ALMA Integration

References

Additional:

Overview

This document outlines the requirements and workflows needed to integrate Alma with the DCB service to support Alma bibliographic data ingestion, patron verification, request placement, circulation tracking, and request finalization in OpenRS.

1 Overview
2 Ingest and Suppression
- 2.1 Item availability
- 2.2 Suppression Value
3 Patron verification
- 3.1 Authentication
- 3.2 Eligibility
4 Place Requests
- 4.1 Place request at lending agency
  - 4.1.1 Search for a user in Alma
  - 4.1.2 Creating a virtual patron in Alma
  - 4.1.3 Creating an item-level request in Alma
  - 4.1.4 Request details in the Alma app
- 4.2 Place request at borrowing agency
  - 4.2.1 Search for an item in Alma
  - 4.2.2 Create a virtual Item record
  - 4.2.3 Create Bibliographic record
  - 4.2.4 Create Holding record
5 Circulate Requests
- 5.1 Circulation tracking and reaction (lending)
- 5.2 Circulation tracking and reaction (borrowing)
- 5.3 Alma loan creation
- 5.4 Update a request status
- 5.5 Update item status
- 5.6 Request cancellation
  - 5.6.1 Retrieve the status of a request
  - 5.6.2 Cancel a request in Alma
- 5.7 Renew a loan
- 5.8 Data Deletion
  - 5.8.1 Delete an item
  - 5.8.2 Delete a user
  - 5.8.3 Delete a request

Ingest and Suppression

Alma supports the OAI-PMH mechanism for harvesting bibliographic records. For more details on the OAI-PMH Alma integration, refer to the official documentation: OAI-PMH Alma Integration

Item availability

In Alma, an item's circulation availability status can be retrieved using the Retrieve Item API

Endpoint: GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}

Key field for availability status

base_status: Provides the item's current status, such as:

1: Item is available (available on shelf).
0: Item is unavailable (checked out, in transit, or being processed).

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/123456789/holdings/987654321/items/567890123?apikey={your_api_key}

{
  "item_data": {
    "pid": "567890123",
    "barcode": "12345678901234",
    "base_status": {
      "value": "0",
      "desc": "Item in place"
    },
    "process_type": {
      "value": "LOAN",
      "desc": "On loan"
    },
    "due_back_date": "2025-02-01T23:59:59Z"
  },
  "holding_data": {
    "holding_id": "987654321",
    "call_number": "QA76.73.J38 2020",
    "location": {
      "value": "STACKS",
      "desc": "Stacks"
    }
  }
}

Status	Description	Field to Check

Status	Description	Field to Check
Available/On shelf	Item is on shelf and ready for loan	`base_status.value = 1`, `process_type.value = AVAILABLE` (or empty)
Checked Out	Item is on loan to a patron	`base_status.value = 0`, `process_type.value = LOAN` `due_date`: contains the due date
In Transit	Item is moving between locations	`base_status.value = 0`, `process_type.value = TRANSIT`
Requested	Whether the item has been requested	`requested`: `true`

Item in Place: The item is on the shelf and available for loan. This is the default status for items that are not checked out, on hold, or in transit.
Checked Out: The item is currently on loan to a patron.
On Hold Shelf: The item has been requested by a patron and is ready for pickup at the specified hold shelf location. Reserved for a patron; not available for others.
In Transit: The item is being transported between library locations. Common for inter-library transfers or when items are returned to a different location.
Missing: The item is marked as lost or not found on the shelf after a search. Used when inventory checks reveal the item is missing.
Lost: The item is declared lost, typically after being overdue for an extended period.
Claimed Returned: The patron claims to have returned the item, but it is not found in the library.
Withdrawn: The item is no longer part of the collection (deaccessioned).
Binding: The item is sent for binding.Indicates the item is temporarily unavailable for use.
Technical - Migration: Items assigned this status during system migration or cataloging activities.
Repair: The item is under repair: Temporarily unavailable until repaired.
Acquisition: The item is newly acquired and not yet processed for circulation. Items awaiting cataloging or physical processing.
Processing: The item is being cataloged or processed for circulation. Temporary status during cataloging workflows.
In Transit for Reshelving: The item is being returned to its original shelf location. Used during returns or after in-library use.
Requested: The item has been requested by a patron or library staff. Blocks others from borrowing the item.

