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}

{
  "item_data": {
    "pid": "987654321",
    "title": "Sample Title",
    "description": "Sample Item Description",
    "suppress_from_publishing": true,
    "library": {
      "value": "MAIN",
      "desc": "Main Library"
    },
    "location": {
      "value": "STACKS",
      "desc": "Stacks"
    },
    "barcode": "12345678901234"
  }
}

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

{
  "holding_data": {
    "holding_id": "234567890",
    "suppress_from_publishing": false,
    "call_number": "QA76.73.P98 C48 2023",
    "location": {
      "value": "STACKS",
      "desc": "Stacks"
    }
  }
}

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

{
  "bib_data": {
    "mms_id": "123456789",
    "title": "Sample Bibliographic Title",
    "suppress_from_publishing": false,
    "record_format": "MARC21"
  }
}

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)

{
  "primary_id": "567890123",
  "first_name": "John",
  "last_name": "Doe",
  "user_group": {
    "value": "STUDENT",
    "desc": "Student"
  },
  "status": {
    "value": "ACTIVE",
    "desc": "Active"
  },
  "expiry_date": "2025-12-31",
  "user_blocks": {
    "total_record_count": 1,
    "user_block": [
      {
        "block_type": {
          "value": "OVERDUE",
          "desc": "Overdue item"
        },
        "block_description": "Overdue book on account",
        "status": {
          "value": "ACTIVE",
          "desc": "Active"
        }
      }
    ]
  },
  "fees": {
    "total_fines": "25.00",
    "currency": "USD"
  },
  "rs_library": {
    "value": "RS_MAIN",
    "desc": "Resource Sharing Main Library"
  }
}

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

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/users?q=primary_id~123456&view=brief&apikey={your_api_key}

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 )

Error code	Error message descroption

Error code	Error message descroption
402210	User with the same primary ID already exists.
400001	Required field is missing (e.g., `primary_id`, `first_name`, etc.).
401045	Invalid email format.
401040	Invalid or unrecognized user group value.
400004	Expiry date is in an invalid format or is in the past.

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.

{
  "user_primary_id": "12345",
  "request_type": "HOLD",
  "pickup_location_type": "LIBRARY",
  "pickup_location_library": "MAIN",
  "pickup_location": "MAIN",
  "comment": "Hold request for patron"
}

{
  "request_id": "987654321",
  "user_primary_id": "12345",
  "request_type": {
    "value": "HOLD",
    "desc": "Hold Request"
  },
  "request_status": {
    "value": "Not Started",
    "desc": "Request not yet started"
  },
  "pickup_location": {
    "value": "MAIN",
    "desc": "Main Library"
  },
  "item_id": "987654321",
  "comment": "Hold request for patron"
}

Error Code	Error Message Description

Error Code	Error Message Description
401880	The user ID is invalid or not found in Alma.
401124	The item ID is invalid or not found.
402246	Request type is not allowed for the specified item.
401649	User is not eligible to place the request.

The initial request_status will typically be Not Started, and Alma will update this as the request progresses.

Not Started:
- Description: The request has been created but has not yet been acted upon.
- Typical Use Case: This is the initial state for new requests, waiting for staff or system action to process the request.
In Process:
- Description: The request is actively being processed.
- Typical Use Case: Staff or an automated system is handling the request. For example: retrieving the item from shelves, preparing the item for shipping, scanning or transferring the item.
On Hold Shelf:
- Description: The requested item is ready for the patron to pick up at the designated location.
- Typical Use Case: The item has been retrieved, processed, and placed in the "Hold Shelf" area of the specified library or circulation desk.ed out.
History:
- Description: The request has been completed, canceled, or expired and is no longer active.
- Typical Use Case: The patron picked up the item (and the loan is recorded in circulation); the request was canceled by the patron or library staff; the request expired before it could be fulfilled.

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.

{
  "user_primary_id": "12345",
  "request_type": "HOLD",
  "pickup_location_type": "LIBRARY",
  "pickup_location_library": "MAIN",
  "pickup_location": "MAIN",
  "comment": "Hold request for patron",
  "item_id": "987654321"
}

{
  "user_primary_id": "12345",
  "request_type": "HOLD",
  "pickup_location_type": "LIBRARY",
  "pickup_location_library": "MAIN",
  "pickup_location": "MAIN",
  "comment": "Place a hold request for the patron",
  "item_id": "987654321"
}

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}

{
  "item_data": {
    "pid": "333444555666",
    "barcode": "123456789",
    "description": "Vol. 1",
    "policy": {
      "value": "REGULAR",
      "desc": "Regular Loan"
    },
    "physical_material_type": {
      "value": "BOOK",
      "desc": "Book"
    },
    "library": {
      "value": "MAIN",
      "desc": "Main Library"
    },
    "location": {
      "value": "STACKS",
      "desc": "Stacks"
    },
    "holding_id": "222333444555",
    "mms_id": "991234567890123"
  },
  "holding_data": {
    "holding_id": "222333444555",
    "call_number": "QA76.73.J38",
    "location": {
      "value": "MAIN",
      "desc": "Main Library"
    }
  },
  "bib_data": {
    "mms_id": "991234567890123",
    "title": "Introduction to Library Science",
    "author": "Jane Doe",
    "isbn": "9781234567890"
  }
}

Error Code	Description

Error Code	Description
401123	The barcode does not match any item in Alma
401124	The barcode is invalid or not recognized

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.

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/tasks/requests?item_barcode=1234567890

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/items?mms_id=991234567890123

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/items?mms_id=991234567890123&holding_id=22334455

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/items?library=MAIN

{
  "total_record_count": 1,
  "item": [
    {
      "bib_data": {
        "mms_id": "123456789",
        "title": "Sample Book Title",
        "author": "John Doe",
        "publisher": "Sample Publisher"
      },
      "holding_data": {
        "holding_id": "987654321",
        "permanent_call_number": "QA76.73.J38"
      },
      "item_data": {
        "pid": "5678901234",
        "barcode": "123456789",
        "location": {
          "value": "MAIN",
          "desc": "Main Library"
        },
        "base_status": {
          "value": "1",
          "desc": "Item in place"
        },
        "process_type": {
          "value": "LOAN",
          "desc": "Checked Out"
        },
        "due_date": "2025-01-31T23:59:00Z"
      }
    }
  ]
}

Error code	Description

Error code	Description
`401650`	Invalid or nonexistent MMS ID
`401651`	Barcode not found in the system

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.