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.

...

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

2. apikey: Your API key with appropriate permissions.

...

Creating an item-level request in Alma

Create a Request API allows to create an 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.

...

Endpoint

POST /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}/requests

Required Parameters

1. mms_id: The unique identifier of the bibliographic record.

2. holding_id: The ID of the holding record associated with the item.

3. item_pid: The unique identifier of the physical item.

Key parameters and mandatory fields include:

• user_primary_id: The ID of the requesting user.

• Mandatory Fields:

  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

...

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

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

• 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

Endpoint

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

Required Parameters:

Parameters:

• mms_id:

  Bib record ID

• Mandatory Fields:

  • The actual record: XML string describing the record

  • suppress_from_publishing: tbd

Create Item

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

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.

...

2. 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

...

3. 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)

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:

...

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 requesting user.

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

...

• 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

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:

• Transaction status changes to COMPLETED          due_date (optional)

• loan_policy (optional)

Example Request

Basic Loan Request:

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:

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)

...