Suppression Value

In Alma, the suppression value indicates whether a bibliographic, holdings, or item record is suppressed from discovery. This information is accessible through the Alma APIs.

The suppression value is in the field suppress_from_publishing:

true: suppressed from publishing.
false: is not suppressed and is visible in discovery systems.

1. Retrieve Item API endpoint: /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/123456789/holdings/234567890/items/987654321?apikey={your_api_key}

2. Retrieve Holdings API endpoint: /almaws/v1/bibs/{mms_id}/holdings/{holding_id}

3. Retrieve Bibliographic Record API endpoint: /almaws/v1/bibs/{mms_id}

Patron verification

Authentication

Alma supports the SAML 2.0 Web Browser SSO profile for user authentication and authorization. Further information on this integration can be found here:
SAML Authentication.

Eligibility

After the patron has been successfully authenticated, DCB must determine if the patron is eligible to place a request. The patron is eligible if the following conditions are met:

Alma patron record is active.
Alma patron record does not have any active patron blocks.

The Users API allows to retrieve information about a patron's account and determine their eligibility.

Endpoint: GET /almaws/v1/users/{user_id}

Key fields:

Account Status (status): Indicates whether the account is active or inactive.
- ACTIVE: The patron is eligible.
- INACTIVE: The patron is not eligible.
Blocks (user_block): Lists any blocks on the patron's account
User account type (account_type): Two basic types of user accounts in Alma are internal and external users
Home library code (rs_libraries): List of the user's related resource-sharing libraries.
Patron type (user_group)

Place Requests

Place request at lending agency

Before placing DCB request in Alma as a lending agency, a virtual patron needs to be found or created in Alma.

Search for a user in Alma

The Users API allows to find user details based on various search criteria such as primary ID, name, email, or user group.

Endpoint: GET /almaws/v1/users/

Parameters: The query string in the format field~value

Creating a virtual patron in Alma

A virtual patron in Alma can be created using the User API.

Endpoint: POST /almaws/v1/users

The minimum required fields are primary_id, first_name, last_name, and user_group.

record_type: Public
primary_id: The primary identifier of the user
first_name: User's first name.
last_name: User's last name.
account_type: External
user_group: Used in fulfillment policies (which one to choose or DCB should create )

For more details on creating a user, refer to Create user API

Creating an item-level request in Alma

Create request for an Item API allows to create an Item-level requests in Alma.

Endpoint: POST /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}/requests

Required parameters:

mms_id: The unique identifier of the bibliographic record.
holding_id: The ID of the holding record associated with the item.
item_pid: The unique identifier of the physical item.

Request body fields:

Field	Description

Field	Description
`user_primary_id`	The primary ID of the user making the request, must be a valid user ID in Alma.
`request_type`	`HOLD`
`pickup_location_type`	Type of pickup location (e.g., LIBRARY). The pickup location library code. (Note: Alma does not provide a direct API endpoint to create pickup locations dynamically. Pickup locations are defined and configured in the Alma interface by library administrators.)
`pickup_location_library`	Code of the library where the item will be picked up.
`pickup_location`	Pickup location code.
`material_type` (optional)	Optional; used in fulfillment policies.

Endpoint: POST /almaws/v1/bibs/{mms_id}/requests

Request body fields:

Field	Description

Field	Description
`user_primary_id`	The primary ID of the user making the request.
`request_type`	The type of request. `HOLD`
`pickup_location_type`	Type of pickup location. `LIBRARY`
`pickup_location_library`	Code of the library where the item will be picked up. (for `HOLD` requests).
`pickup_location`	Pickup location code.
`item_id`	The ID of the specific item being requested.
`comment`	Optional comments related to the request.

To retrieve details about an item's bib and holding records can be used the Items API

Endpoint: GET /almaws/v1/items?item_barcode={barcode}

Request details in the Alma app

Once a request is created in Alma, it will have a unique ID and include the following information:

Request type: Patron physical item request
Item's status: Item in place
Pickup at: Pickup location
Item material type
Workflow step: Pickup from shelf
Process status: New (Not started)
Managed by Library: The library where the available inventory is located
Managed by Desk: The circulation desk where the available inventory is located

Place request at borrowing agency

