Hold per Title

General Purpose

The resource may be accessed with a GET method to retrieve a specific patron’s hold request information for a given title.

The reported information may be viewed as a list of available request groups, or as a specific available request group’s information.

The request group donates a subset of the title that may be requested.

For example, if the title is a multi-volume title, each volume/issue will be a separate request group. If there are different material type items, each material type will also be a separate request group.

In the case of institutional requests, other parameters, such as differences in the owning sublibrary or differences in the item status, may also affect the request groups division. This depends on the following tab100 variables:

  •  SUB-LIBRARY-DIVISION
  •  HOLD-REQUEST-ITM-STATUS
  •  HOLD-REQUEST-COLLECTION
  •  HOLD-REQ-PROCESS-STATUS

The request groups’ parameters also include the allowed pickup locations and the information that may be attached to the request, such as additional author information or added notes. Such fields are marked by the usage attribute.

The resource may be accessed with a PUT method to create a hold request for a specific patron and on a specific title.

Additional information on institutional hold request groups.
Additional information on consortial hold request groups.

Product Version Compatibility

Versions 18, 20.1 and later

Interface Type

RESTful API

Hierarchy

specific patron hold request information for a given title

Input Parameters

REST Resource IDs:

Patron ID: The Aleph patron system identifier.

Record ID: The Aleph BIB record identifier. The identifier is composed of the BIB library code + the system number. For example, USM01000050362

Group ID: The ID of the specific request group. May be used to fetch a specific request group’s information.

URL Parameters:

institution: The ID of an institution (ADM library) for which the information is requested. The parameter may be used when the tab100 CONSORTIAL-HOLD-REQUEST variable is set to use institutional requests. Optional.

view: The format in which the request groups list will be displayed. Possible values are brief and full. Optional.

Input URI

Request Groups List:

<Base URL>:/patron/<patron ID>/record/<record ID>/holds

For example:

To retrieve the request groups list for the patron ID 00000036 and BIB record 000009549, use:

http://server.name:1892/rest-dlf/patron/00000036/record/USM01000009549/holds

To retrieve the request groups list for the patron ID 00000036 and BIB record 000050362 in a specific institution, use:

http://server.name:1892/rest-dlf/patron/00000036/record/USM01000009549/holds?institution=USM50

Specific Request Group :

<Base URL>:/patron/<patron ID>/record/<record ID>/holds/<hold ID>

For example:

To retrieve a specific hold group’s information for the patron ID 00000036 and BIB record 000009549, use:

http://server.name:1892/rest-dlf/patron/00000036/record/USM01000009549/holds/USM50000009549000010

Input XML

To create a new title-level hold request, use the same URL with a PUT method of HTTP.

The request “Body” of the “PUT” method must contain input XML with the Hold request details.

The PUT XML must have the following structure:

post_xml=<hold-request-parameters><pickup-location>WID</pickup-location><last-interest-date>20111231</last-interest-date><start-interest-date>20110917</start-interest-date><sub-author>Additional Author Information</sub-author><sub-title>Additional Title Information</sub-title><pages>Addtional Pages Information</pages><note-1>Additional Note</note-1><note-2>Addtional Note</note-2><rush>Y or N</rush></hold-request-parameters>

Note that the date information must be in YYYYMMDD format. The pickup location must be supplied as code.
Also note the “post_xml=” on start.

Output XML Format

The returned XML includes a list of the record’s request groups, or a specific request group’s information.

Request groups list example:

<?xml version="1.0" encoding="UTF-8"?>
<hold-grp-list>
  <reply-text>ok</reply-text>
  <reply-code>0000</reply-code>
  <hold allowed="Y">
    <institution code="USM50">
      <inst-name>Exlibris Demo Libraries</inst-name>
      <group href="http://server.name:1892/rest-dlf/patron/00000036/record/USM01000009549/holds/USM50000009549000010"/>
    </institution>
  </hold>
</hold-grp-list>

Specific request group example:

<?xml version="1.0" encoding="UTF-8"?>
<hold-grp-full>
  <reply-text>ok</reply-text>
  <reply-code>0000</reply-code>
  <group id="USM50000009549000010">
    <translate-change-active-library>USM50</translate-change-active-library>
    <sublibrary-code>WID</sublibrary-code>
    <sublibrary>Main Library</sublibrary>
    <item-status-code>01</item-status-code>
    <item-status>Regular loan</item-status>
    <item-process-status-code/>
    <item-process-status>Not in Process</item-process-status>
    <collection-code>WIDLC</collection-code>
    <collection>WID-LC</collection>
    <volume/>
    <issue/>
    <part/>
    <year/>
    <month/>
    <material>Book</material>
    <description/>
    <pickup-locations default="Y" usage="Mandatory">
      <pickup-location code="LAW  ">Law Library</pickup-location>
      <pickup-location code="LIT  ">Economics Library</pickup-location>
    </pickup-locations>
  </group>
  <last-interest-date usage="Optional">20140307</last-interest-date>
  <start-interest-date usage="Optional"/>
  <sub-author usage="Optional" max_len="50"/>
  <sub-title usage="Optional" max_len="100"/>
  <pages usage="Optional" max_len="30"/>
  <note-1 usage="Optional" max_len="50"/>
  <note-2 usage="Optional" max_len="50"/>
  <rush usage="Optional"/>
</hold-grp-full>

If a new request was successfully created using the PUT method then a reply such as the following will be reported:

<?xml version="1.0" encoding="UTF-8"?>
<put-rec-hold>
  <reply-text>ok</reply-text>
  <reply-code>0000</reply-code>
  <create-hold>
    <note type="info">Action Succeeded</note>
  </create-hold>
</put-rec-hold>

Possible Error Codes

01 : The supplied institution ID is invalid

02 : The patron ID is invalid

19 : Record does not exist

21 : Group does not exist

25: Failed to create request