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.

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

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 types of active blocks include:

Alma operator-assigned blocks
System-assigned blocks (limits)
Overdue blocks due to an overdue item (punitive blocks)

Check for Patron Blocks

Endpoint:

GET /almaws/v1/users/{user_id}

Key Field:

user_block: Provides details about active blocks on the user's account.

Example Request:

http
GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/users/12345678?apikey={your_api_key}

Example Response:

json
{
  "primary_id": "12345678",
  "first_name": "John",
  "last_name": "Doe",
  "user_block": [
    {
      "block_type": "General",
      "description": "User has overdue items",
      "status": "Active"
    }
  ],
  "user_status": "Active"
}

Details can be found here.

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.

Creating a virtual patron in Alma

A virtual patron in Alma can be created using the Create a 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

Search for a user in Alma

Retrieve User API allows to look up a user by their primary ID, barcode, or email address.

Endpoint

GET /almaws/v1/users/{user_id}

Parameters

user_id: The user's unique identifier in Alma. This can be their primary ID, barcode, or email address.

Creating an item-level request in Alma

Create a Request API allows to create an Item-level requests.

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.

Key parameters and mandatory fields include:

user_primary_id: The ID of the requesting user.
request_type: HOLD
pickup_location_type: LIBRARY
pickup_location_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.)
material_type (optional): Used in fulfillment policies.

Hold request example

http
POST https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/123456789/holdings/987654321/items/567890123/requests?apikey={your_api_key}
{
  "user_primary_id": "patron123",
  "request_type": "HOLD",
  "pickup_location_type": "LIBRARY",
  "pickup_location_library": "Main Library",
  "comment": "Requesting for research purposes."
}

For more details on creating a request for an item, refer to Create request for an Item

Alma request details

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.

Creating a virtual item in Alma

A virtual item in Alma can be created by using the following APIs:

Create an Item API allows to add an item to a specific bibliographic record and holding

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:

Barcode
physical_material_type
policy: Interlibrary Loan
location?: The item's shelving location
library: The library where the item is located.

Example request:

Notes:

Barcodes must be unique across Alma. If the barcode already exists, the request will fail
Library and location codes must match valid configurations in Alma.
The mms_id and holding_id should correspond to existing records.

For more details on creating an item, refer to Create Item.

Create a Bibliographic Record API

API Endpoint

POST /almaws/v1/bibs

Key Fields:

The MARC XML structure should follow the standard MARC21 format.
suppress_from_publishing: default is true

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

Create a Holding Record API

API Endpoint

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

Parameters:

mms_id: Bib record ID

Key Fields:

The actual record: XML string describing the record
- suppress_from_publishing: tbd

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: Request status: In progress (Transit item) Item status: Transit	Trigger DCB `HandleSupplierInTransit` event to change Borrowing or Pickup Library transaction state = `OPEN` 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 = `AWAITING_PICKUP`	Trigger `HandleBorrowerItemOnHoldShelf` event to change Borrowing or Pickup Library transaction state =`AWAITING_PICKUP` DCB `PatronRequest.READY_FOR_PICKUP` `HostLmsItem.ITEM_ON_HOLDSHELF` Alma Supplying Library : On hold shelf / 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 = `ITEM_CHECKED_OUT`	Trigger `HandleBorrowerItemLoaned` event to change Borrowing or Supplying Library transaction state = `ITEM_CHECKED_OUT` DCB `PatronRequest.LOANED` `HostLmsItem.ITEM_LOANED` Alma Supplying Library: 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 = `ITEM_CHECKED_IN`	Trigger `HandleBorrowerRequestReturnTransit` event to change at Borrowing or Pickup Library transaction state = `ITEM_CHECKED_IN` loan status = `Closed` virtual item status = `In transit` 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 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 = `CLOSED` DCB `PatronRequest.COMPLETED` `HostLmsItem.ITEM_AVAILABLE` Local status on supplier request changed to `AVAILABLE`

Workflow diagram

Alma loan creation

Create Loan API allows to create a loan record for a patron.

API Endpoint

POST /almaws/v1/loans

Parameters:

item_barcode: The barcode of the item being loaned.
patron_id: The ID of the patron who is borrowing the item.

Key Fields:

circ_desk: Circulation desk code (DCB parameter?)
library: Library code responsible for the loan (lending agency?)
request_id
due_date (optional)
loan_policy (optional)

Example Request

Basic Loan Request:

Loan with Policy:

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

Circulation tracking and reaction (borrowing)

tbd

Finalization

Common Request Closure Statuses in Alma

Completed. The request has been successfully fulfilled.
Canceled. The request has been canceled, either manually by a user/staff member or automatically by the system.
Expired. The request has expired without being fulfilled, based on library-defined expiration rules.
Rejected. The request was rejected by library staff or the system due to eligibility, policy, or technical reasons.
Failed. The request could not be fulfilled due to a failure in the process.
Hold Shelf Expired. The item was placed on the hold shelf but was not picked up within the designated time frame.

Retrieving Request Closure Status via API

Endpoint:

GET /almaws/v1/bibs/{mms_id}/requests

Example Request:

Key Fields in Response:

request_status: Shows the current or final status of the request.
expiry_date: Indicates the expiration date, if applicable.
pickup_location: Provides the location where the item was to be picked up.

Example Response:

Cancel a request in Alma via the API

Endpoint:

DELETE /almaws/v1/bibs/{mms_id}/requests/{request_id}

Required Parameters

mms_id: The bibliographic record ID of the item for which the request was made.
request_id: The unique identifier of the request to be canceled.

Required Parameters

mms_id: The bibliographic record ID of the item for which the request was made.
request_id: The unique identifier of the request to be canceled.

Example Request

Default request-cancellation reasons