Before placing DCB request at the borrowing agency, a virtual item needs to be found or created in Alma.

Search for an item in Alma

The Search API can be used to search for an item in Alma, if you don’t have mms_id, holding_id, or item_pid.

Endpoint: GET /almaws/v1/items

Query parameters:

Parameter	Description

Parameter	Description
`mms_id`	The MMS ID of the bibliographic record.
`holding_id`	The holding record ID.
`item_barcode`	The barcode of the specific item.
`library`	The library code.

Create a virtual Item record

A virtual item in Alma can be created by using Create an Item API

Endpoint: POST /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items

Required parameters:

mms_id: The unique identifier of the bibliographic record.
holding_id: The ID of the holding record where the item will be added.

Key fields:

Field	Description

Field	Description
`Barcode`	The barcode for the new item (must be unique).
`description`	A description of the item (e.g., "Volume 1").
`physical_material_type`	Type of physical material (e.g., `BOOK`, `DVD`).
`location`	Location in the library (e.g., `STACKS`).
`call_number`	Call number of the item (e.g., `QA76.73.P98`).
`status`	The status of the item (e.g., `IN_PLACE`).
`policy`:	Interlibrary Loan
`library`:	The library where the item is located.

Create Bibliographic record

Endpoint: POST /almaws/v1/bibs

For more details on creating a bibliographic record, refer to Create record

Create Holding record

Endpoint: POST /almaws/v1/bibs/{mms_id}/holdings

Parameters:

mms_id: Bib record ID

For more details on creating a holding record, refer to Create holding record

Circulate Requests

Circulation tracking and reaction (lending)

Lifecycle	Given	When	Then

Lifecycle	Given	When	Then
Dispatched by Supplying Library Trigger: Manual action in Alma - Scan in items	DCB Patron Request exists in status `REQUEST_PLACED_AT_BORROWING_AGENCY`	DCB Patron Request Workflow matches corresponding request details at Alma Supplying Library: transaction state = `PICKUP_TRANSIT` Request status: In progress (Transit item) Item status: Transit	Trigger DCB `HandleSupplierInTransit` event to change Borrowing or Pickup Library transaction state =`PICKUP_TRANSIT` DCB `PatronRequest.PICKUP_TRANSIT` `HostLmsItem.ITEM_PICKUP_TRANSIT`
Received at Pickup Library	DCB Patron Request exists with corresponding `HostLmsItem.ITEM_PICKUP_TRANSIT`	DCB Patron Request Workflow matches corresponding request details at Pickup Library transaction state = `RECEIVED_AT_PICKUP` `READY_FOR_PICKUP`	Trigger `HandleBorrowerItemOnHoldShelf` event to change Borrowing Library transaction state =`RECEIVED_AT_PICKUP` `READY_FOR_PICKUP` DCB `PatronRequest.READY_FOR_PICKUP` `HostLmsItem.ITEM_ON_HOLDSHELF` Alma Supplying Library: Request status: On Hold Shelf Item status: On Hold Shelf transaction state =`RECEIVED_AT_PICKUP` `READY_FOR_PICKUP`
Item Checked Out to Patron at Pickup Library	DCB Patron Request exists with corresponding `HostLmsItem.ITEM_ON_HOLDSHELF`	DCB Patron Request Workflow matches corresponding request details at Pickup Library transaction state = `LOANED`	Trigger `HandleBorrowerItemLoaned` event to change Borrowing Library transaction state = `LOANED` DCB `PatronRequest.LOANED` `HostLmsItem.ITEM_LOANED` Alma Supplying Library: transaction state = `LOANED` Request status: Completed Item status: Loan Loan status: Active, the item is checked out to a patron.
Item Returned by Borrowing Patron	DCB Patron Request exists in status with corresponding `HostLmsItem.ITEM_LOANED`	DCB Patron Request Workflow matches corresponding request details at either Pickup or Borrowing Library transaction state = `RETURN_TRANSIT`	Trigger `HandleBorrowerRequestReturnTransit` event to change at DCB `PatronRequest.RET-TRANSIT` `HostLmsItem.ITEM_RETURNED` Alma Supplying Library: no changes
Received Back at Lending Agency Trigger: Manual action in Alma - Return items	DCB Patron Request exists in status with corresponding `HostLmsItem.ITEM_RETURNED`	DCB Patron Request Workflow matches corresponding request details at either Alma Supplying Library transaction state = `COMPLETED` Item status: Item in place /Transit for Reshelving Loan status: In Transit: If the item is returned to a non-owning branch and is being sent back to its home location Returned: The item has been returned to the library and is no longer checked out.	Trigger `HandleBorrowerRequestReturnTransit` event to change Borrowing or Pickup Library transaction state = `COMPLETED` DCB `PatronRequest.COMPLETED` `HostLmsItem.ITEM_AVAILABLE` Local status on supplier request changed to `AVAILABLE`

