DCB Alma Adapter (as of DCB Service 8.47.0)

The Alma adapter enables end-to-end resource-sharing with Alma systems. It supports live item availability, patron ops, hold placement at the correct agency, loans/renewals, and basic create/delete flows for bibs/holdings/items. The integration of Alma has been derived from ExLibris REST APIs documentation (found here: https://developers.exlibrisgroup.com/alma/apis/ ).

Supported Scenarios

• Live availability (items per bib, mapped to DCB status & enriched with agency + item-type)

• Place hold

  • At supplying agency (uses configured “DCB sharing library”)

  • At borrowing agency (library derived from pickup Location.localId)

  • At local agency (same as borrowing agency)

• Checkout to patron (creates Alma loan with circ desk + library + request linkage)

• Renew loan (find matching loan for item - renew)

• Cancel hold (user request delete)

• Patron ops: create, update (group), auth, delete, get by id/identifier

• Bib/holding/item ops: create bib, create holding (impl in client), delete item/holding, delete bib

• Config discovery: fetch libraries/locations (grouped) to drive setup

How It Works (Implementation Notes)

• HTTP client & auth - All calls use apikey <KEY> header against Alma AWS v1; base URL resolved from HostLms config.

• Availability mapping – For a bib (MMS ID), fetch holdings - items; map Alma process_type and base_status to DCB item status (AVAILABLE/LOANED/TRANSIT/etc). Due-back date and location are also mapped; item then enriched with agency and item-type via mapping services.

• Hold placement - Builds Alma HOLD request with pickupLocationType=LIBRARY and the library code resolved by context:

  • Supplying: configured DCB Sharing Library Code.

  • Borrowing/Local: derived from Location.localId.
    Errors parse Alma’s structured error payloads for troubleshooting.

• Checkout - Creates a user loan with configured circ desk and passed library code, linking to the local request ID.

• Renew - Lists user loans, matches by item ID, then op=renew.

• Patron creation - Requires barcode and/or external ID; multiple barcodes may not be supported by Alma. Patron type (user_group) is mapped from canonical via reference value mappings.

• Location/circ-desk lookups - Libraries and locations are fetched; when ambiguous or CLOSED, the adaptor falls back to a configured default patron location code. Circ-desk - location mapping prefers an OPEN location, then REMOTE, else default.

Alma API Calls Used:

Users & Authentication

• GET /almaws/v1/users/{user_id} - getUserDetails: resolves patrons by local ID / identifier; also used before updates. Called from getPatronByLocalId, getPatronByIdentifier, and updatePatron.

• GET /almaws/v1/users/{user_id}?password=… - authenticateOrRefreshUser: barcode + secret auth; used by patronAuth.

• PUT /almaws/v1/users/{user_id} - updateUserDetails: updates patron (swap-all); used by updatePatron.

• DELETE /almaws/v1/users/{user_id} - deleteUser: deletes patron; used by deletePatron.

Requests (Holds)

• POST /almaws/v1/users/{user_id}/requests?item_pid=… - createUserRequest: places a hold; used by placeHoldRequestAtSupplyingAgency, placeHoldRequestAtBorrowingAgency, placeHoldRequestAtPickupAgency, placeHoldRequestAtLocalAgency via submitLibraryHold.

• GET /almaws/v1/users/{user_id}/requests/{request_id} - retrieveUserRequest: fetches a specific hold; used by getRequest.

• DELETE /almaws/v1/users/{user_id}/requests/{request_id} - cancelUserRequest: cancels a hold; used by deleteHold and cancelHoldRequest.

Loans

• GET /almaws/v1/users/{user_id}/loans - retrieveUserLoans: lists loans (used to find the loan to renew).

• POST /almaws/v1/users/{user_id}/loans?item_pid=… createUserLoan: checkout; used by checkOutItemToPatron.

• POST /almaws/v1/users/{user_id}/loans/{loan_id}?op=renew - renewLoan: renew a loan; used by the renew flow.

Bibliographic & Inventory

• POST /almaws/v1/bibs - createBibRecord: creates bib; used by createBib.

• POST /almaws/v1/bibs/{mms_id}/holdings - createHoldingRecord: creates holding (first step in virtual-item flow). Used by createItem (via createHolding).

• POST /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items - createItem: creates item under holding; used by createItem.

• GET /almaws/v1/bibs/{mms_id}/holdings - retrieveHoldingsList: lists holdings for a bib; used by getItems.

• GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items - retrieveItemsList: lists items in a holding; used by getItems.

• GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid} - retrieveItem: fetches a single item; used by getItem.

• DELETE /almaws/v1/bibs/{mms_id} - deleteBibRecord: deletes bib; used by deleteBib.

