Page Comparison

References

...

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

...

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

...

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.

...

user_id: The user's unique identifier in Alma. This can be their primary ID, barcode, or email address.
apikey: Your API key with appropriate permissions.

...

Creating an item-level request in Alma

...

user_primary_id: The ID of the requesting user.
request_type: HOLD
pickup_location_type: LIBRARY
pickup_location_library: The pickup location library code.
material_type (optional): Used in fulfillment policies.

...

(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

Code Block

http
POST https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/123456789/holdings/987654321/items/567890123/requests?apikey={your_api_key}
Content-Type: application/json

{
  "user_primary_id": "patron123",
  "request_type": "HOLD",
  "pickup_location_type": "LIBRARY",
  "pickup_location_library": "Main Library",
  "comment": "Requesting for research purposes."
}

...

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

Create record

Mandatory Fields:
- The actual record: XML string describing the record
- record_format: Default is marc21
- suppress_from_publishing: default is true

Create holding record

Parameters:
- mms_id: Bib record ID
Mandatory Fields:
- The actual record: XML string describing the record
- suppress_from_publishing: tbd

Create Item

...

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?

...

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.

: The item's shelving location

library: The library where the item is located.

Example request:

Code Block

http
POST https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/123456789/holdings/987654321/items?apikey={your_api_key}
Content-Type: application/json

{
  "item_data": {
    "barcode": "1234567890123",
    "policy": "Standard Loan",
    "library": {
      "value": "MAIN"
    },
    "location": {
      "value": "GEN"
    },
    "physical_material_type": {
      "value": "BOOK"
    },
    "description": "Hardcover edition",
    "enumeration_a": "Vol. 1"
  }
}

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 request for an itembibliographic record, refer to Create request for an Item

Circulate Requests

Circulation tracking and reaction (lending)

...

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

Alma Supplying Library:
- Request status: In progress
- 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

...

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
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 Pickup Library transaction state = `AWAITING_PICKUP` Trigger `HandleBorrowerItemOnHoldShelf` Alma Supplying Library: Request status: In progress (Transit item) Item status: Transit	Trigger DCB `HandleSupplierInTransit` event to change Borrowing or Pickup Library transaction state = `AWAITING_PICKUP` `OPEN` DCB `PatronRequest.READYPICKUP_FOR_PICKUPTRANSIT` `HostLmsItem.ITEM_ONPICKUP_HOLDSHELF` Alma Supplying Library: On hold shelf / Ready for pickup Item Checked Out to Patron `TRANSIT`
Received at Pickup Library	DCB Patron Request exists with corresponding `HostLmsItem.ITEM_ONPICKUP_HOLDSHELFTRANSIT`	DCB Patron Request Workflow matches corresponding request details at Pickup Library transaction state = `ITEMAWAITING_CHECKED_OUTPICKUP`	Trigger `HandleBorrowerItemLoaned` `HandleBorrowerItemOnHoldShelf` event to change Borrowing or Supplying Pickup Library transaction state = `ITEMAWAITING_CHECKED_OUTPICKUP` DCB `PatronRequest.LOANEDREADY_FOR_PICKUP` `HostLmsItem.ITEM_ON_LOANEDHOLDSHELF` Alma Supplying Library Request status: In progress Item status: Loan Loan status: Active, the item is checked out to a patron. Item Returned by Borrowing Patron : On hold shelf / Ready for pickup
Item Checked Out to Patron at Pickup Library	DCB Patron Request exists in status with corresponding `HostLmsItem.ITEM_ON_LOANEDHOLDSHELF`	DCB Patron Request Workflow matches corresponding request details at either Pickup or Borrowing Library transaction state = `ITEM_CHECKED_INOUT`	Trigger `HandleBorrowerRequestReturnTransit` `HandleBorrowerItemLoaned` event to change at Borrowing or Pickup Supplying Library transaction state = `ITEM_CHECKED_IN` loan status = `Closed` virtual item status = `In transit` `OUT` DCB `PatronRequest.RET-TRANSITLOANED` `HostLmsItem.ITEM_RETURNEDLOANED` Alma Supplying Library: no changes? Received Back at Lending Agency 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_RETURNEDLOANED`	DCB Patron Request Workflow matches corresponding request details at either Alma Supplying Library Request status: 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. either Pickup or Borrowing Library transaction state = `ITEM_CHECKED_IN`	Trigger `HandleBorrowerRequestReturnTransit` event to change at Borrowing or Pickup Library transaction state = `CLOSED` DCB `PatronRequest.COMPLETED` `HostLmsItem.ITEM_AVAILABLE` Local status on supplier request changed to `AVAILABLE`

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:

...

Alma updates:

No status updates

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

Alma status updates:

Request status: Completed
Item status: Item in place
Loan is closed

DCB status transition:

...

- 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:

Code Block

http
POST https://api-na.hosted.exlibrisgroup.com/almaws/v1/loans?apikey={your_api_key}
Content-Type: application/json

{
  "item_barcode": "1234567890123",
  "patron_id": "987654321",
  "due_date": "2024-12-18"
}

Loan with Policy:

Code Block

http
POST https://api-na.hosted.exlibrisgroup.com/almaws/v1/loans?apikey={your_api_key}
Content-Type: application/json

{
  "item_barcode": "1234567890123",
  "patron_id": "987654321",
  "loan_policy": {
    "value": "Regular"
  }
}

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

Circulation tracking and reaction (borrowing)

...

Versions Compared

Old Version 34

New Version Current

Key

Search for a user in Alma

Creating an item-level request in Alma

Creating an item-level request

Circulate Requests

Circulation tracking and reaction (lending)

Circulate Requests

Circulation tracking and reaction (lending)

1. Placing the request

2. Item is sent out to the borrowing agency

3. Item received in borrowing agency:

4. Item is loaned in borrowing agency:

5. Item returned at the borrowing library

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

Circulation tracking and reaction (borrowing)