ALMA Integration

References

Additional:

• Implementing a DCB client adaptor

• From Contribution to Selectable

• Tracking v3 matrix

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:

1. Alma operator-assigned blocks

2. System-assigned blocks (limits)

3. Overdue blocks due to an overdue item (punitive blocks)

Active patron blocks can be retrieved using the Alma User API > Get user details > user_blocks endpoint. Details can be found here.

• block_type: code of user block type

• block_status: active/inactive

Place Requests

Place request at lending agency

Before placing DCB request at the 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 by using the Rest user API. The mandatory fields for this API are as follows:

• record_type: Public

• primary_id: The primary identifier of the user

• Account_type: External

• User_group (optional): Used in fulfillment policies

• last_name: Used in displays and search

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

Creating an item-level request in Alma

Item-level requests can be created using the Rest User request API. Key parameters and mandatory fields include:

• Parameters:

  • Bib/Holding/Item ID: The bibliographic, holding, or item ID.

  • User_id: The ID of the requesting user.

• Mandatory Fields:

  • request_type: HOLD

  • pickup_location_type: LIBRARY

  • pickup_location_library: The pickup location library code.

  • material_type (optional): Used in fulfillment policies.

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:

1. Create record

• Mandatory Fields:

  • The actual record: XML string describing the record

  • record_format: Default is marc21

  • suppress_from_publishing: default is true

2. Create holding record

• Parameters:

  • mms_id: Bib record ID

• Mandatory Fields:

  • The actual record: XML string describing the record

  • suppress_from_publishing: tbd

3. Create Item

   • Parameters:

     • Barcode

     • physical_material_type

     • policy: Interlibrary Loan

     • location?

Creating an item-level request

Item-level requests can be created using the Rest User Request API. Key parameters and mandatory fields include:

• Parameters:

  • Bib/Holding/Item ID: The bibliographic, holding, or item ID.

  • User_id: The ID of the requesting user.

• Mandatory Fields:

  • request_type: HOLD

  • pickup_location_type: LIBRARY

  • pickup_location_library: The pickup location library code.

  • material_type (optional): Used in fulfillment policies.

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

Circulate Requests

Circulation tracking and reaction (lending)

Workflow diagram

1. Placing the request

When a patron places a DCB request, it goes through initial checks and follows the sequence of status transitions (more details https://openlibraryfoundation.atlassian.net/wiki/x/IYAZqw) :

DCB Status Transition:

• SUBMITTED_TO_DCB,

• PATRON_VERIFIED,

• RESOLVED,

• REQUEST_PLACED_AT_SUPPLYING_AGENCY,

• CONFIRMED,

• REQUEST_PLACED_AT_BORROWING_AGENCY

Alma status updates:

• Request type: Patron physical item request

• Process status: New (Not started)

• Item Status: "Item in place" (indicating the item is currently available on the shelf)

2. Item is sent out to the borrowing agency

Alma updates:

• Request status: In progress

• Item status: Transit

DCB status transition:

• Transaction status changes on PICKUP_TRANSIT

3. Item received in borrowing agency:

DCB status transition:

• Transaction status changes to RECEIVED_AT_PICKUP > READY_FOR_PICKUP

Alma updates:

• No status updates

4. Item is loaned in borrowing agency:

DCB status transition:

• Transaction status changes to LOANED

• A loan is created in Alma.

Alma status updates:

• Request status: In progress

• Item status: Loan

• Loan is created

Alma loan creation

To create the loan in Alma, the Rest Item Loan API is used with the following parameters and fields:

Parameters:

• User_id: The ID of the requesting user.

• item_pid or item_barcode: Item ID or barcode must be supplied

 Mandatory Fields:

• circ_desk: Circulation desk code (DCB parameter?)

• library: Library code responsible for the loan (lending agency?)

• request_id

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

5. Item returned at the borrowing library

DCB status transition:

• Transaction status changes to RETURN_TRANSIT

Alma updates:

• No status updates

6. Item returned to the lending library (scan item at lending library):

Alma status updates:

• Request status: Closed?

• Item status: Item in place

•  Loan is closed

DCB status transition:

• Transaction status changes to COMPLETED          

Circulation tracking and reaction (borrowing)

tbd

Finalization

In Alma, request cancellation can be performed automatically by REST API, manually in Alma by a staff member.

Cancel user request by API

API key parameters and mandatory fields include:

• Parameters:

  • user_id: The ID of the requesting user.

  • request_id: A unique identifier of the request that should be canceled.

• Mandatory Fields:

  • reason: CancelledAtPatronRequest

For more details on cancellation request by API can be found here

Cancel user request manually in Alma

When a request is cancelled manually in Alma, the user performing the cancellation must specify a reason for the cancellation by selecting one from a list of possible reasons (see, Default request-cancellation reasons). The options that appear in this list are defined in a code table. Initially, the code table contains a default list of reasons, each of which is identified by a code and a description.