Copyright (C) 2018-2023 The Open Library Foundation
This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.
Microservice to allow 3rd party discovery services to perform FOLIO patron actions via the discovery service's UI.
Some of the features of mod-patron may rely on specific configurations. mod-patron stores such configurations in its own
database using local settings API with interface: patron.settings. The module provides CRUD API for managing it.
Required parameters:
keyscopevalue
| Configuration name | Key | Scope | Value | Description |
|---|---|---|---|---|
| Multi-Item Requesting Feature enable/disable | isMultiItemRequestingFeatureEnabled |
mod-patron |
Object with property name enabled and value true or false |
Allows to query batch request details using GET /patron/account/{accountId} endpoint |
Multi-Item Requesting Feature configuration example:
Request body that can be used to enable the Multi-Item Requesting Feature using POST /patron/settings endpoint:
{
"id": "65de6432-be11-48ba-9686-a65101634040",
"scope": "mod-patron",
"key": "isMultiItemRequestingFeatureEnabled",
"value": {
"enabled": "true"
},
"_version": 1
}When modifying the configuration setting using PUT /patron/settings/{id}, ensure that the value property is a valid JSON object
and _version property is provided with the correct version number.
Returns the patron account: totals, and optionally the lists of charges, holds, loans and batch request status records (Multi-Item requests).
| Query parameter | Default | Description |
|---|---|---|
includeLoans |
false |
Include the loans list |
includeCharges |
false |
Include the charges list |
includeHolds |
false |
Include the holds list |
includeBatches |
false |
Include the batches list of batch request status records, see Multi-Item requests |
batchesDaysBack |
30 |
Look-back window in days for batch requests without an open request, see Multi-Item requests |
sortBy |
not set | CQL sort of the holds, charges and loans lists, see Sorting |
offset |
0 |
Number of records to skip |
limit |
2147483647 |
Maximum number of records per list |
The endpoint has optional query parameter 'sortBy' that indicates the order of records within the lists of holds, charges, loans. The value of 'sortBy' parameter is appended as a part of a CQL query that's evaluated during separate corresponding calls to retrieve holds, charges and loans. Often, a given value of 'sortBy' will only work with one type of record (holds, loans, or charges), e.g. item.title works for holds, but not loans/charges. The expectation is that when using the 'sortBy' parameter, separate calls will be made for retrieving holds, loans, and charges. In cases where multiple 'include*' parameters are 'true' and 'sortBy' is used, it's possible (if not probable) that some of those lists will not be sorted as desired.
Examples of requests:
- get holds sorted by item.title field in ascending order: /patron/account/{accountId}?includeHold=true&&sortBy=item.title/sort.ascending
- get charges sorted by title field in ascending order: /patron/account/{accountId}?includeCharges=true&&sortBy=title/sort.ascending
- get loans sorted by loanDate field in ascending order: /patron/account/{accountId}?includeCharges=true&&sortBy=loanDate/sort.ascending
Controlled by the includeBatches and batchesDaysBack query parameters.
A Multi-Item request (batch request) is a set of item requests submitted together with
POST /patron/account/{accountId}/instance/{instanceId}/batch-request. The requests that are created for its items
are ordinary holds. The batches list of the account does not contain the batch requests themselves, it contains
batch request status records: one record per batch request, describing its processing status and the outcome
for each of its items (see the example below).
The records are linked to the holds by id: for a hold created as part of a batch request, batchRequestInfo.batchRequestId
is equal to the batchRequestId of the corresponding record in batches.
- The
isMultiItemRequestingFeatureEnabledsetting must exist and be enabled, see Supported configuration settings. WithincludeBatches=trueand the setting missing, disabled or invalid, the endpoint responds with422and no account data. - The
circulation-bffinterfacescirculation-bff-requestsandcirculation-bff-requests-batchmust be available.
- Type: boolean, optional, default
false. Withfalsethebatchesproperty in the response is an empty list, holds have nobatchRequestInfo, and thebatchesDaysBackparameter is ignored. - With
true:- The
batcheslist of batch request status records is added to the response. Each record contains thebatchRequestId, thestatus(In progressorCompleted; a batch request where every item failed isCompleted),submittedAt,completedAt(only when completed), the countersitemsTotal,itemsRequested,itemsPending,itemsFailedand the per-item listsitemsRequestedDetails,itemsPendingDetails,itemsFailedDetails. - Each hold created as part of a batch request gets the
batchRequestInfoproperty (batchRequestIdandbatchRequestSubmittedAt) that points to its record inbatchesbybatchRequestId. It is present only whenincludeHolds=true, as the holds list is empty otherwise. - Fetching the requests is a bit heavier than doing the same when
includeBatchesisfalse, as getting the batch request related info requires additional upstream calls. includeBatches=trueis enough to get thebatches,includeHoldsis not required.
- The
The batches list contains the union of the records for:
- Batch requests of the holds returned in the response, in other words of the page of requests selected with
offset,limitandsortBy. Every such record is referenced by at least one hold throughbatchRequestInfo, whenincludeHolds=true. Their item details haveinstanceIdandtitle. - Batch requests of the patron that have no open request, so no hold references them and they are not reachable
through the requests: batch requests that are pending, in progress or failed (for example, every item failed)
and were submitted within the last
batchesDaysBackdays. Their item details have noinstanceIdand may have notitle.offset,limitandsortBydo not apply to them.
A batch request found both ways has one record. The records are ordered by submission date (submittedAt),
newest first, regardless of sortBy.
- Type: integer, optional, default
30, minimum0, maximum365. Values out of the range are rejected with400. - Used only when
includeBatches=true, ignored otherwise. - Defines the look-back window for the batch requests without an open request (group 2 above): only those
submitted at or after "now minus
batchesDaysBackdays" (UTC) get a record inbatches. It does not filter the records of the batch requests referenced by the holds in the response (group 1). 0means the cut-off is the current moment, so effectively no records of group 2 are returned.- Completed batch requests (all items successfully requested) are not added by this parameter. They appear only if one of their requests is still open, as it is then referenced by a hold.
- At most 100 batch requests without an open request are loaded per call, the newest ones. Older ones within
the
batchesDaysBackwindow are not returned if there are more than 100 such ones in the window. The cap is not configurable. - Each record costs at least two additional upstream calls (the batch request and its details), all made
concurrently. The cap bounds the number of these calls, so
includeBatches=truehas a noticeable cost for patrons with many batch requests. - A failure to load the status or details of a batch request without an open request is logged and its record is left out of the response instead of failing the whole request. A failure for a batch request referenced by a returned hold, or for the query of the batch requests themselves, fails the request.
- The
batcheslist itself is not paged.offsetandlimitonly affect which requests are returned, and therefore which records of group 1 are included. - For an
In progressrecord the counters are calculated from the batch request details, as they are the most up-to-date. For aCompletedrecord they are taken from the batch request statistics.
Example of the request:
GET /patron/account/{accountId}?includeHolds=true&includeBatches=true&batchesDaysBack=60
Example of a record of the batches list, for a batch request without an open request:
{
"batchRequestId": "5203c035-005e-4a70-b555-ddaa3094c521",
"status": "In progress",
"submittedAt": "2025-09-10T10:00:00.123+00:00",
"itemsTotal": 2,
"itemsRequested": 0,
"itemsPending": 2,
"itemsFailed": 0,
"itemsPendingDetails": [
{
"itemId": "7e881333-3a3a-501c-a6d4-03b81e3c7e79",
"pickUpLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8"
},
{
"itemId": "8e881333-3a3a-501c-a6d4-03b81e3c7e79",
"pickUpLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8"
}
],
"itemsFailedDetails": [],
"itemsRequestedDetails": []
}See project MODPATRON at the FOLIO issue tracker.
Other modules are described, with further FOLIO Developer documentation at dev.folio.org