Lending workflow diagram

Circulation tracking and reaction (borrowing)

Lifecycle	Given	When	Then

Lifecycle	Given	When	Then
Dispatched by Supplying Library	DCB Patron Request exists in status `REQUEST_PLACED_AT_BORROWING_AGENCY`	DCB Patron Request Workflow matches corresponding request details at Supplying Library transaction status = `PICKUP_TRANSIT`	Trigger DCB `HandleSupplierInTransit` event to change Pickup Library transaction status = `PICKUP_TRANSIT` DCB `PatronRequest.PICKUP_TRANSIT` `HostLmsItem.ITEM_PICKUP_TRANSIT` Alma Borrowing Library: transaction status = `PICKUP_TRANSIT` Request status: In progress (Transit item) Item status: Transit
Received at Borrowing Library	DCB Patron Request exists with corresponding `HostLmsItem.ITEM_PICKUP_TRANSIT`	DCB Patron Request Workflow matches corresponding request details at Alma Borrowing Library Request status: On Hold Shelf Item status: On Hold Shelf transaction state =`ON_HOLD_SHELF`	Supplying or Pickup Library transaction state =`RECEIVED_AT_PICKUP` `READY_FOR_PICKUP` DCB `PatronRequest.READY_FOR_PICKUP` `HostLmsItem.ITEM_ON_HOLDSHELF`
Item Checked Out to Patron at Pickup Library	DCB Patron Request exists with corresponding `HostLmsItem.ITEM_ON_HOLDSHELF`	DCB Patron Request Workflow matches corresponding request details at Alma Borrowing Library: transaction state = `LOANED` Request status: Completed Item status: Loan Loan status: Active, the item is checked out to a patron.	Trigger `HandleBorrowerItemLoaned` event to change Supplying or Pickup Library transaction state = `LOANED` DCB `PatronRequest.LOANED` `HostLmsItem.ITEM_LOANED`
Item Returned by Borrowing Patron	DCB Patron Request exists in status with corresponding `HostLmsItem.ITEM_LOANED`	DCB Patron Request Workflow matches corresponding request details at either Alma Borrowing Library: transaction state = `RETURN_TRASIT` Item status: Item in place /Transit for Reshelving Loan status: In Transit: If the item is returned to a non-owning branch and is being sent back to its home location Returned: The item has been returned to the library and is no longer checked out.	Trigger `HandleBorrowerRequestReturnTransit` event to change Supplying or Pickup Library transaction state = `RETURN_TRASIT` DCB `PatronRequest.RET-TRANSIT` `HostLmsItem.ITEM_TRANSIT` or `HostLmsItem.ITEM_RETURNED`
Received Back at Lending Agency	DCB Patron Request exists in status with corresponding `HostLmsItem.ITEM_RETURNED`	DCB Patron Request Workflow matches corresponding request details at either Supplying Library transaction state = `COMPLETED` item status = `Available`	Trigger `HandleBorrowerRequestReturnTransit` event to change Borrowing or Pickup Library transaction state = `COMPLETED` DCB `PatronRequest.COMPLETED` `HostLmsItem.ITEM_AVAILABLE`

Borrowing workflow diagram

Alma loan creation

The Loan API can be used to create a loan in Alma. This operation requires providing the patron ID and item barcode.

Endpoint: POST /almaws/v1/users/{user_id}/loans

Key fields in the response

Field	Description

Field	Description
`loan_id`	The unique identifier for the loan
`item_barcode`	The barcode of the item being loaned
`due_date`	The date and time when the item is due
`loan_status`	The status of the loan (`ACTIVE`)
`user_id`	The ID of the user to whom the item was loaned

