Alma Pickup Anywhere (PUA) implementation

Purpose and scope

This page explains how DCB interacts with Alma APIs to support Pickup Anywhere (PUA). It focuses on the Alma‑side calls and required identifiers. It does not describe DCB’s internal workflow or edge cases.

Roles and terminology

In PUA an Alma system can appear as one or many of three roles:

Borrower -- the patron’s home system is Alma.
Supplier -- the lending item’s system is Alma.
Pickup -- the pickup location’s system is Alma.

DCB uses virtual records: short-lived stand-ins for non-Alma bibs, holdings, items, and users - to let Alma execute its standard workflows.

How role is assigned

After a PUA request is submitted, DCB assigns an Alma system to a role based on:

Whether the patron is from an Alma agency.
Whether the supplying item belongs to an Alma agency.
Whether the pickup location is at an Alma agency.

By definition of PUA, the pickup agency is different from the agency where the request was placed.

Virtual records

To satisfy Alma’s expectations before placing a hold, DCB will create:

Borrower -- virtual Bib, Holding and Item.
Supplier -- virtual User.
Pickup -- virtual Bib, Holding, Item and User.

Endpoint details for creating virtual records are in the DCB Alma Adapter doc: DCB Alma Adapter (as of DCB Service 8.47.0)

Placing the hold (all roles)

Endpoint

POST /almaws/v1/users/{user_id}/requests?item_pid={item_pid}

Body

{
  "requestType": "HOLD",
  "pickupLocationType": "LIBRARY",
  "pickupLocationLibrary": "library_code",
  "comment": "Consortial Hold. tno= ..."
}

Static fields

requestType = "HOLD"
pickupLocationType = "LIBRARY"

Parameter sources by role

Role	`user_id` (source)	`item_pid` (source)	`pickupLocationLibrary` (source)	`comment`

Role	`user_id` (source)	`item_pid` (source)	`pickupLocationLibrary` (source)	`comment`
Borrower	Real Alma user local ID	Virtual local item ID created by DCB	Configured sharing‑library‑code	Generated transaction note (DCB)
Supplier	Virtual user ID created by DCB	Real local item ID chosen during DCB resolution	Configured sharing‑library‑code	Generated transaction note (DCB)
Pickup	Virtual user ID created by DCB	Virtual local item ID created by DCB	Local ID from stored DCB Location record	Generated transaction note (DCB)

Notes

comment is a DCB‑generated concatenated string, typically including tno.

Updating item status (state alignment)

To keep borrower, supplier, and pickup states aligned, DCB signals item state changes in Alma. The adapter first retrieves the item to gather current state, then performs a scan‑in operation via the API so Alma advances its internal workflow independently of DCB.

Endpoint

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

Reference: https://developers.exlibrisgroup.com/alma/apis/docs/bibs/UE9TVCAvYWxtYXdzL3YxL2JpYnMve21tc19pZH0vaG9sZGluZ3Mve2hvbGRpbmdfaWR9L2l0ZW1zL3tpdGVtX3BpZH0=/

Expectation

DCB State	Alma item state

DCB State	Alma item state
`PICKUP_TRANSIT`	`TRANSIT`
`READY_FOR_PICKUP`	`HOLDSHELF`
`LOANED`	`LOAN`
`RETURN_TRANSIT`	`TRANSIT`
`REQUEST_PLACED_AT_PICKUP_AGENCY`	`REQUESTED`
`COMPLETED`	`1 (in place)`

Cheat sheet:

Base status = in place / not in place.

Process type = why it’s not in place (Loan, Transit, Hold Shelf, Missing, Lost, Acquisition, RS, Technical-Migration, Work Order).

Useful resources:

Cleanup of virtual records

Once the item circulates and returns to the supplier, DCB cleans up to restore the Alma system state:

Removes virtual bibs, holdings, items, and holds created for the DCB PUA request.
Virtual patron records are retained for reuse; they are not removed during cleanup.

Reuse key

DCB locates a reusable virtual user by a unique ID placed in the user_identifier field:
"<localId>@<agencyCode>" (e.g., "245343@gtech").

Cleanup (DELETE) endpoints are listed in the Adapter doc:
DCB Alma Adapter (as of DCB Service 8.47.0)

Tracking

DCB tracks local Alma records to pull in changes and react to them. The records that DCB is most interested in is the item and hold as their states will drive DCB’s internal workflow. The fetching of these local records is implemented by:

Item retrieval endpoint: https://developers.exlibrisgroup.com/alma/apis/docs/bibs/R0VUIC9hbG1hd3MvdjEvYmlicy97bW1zX2lkfS9ob2xkaW5ncy97aG9sZGluZ19pZH0vaXRlbXMve2l0ZW1fcGlkfQ==/
Request retrieval endpoint: https://developers.exlibrisgroup.com/alma/apis/docs/users/R0VUIC9hbG1hd3MvdjEvdXNlcnMve3VzZXJfaWR9L3JlcXVlc3RzL3tyZXF1ZXN0X2lkfQ==/
User retrieval endpoint; https://developers.exlibrisgroup.com/alma/apis/docs/users/R0VUIC9hbG1hd3MvdjEvdXNlcnMve3VzZXJfaWR9/

Meaning

Virtual = created by DCB so Alma can process non‑Alma entities.
Real = pre‑existing in that Alma agency.

Role	Item tracking: `mms_id` / `holding_id` / `item_pid`	Patron tracking: `user_id`	Request tracking: `request_id` (Alma hold)
Borrower	Virtual	Real	Real
Supplier	Real	Virtual	Virtual
Pickup	Virtual	Virtual	Virtual

Useful links:

https://journal.code4lib.org/articles/16597

Out of scope

DCB inner workings and message passing.
Edge cases beyond the standard PUA use case.