• DELETE /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid} - withdrawItem: deletes item; used by deleteItem.

• DELETE /almaws/v1/bibs/{mms_id}/holdings/{holding_id} - deleteHoldingsRecord: deletes empty holding; used by deleteItem (after item withdrawal).

Setup: Add a New Alma System on DCB

1. Create HostLms with lmsClientClass = org.olf.dcb.core.interaction.alma.AlmaHostLmsClient.

2. Configure required properties (provided via AlmaClientConfig):

   • alma-url (Alma region base) & apiKey with permissions for Users, Requests, BIBs/Holdings/Items, and Conf.

   • dcbSharingLibraryCode (used for SUPPLYING holds).

   • defaultPatronLocationCode (fallback when a location is CLOSED/ambiguous; example default “GTMAIN”).

   • pickupCircDesk (used during checkout and for cross-system pickup resolution; example key “DEFAULT_CIRC_DESK”).

   • userIdentifier type for external IDs (e.g., INST_ID). Optional.

   • itemPolicy default for created items (e.g., BOOK). Optional.

• Reference value mappings

  • Map patronType (DCB - Alma) and itemType (DCB - Alma) in ReferenceValueMapping; missing mappings are treated as errors.

• Locations/Agencies

  • Ensure DCB Location records exist with localId = Alma Library Code so borrowing/local flows can resolve pickup library correctly. Use config discovery to import libraries/locations.

• Local development

  • If testing with the Georgia Tech sandbox, you must confirm that your IP is whitelisted or certain functionality will not work.

    • Developers at Knowledge Integration may need to use the internal VPN.

Testing: The Alma Workflow

When Alma is the supplier

• Place your request in DCB, ensuring that the item/ record you have selected is available at your Alma library.

• The request should now be in the status REQUEST_PLACED_AT_BORROWING_AGENCY.

• Because Alma is the supplier, you will first need to perform a scan-in operation in Alma on the item. Fetch its barcode from DCB Admin - you are looking for the “Local item barcode” under the “Supplying” section of the request page.

  • You can do this in the Alma UI or via the API.

  • If doing this via the API you need to make a POST request to https://your-test-alma/almaws/v1/bibs/bibId/holdings/holdingId/items/itemId?apikey=yourapikey&op=scan&circ_desk=DEFAULT_CIRC_DESK&library=YOUR_SUPPLYING_LIBRARY

    • You may also need to make a request to get the holdings for the bib - this is a get request to bibs/{bibId}/holdings

• Once this has been done, the request should enter PICKUP_TRANSIT. Proceed to your borrowing library and check the item in there: you will then see the request change to READY_FOR_PICKUP.

• When your DCB request is READY_FOR_PICKUP, check the item out at the borrower. DCB will detect this and perform a “virtual checkout” at the Alma supplier.

  • Note: if you see “Virtual checkout failed” in the audit logs at this stage, you should investigate in Alma why the checkout has failed.

• Your DCB request should now have hit LOANED, with checkouts performed at both the borrower and the supplier.

• You are now ready to scan / check the item back in at the borrowing system. This should change to RETURN_TRANSIT.

• You will now need to scan the item in again in Alma. If your return library is different to your supplying library, you should change the “library” parameter to match.

  • For example, on the Georgia Tech system the supplying library can be GTMAIN, and the return library may be GTLSC.

Known Issues / Gaps

• Update hold request: not implemented (returns NotImplemented). Needed for PUA workflow.

• Update item status: placeholder (returns “OK” - used to progress DCB workflow pending Alma-specific approach).

• Prevent renewal on loan: not implemented.

• Cancel hold: implemented via user request delete, but note in code that Alma status update nuances may still be needed.

• Supplier preflight: stubbed to true

• Patron creation: requires at least one barcode or external ID; multiple barcodes may not be supported.

• Location resolution: if multiple or CLOSED, adaptor falls back to default; verify defaults per site.

• Hold count: To prevent breaking EBSCO Locate, this was set to 0. https://openlibraryfoundation.atlassian.net/browse/DCB-2046 was created for this work.

Current bugs (WIP):

• https://openlibraryfoundation.atlassian.net/browse/DCB-2015

• https://openlibraryfoundation.atlassian.net/browse/DCB-2065

Current known issues (WIP)

• https://openlibraryfoundation.atlassian.net/browse/DCB-2046 - Hold counts are always set to 0

Common issues

• If the config above is not set correctly in the Host LMS in DCB, the following errors will happen.

  • "Missing required configuration property: \"sharing-library-code\""

    • Update the Host LMS to add the sharing library code. RES_SHARE is the default.