Holds & ILL
This chapter describes several use-cases on placing a hold of ILL request in the Wise system. Before using any of the described endpoints a patron must be logged in and have a valid token.
Before a hold can be placed in the system it is necessary to first get hold information from Wise. The result gives information about whether or not a hold can be placed, the costs and pickup locations.
The Wise rest-api has 2 pairs of endpoints for preparing and placing holds.
- Prepare and place a hold on a single title/item
- Prepare and place a hold on multiple titles
These endpoints can be used in 2 ways:
- An item will be delivered for every title
- One item will be delivered for one of the titles. The first item that is found and checked in.
Single hold
The first step for placing a hold on a title is to get the hold information and to check if a hold is allowed for the title:
Prepare hold:
GET /patron/{patronSystemId}/libraryId/{libraryId}/prepareHold/{titleNr}/branch/{branch}
The patron must be logged in before the endpoint can be called. You need a title number and the patrons home branch.
The response gives information on the following:
- holdPossible : true if a hold can be created for this title
- pickupLocation : this branch is the current pickup location
- pickupLocations : alternative locations
- reserverationCostDetails : costs regarding placing, pickup and lending fee
- illAllowed : true if a hold can be created for items which aren’t available in patrons library.
- holdParameters : illAllowed is only available if the holds searchStrategy contains a “R” (region level holds) and/or “I” (system level holds). See Wise manager : holds settings.
Sample:
{
"id": "",
"validationErrors": [],
"holdPossible": true,
"chooseIssueFirst": false,
"pickupLocations": [
{
"branchId": "6491",
"locationType": "B"
},
{
"branchId": "6492",
"locationType": "B"
},
{
"branchId": "6493",
"locationType": "B"
}
],
"pickupLocation": {
"branchId": "6490",
"locationType": "B"
},
"reservationCostDetails": {
"placementCost": 0.0,
"pickupFee": 0.0,
"lendingFee": 0.0
},
"punchCardPunches": 0,
"holdParameters": "N;N649;BIEB;I649;6490;6490|6491|6492|6493|~~~~|",
"queuePosition": 1,
"messageParameters": [],
"reservationCost": 0.0,
"illAllowed": false
}
Place hold
When the prepareHold answers with holdPossible = true or illAllowed = true, then a hold can be created.
Parameters:
- bibliographicRecordId : title number
- holdParameters : the parameter string received from the prepareHold endpoint
- pickupLocationBranchId : the branch to pickup
- requestDueDate : after this date the hold will be canceled if it’s not fulfilled. When omitted, then the default dueDate will be calculated as configured in the hold settings (see Wise Manager)
Sample:
POST patron/4be868c83ea2f8c03b3e052bb35cf0ff/library/I649/hold
{
"requestDueDate":"2021-07-14",
"bibliographicRecordId":3407533,
"holdParameters": "N;N649;BIEB;I649;6490;6490|6491|6492|6493|~~~~|",
"pickupLocationBranchId":"6490"
}
The example above creates a hold request in the holds network of branch 6490.
Creating an ILL request
When a hold is not possible, but a ILL is, then a placeHold can be used to create an ILL request. Therefore the holdParameters must be adjusted. By replacing the first position of the holdParameters (“B” or “N”) with an “I”, the hold will become an Internal ILL request in the Wise system.
[Kastlijst)
Multiple Holds
The endpoints /holdOption en /hold are replacing the endpoints discussed in the previous section (/prepareHold and /placeHold). These endpoints gives you the possibility to create multiple holds in one call. The holds can be grouped together and be handled as one hold or as individual holds.
Prepare multiple holds
Before a hold can be created the application needs to check if creating a hold is allowed.
Parameters:
- bibliographicRecordId : one or more title numbers
- holdType :
- ONE means all titles will be grouped together and as soon as an item is linked to the reservation, all other reservations are cancelled.
- ALL will result in individual holds and will be handled independently
PUT /restapi/patron/{patronSystemId}/holdoption
{
"titleHoldOptions":[
{
"bibliographicRecordId":"1137719"
},
{
"bibliographicRecordId":"4595"
}
],
"holdType":"ONE",
"pickupBranchId":"6490"
}
Response:
{
"id":"",
"validationErrors":[
],
"pickupBranchId":"6490",
"titleHoldOptions":[
{
"bibliographicRecordId":1137719,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":false
},
{
"bibliographicRecordId":4595,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":true
}
],
"holdType":"ONE",
"altPickupBranches":[
{
"locationNumber":"6491",
"locationType":"B",
"description":"Negenmanneke"
},
{
"locationNumber":"6492",
"locationType":"B",
"description":"Ruisbroek"
},
{
"locationNumber":"6493",
"locationType":"B",
"description":"Vlezenbeek"
}
],
"reservationCostDetails":{
"placementCost":0,
"pickupFee":0,
"punchCardPunches":0
}
searchStrategy":"BRANCH"
}
The response gives information on the following:
- holdAllowed : true if a hold can be created for this title on all levels (library/network/region/system)*
- fastDeliveryAllowed : true if one or more items are available in the library; when a hold is created as fastDelivery the fastDelivery costs are applied
- pickupLocation : this branch is the current pickup location
- pickupLocations : alternative locations
- reserverationCostDetails : costs regarding placing, pickup and lending fee
- illAllowed : true if a hold can be created for items which aren’t available in the patron's library.*
fastDeliveryAllowed will be available when the system option “FASTDEL” is activated. The FASTDEL option can be combined with FASTDEN:
- FASTDEL : If an item of the requested title is available in the pickup location, then fastDeliveryAllowed will be true and the fast delivery costs are presented instead of the default hold costs.
- FASTDEN: This is an addition to FASTDEL. Now the system wil respond with fastDeliveryAllowed = true, when an item is available in the holds network of the library.
*) illAllowed is only available if the holds searchStrategy contains a “R” (region level holds) and/or “I” (system level holds). See Wise Manager : holds settings: searchStrategy
To check if a hold will be on Region of System level, the api-client should first check if illAllowed is true. If not, the hold will be placed on branch/network level if holdAllowed is true.
Multiple place holds
This endpoint can be used to create one or more holds on multiple titles as a group or as individual holds.
Parameters:
- bibliographicRecordId : title number
- fastDeliveryAllowed : create the hold and apply the fast delivery costs instead of the placement costs.
- holdType :
- ONE means all titles will be grouped together and as soon as an item is linked to the reservation, all other reservations are cancelled.
- ALL will result in individual holds and will be handled independently
- requestDueDate : date until the hold will be active. After this date the hold will be canceled if it’s not fulfilled. When omitted, then the default dueDate will be calculated as configured in the hold settings (see Wise Manager)
Request
POST patron/4be868c83ea2f8c03b3e052bb35cf0ff/hold
{
"holds":[
{
"bibliographicRecordId":1137719,
"fastDeliveryAllowed":"false",
},
{
"bibliographicRecordId":4595,
"fastDeliveryAllowed":"false",
}
],
"holdType":"ONE",
"pickupBranchId":"6490"
“searchStrategy":"BRANCH" Is hier een Default?
}
Response
{
"id":"",
"validationErrors":[
],
"groupHoldId":617984,
"pickupBranchId":"6490",
"holds":[
{
"bibliographicRecordId":1137719,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":false
},
{
"bibliographicRecordId":4595,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":true
}
],
"holdType":"ONE",
"reservationCostDetails":{
"placementCost":0,
"pickupFee":0,
"punchCardPunches":0
},
"searchStrategy":"BRANCH"
}
Get Holds
The GET method of the holds endpoint gives all active holds of a patron.
GET patron/{patronSystemId}/library/{libraryId}/hold
Response
The response contains for every hold the following properties:
- holdNumber : reference number for this hold
- groupHoldId : reference to other holds in case of holdType “ONE” with multiple titles is created
- bibliographicRecordId : title number of title
- holdStatus : status of this hold
- queuePosition : position in hold queue (approx.)
{
"id":"",
"validationErrors":[
],
"offset":0,
"limit":50,
"total":2,
"items":[
{
"id":"617985",
"validationErrors":[
],
"libraryId":"",
"itemId":0,
"bibliographicRecordId":"4595",
"holdStatus":"ACTIVE",
"cancelAllowed":true,
"updateAllowed":true,
"awaitingPickup":false,
"title":"Gebrandschilderd glas",
"author":"Lee, Lawrence",
"pickupLocationBranchId":"6490",
"pickupLocationName":"libraryName",
"requestDueDate":"2022-06-10",
"holdPlacedDate":"2021-06-10",
"queuePosition":1,
"momkeys":"vlc=13388;isbn=9789027481108;key=4595;",
"medium":"BOE",
"holdNumber":"21061000002",
"groupHoldId":617984
},
{
"id":"617984",
"validationErrors":[
],
"libraryId":"",
"itemId":0,
"bibliographicRecordId":"1137719",
"holdStatus":"ACTIVE",
"cancelAllowed":true,
"updateAllowed":true,
"awaitingPickup":false,
"title":"Het grote boek van waar of niet waar?",
"author":"Mills, Andrea",
"pickupLocationBranchId":"6490",
"pickupLocationName":"Sint-Pieters-Leeuw",
"requestDueDate":"2022-06-10",
"holdPlacedDate":"2021-06-10",
"queuePosition":1,
"momkeys":"vlc=9310024;isbn=9789002258008;key=1137719;",
"medium":"BOE",
"holdNumber":"21061000001",
"groupHoldId":617984
}
]
}