Additional notes

Loan Policy: Alma's loan rules are determined by the library's fulfillment configuration, which includes item type, user type, and location.
Due Date: Alma automatically calculates the due date based on the fulfillment policies.

Update a request status

You can use the Requests API to update the status of a specific request. This operation is typically used to change the progress of a request, such as moving it to "On Hold Shelf" or marking it as "Fulfilled."

Endpoint: PUT /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}/requests/{request_id}

Key fields in the response

Field	Description

Field	Description
`request_id`	The unique identifier of the request
`status`	The updated status of the request (e.g., `FULFILLED`).
`pickup_location`	The pickup location for the request
`user_id`	The ID of the user associated with the request
`item_barcode`	The barcode of the item associated with the request

Update item status

The Item API can be used to update the status of an item

Endpoint: PUT /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}

Key fields in the response

Field	Description

Field	Description
`mms_id`	The ID of the bibliographic record
`holding_id`	The ID of the holding record
`pid`	The ID of the item record
`process_type`	The updated process type for the item
`base_status`	The availability status of the item

Request cancellation

Retrieve the status of a request

The Retrieve Request API can be used to retrieve the status of a request. Canceled requests will have a status value of CANCELED.

Endpoint: GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}/requests/{request_id}

Cancel a request in Alma

The Requests API can be used to cancel a request in Alma.

Endpoint: POST /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}/requests/{request_id}?op=cancel

Query parameter:

Parameter	Value	Description

Parameter	Value	Description
`op`	`cancel`	Indicates that the operation is to cancel the request.

The request body can optionally include a reason for cancellation

Key fields in the response

Field	Description

Field	Description
`request_id`	The unique identifier of the canceled request
`status`	The updated status of the request (e.g., `CANCELED`)
`reason`	The reason provided for canceling the request
`used_id`	The ID of the user associated with the request
`item_barcode`	The barcode of the item associated with the request

Renew a loan

The Loan Renewal API allows to renew a loan for a specific user and item.

Endpoint: POST /almaws/v1/users/{user_id}/loans/{loan_id}?op=renew

Query parameter:

Parameter	Value	Description

Parameter	Value	Description
`op`	`renew`	Indicates that the operation is to renew a loan

A body is not required for the renewal request unless additional details are necessary. If needed, you can include optional parameters such as comments.

A successful response confirms the loan has been renewed and provides updated details about the loan, such as the new due date.

Key fields in the response

Field	Description

Field	Description
`loan_id`	ID of the loan
`user_id`	ID of the user who borrowed the item
`item_barcode`	item barcode
`loan_date`	The date and time the loan started
`due_date`	The new due date for the loan
`renewal_count`	The number of times the loan has been renewed

Additional Notes

Eligibility: Not all loans are renewable. Items with active holds, recalls, or that exceed the renewal limit may not be renewed.
Renewal Limits: Alma enforces renewal policies based on the configuration for user groups, item policies, and loan terms.

Data Deletion

Delete an item

The Items API can be used to delete an item.

Endpoint: DELETE /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}

If the item is successfully deleted, the API will return an HTTP status code 204 No Content, with no response body.

Preconditions for Deletion

No active loans: Items with active loans cannot be deleted.
No open requests: Cancel or close any requests linked to the item before deletion.
Unsuppressed from publishing: Ensure the item is not suppressed if it is required for other records.

Delete a user

The Users API can be used to delete a user in Alma.

Endpoint: DELETE /almaws/v1/users/{user_id}

If the user is successfully deleted, the API will return an HTTP status code 204 No Content, with no response body.

Preconditions for Deletion

No active loans: Users with active loans cannot be deleted.
No open requests: Cancel or close any requests linked to the user.
Linked data: Ensure the user has no unresolved fines, fees, or other dependencies.

Delete a request

The Requests API can be used to delete a request.

Endpoint: DELETE /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}/requests/{request_id}

If the request is successfully deleted, the API will return an HTTP status code 204 No Content, with no response body.

Preconditions for Deletion

Unfulfilled requests: The request must not already be fulfilled or completed.
Request ID: Ensure you have the correct request_id to delete the specific request.
Linked dependencies: Verify that deleting the request will not impact ongoing workflows.