Hold Per Title

Ex Libris Developer Network Voyager Documentation Voyager APIs RESTful Web Services 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 resource may be accessed with a PUT method to create a hold request for a specific patron and on a specific title.

Product Version Compatibility

Voyager 7.2.0 and later.
Voyager 9.0.0 and later – With the following features:

use patron request group to make request
allow or block hold title request on itemless bib
allow or block hold title request when all items of the bib are lost or missing

Input Parameters

Parameter	Type	Description	Value	Default	Required
record ID	path parameter	The Voyager bibliographic record ID.	string	None	Yes
patron	query parameter	The Voyager patron system ID. The system ID can be retrieved from the Voyager circulation staff client interface or returned from the AuthenticatePatronService Web service with patron barcode and last name. The purpose of this parameter is to retrieve additional information regarding whether this patron can request the specific record.	string	None	Yes
patron_homedb	query parameter	The Voyager patron home DB key.	string	None	Yes
patron_group	query parameter	This indicates the Voyager patron group ID. If this parameter is not specified, the server uses its best-guess patron group ID.	string	None	No

Input XML Elements

Parameter	Description	Value	Default	Required
<comment>	Comment from the patron regarding this request (maximum 100 characters)	string	None	No
<dbkey>	Database key of the requested item	string	None	Yes
<last-interest-date>	The latest date in which the item must be supplied in yyyymmdd format	string	None	Yes
<pickup-location>	The code of the requested pickup location, for example 12	string	None	Yes
<request-group-id>	The id of the request group, for example 2	string	None	No

Input URL Syntax

<Base URL>:/record/<record ID>/hold?patron=patId&patron_homedb=homedb&patron_group=NN

Example

The following is a URL to access a patron’s hold request information:

http://server:port/vxws/record/155/hold?patron=185&patron_homedb=1@QA20012DB20020613131313&patron_group=1

To create a new title-level hold request, use the same URL with a PUT method. The PUT XML must have the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<hold-title-parameters>
<pickup-location>13</pickup-location>
<last-interest-date>20091231</last-interest-date>
<comment></comment>
<dbkey>1@QA20012DB20020613131313</dbkey>
</hold-title-parameters>

The PUT XML with the optional request group id:

<?xml version="1.0" encoding="UTF-8"?>
<hold-title-parameters>
<pickup-location>13</pickup-location>
<last-interest-date>20091231</last-interest-date>
<comment></comment>
<dbkey>1@QA20012DB20020613131313</dbkey>
<request-group-id>2</request-group-id>
</hold-title-parameters>

Output XML Format

The following is an output of a patron’s hold request information:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
<reply-text>ok</reply-text>
<reply-code>0</reply-code>
<hold allowed="*Y*">
<pickup-locations usage="*Mandatory*">
<pickup-location code="*13*" default="*N*">Acquisitions</pickup-location>
<pickup-location code="*28*" default="*N*">Branch General</pickup-location>
<pickup-location code="*11*" default="*N*">Cataloging Desk</pickup-location>
<pickup-location code="*12*" default="*Y*">Circulation Desk</pickup-location>
<pickup-location code="*45*" default="*N*">DLC Test</pickup-location>
<pickup-location code="*8*" default="*N*">Main Stacks</pickup-location>
<pickup-location code="*4*" default="*N*">Media Department</pickup-location>
<pickup-location code="*17*" default="*N*">Media Stacks</pickup-location>
<pickup-location code="*16*" default="*N*">Offsite</pickup-location>
<pickup-location code="*31*" default="*N*">Other Branch Circ. Desk</pickup-location>
<pickup-location code="*49*" default="*N*">QA ILL Test</pickup-location>
<pickup-location code="*14*" default="*N*">Reserve Desk</pickup-location>
</pickup-locations>
<dbkey code="*1@QA20012DB20020613131313*" usage="*Mandatory*">University  Library</dbkey>
<instructions usage="*read-only*">Please select an item. (FROM  SysAdmin)</instructions>
<last-interest-date usage="*Mandatory*">2010-01-06</last-interest-date>
<comment max_len="*100*" usage="*Optional*" />
<items usage="*Mandatory*">
<any-item>
<record_id>155</record_id>
<description>Any Copy</description>
</any-item>
<item>
<item_id>303</item_id>
<description>c.0 44102 Main Stacks</description>
</item>
</items>
</hold>
</response>

The following is an output of a patron’s hold request using the PUT method:

<?xml version="1.0" encoding="UTF-8"?>
<response>
     <reply-text>ok</reply-text>
     <reply-code>0</reply-code>
     <create-hold-title>
        <note type="">Your request was successful.</note>
     </create-hold-title>
</response>

The patron request group will be displayed if

The bib location is in the request group, and
The view option from the input URL is full, and

Either

The bib has multiple items that are in different locations. Therefore, these items are in different request groups.
In this case, the request group stanza will be displayed if

Either SysAdmin Circulation Request Configuration for Web Service Title Level Hold is set to Y, or
SysAdmin Circulation Request Configuration for Web Service Copy Level Hold is set to Y, or
vxws.properties option.displayRequestGroups is set to Y

The bib has items that belong to the same location. Therefore, these items are in same request group.
In this case, the request group stanza will be displayed if

SysAdmin Circulation Request Configuration for Web Service Title Level Hold is set to N, and
SysAdmin Circulation Request Configuration for Web Service Copy Level Hold is set to N, and
vxws.properties option.displayRequestGroups is set to Y

The following is a URL to access a patron’s hold request information and displays request group:

http://server:port/vxws/record/145372/hold?view=full&patron=1000806&patron_homedb=1@QA20012DB20020613131313

The corresponding output is:

<?xml version="1.0" encoding="UTF-8" ?>
 <response>
  <reply-text>ok</reply-text>
  <reply-code>0</reply-code>
 <hold allowed="Y">
 <pickup-locations usage="Mandatory">
  <pickup-location code="13" default="N">Acquisitions</pickup-location>
  <pickup-location code="75" default="N">CDVYG499hasright</pickup-location>
  <pickup-location code="11" default="N">Cataloging Desk</pickup-location>
  <pickup-location code="12" default="Y">Circulation Desk</pickup-location>
  <pickup-location code="45" default="N">DLC Test</pickup-location>
  <pickup-location code="77" default="N">Dennis Location</pickup-location>
  <pickup-location code="6" default="N">Juvenile Education</pickup-location>
  <pickup-location code="8" default="N">Main Stacks</pickup-location>
  <pickup-location code="71" default="N">OPAC Circ Desk</pickup-location>
  <pickup-location code="16" default="N">Offsite</pickup-location>
  <pickup-location code="31" default="N">Other Branch Circ. Desk</pickup-location>
  <pickup-location code="49" default="N">QA ILL Test</pickup-location>
  <pickup-location code="14" default="N">Reserve Desk</pickup-location>
  </pickup-locations>
  <dbkey code="1@QA20012DB20020613131313" usage="Mandatory">DEV900NCDB</dbkey>
  <instructions usage="read-only">Please select an item. (FROM SysAdmin)</instructions>
  <last-interest-date usage="Mandatory">2013-08-07</last-interest-date>
  <comment max_len="100" usage="Optional" />
 <items usage="Mandatory">
 <any-item>
  <record_id>145372</record_id>
  <description>Any Copy</description>
  </any-item>
 <item>
  <item_id>115898</item_id>
  <description>c.0 VYG2067REQGRP0101 Main Stacks</description>
  </item>
 <item>
  <item_id>115899</item_id>
  <description>c.0 VYG2067REQGRP0102 Main Stacks</description>
  </item>
 <item>
  <item_id>115900</item_id>
  <description>c.0 VYG2067SECONDREQGRP01 Reference Department</description>
  </item>
  </items>
 <groups>
 <group>
 <pickupLocations>
  <pickup-location code="8">Main Stacks</pickup-location>
  </pickupLocations>
  <group_id>3</group_id>
  <group_desc>Request Group 2</group_desc>
  </group>
 <group>
 <pickupLocations>
  <pickup-location code="16">Offsite</pickup-location>
  <pickup-location code="31">Other Branch Circ. Desk</pickup-location>
  <pickup-location code="45">DLC Test</pickup-location>
  <pickup-location code="49">QA ILL Test</pickup-location>
  <pickup-location code="75">CDVYG499hasright</pickup-location>
  </pickupLocations>
  <group_id>4</group_id>
  <group_desc>Super Request Group 3</group_desc>
  </group>
  </groups>
  </hold>
  </response>

Using the same URL, and the following to submit the request with the request group:

<?xml version="1.0" encoding="UTF-8"?>
<hold-title-parameters>
    <pickup-location>8</pickup-location>
    <last-interest-date>20091231</last-interest-date>
    <comment/>
    <dbkey>1@QA20012DB20020613131313</dbkey>
    <request-group-id>2</request-group-id>
</hold-title-parameters>

When on SysAdmin OPAC circ desk circulation policy Configuration policies tab,
if ‘Allow title level hold on bibs with no items – OPAC’ is unchecked
then the itemless bib title hold request is not allowed.

The following input XML using HTTP GET on an itemless bib

http://server:port/vxws/record/145548/hold?view=full&patron=1000875&patron_homedb=1@QA20012DB20020613131313

will generate the following output showing the hold is not allowed:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <reply-text>ok</reply-text>
    <reply-code>0</reply-code>
    <hold allowed="N">
         <note type="error">No holdings are available.</note>
    </hold>
</response>

The following input XML using HTTP PUT to sumit request on an itemless bib

http://server:port/vxws/record/145548/hold?view=full&patron=1000875&patron_homedb=1@QA20012DB20020613131313

with the input XML:

<?xml version="1.0" encoding="UTF-8"?>
<hold-title-parameters>
<pickup-location>13</pickup-location>
<last-interest-date>20091231</last-interest-date>
<comment></comment>
<dbkey>1@QA20012DB20020613131313</dbkey>
</hold-title-parameters>

will generate the following output showing the hold is not allowed:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <reply-text>Failed to create request</reply-text>
    <reply-code>25</reply-code>
    <create-hold-title>
         <note type="error">No holdings are available.</note>
    </create-hold-title>
</response>

When

An SysAdmin OPAC circ desk circulation policy Configuration items tab, the settings for the item type (e.g. Book)
does not allow OPAC hold on missing or lost (either Libray or System applied) items. (All OPAC Hold boxes are unchecked)
All items of the bib are either missing or lost.

The following input XML using HTTP GET

http://server:port/vxws/record/145549/hold?view=full&patron=1000875&patron_homedb=1@QA20012DB20020613131313

will generate the following output showing the hold is not allowed:

<?xml version="1.0" encoding="UTF-8"?>
    <response>
    <reply-text>ok</reply-text>
    <reply-code>0</reply-code>
    <hold allowed="N">
         <note type="error">No items are available for request because they are missing or lost.</note>
    </hold>
</response>

When

On SysAdmin OPAC circ desk circulation policy Configuration items tab, the settings for the item type (e.g. Book)
does not allow OPAC hold on missing or lost (either Libray or System applied) items. (All OPAC Hold boxes are unchecked)
All items of the bib are either missing or lost.

The following input XML using HTTP PUT to submit a request

http://server:port/vxws/record/145549/hold?view=full&patron=1000875&patron_homedb=1@QA20012DB20020613131313

with the input XML:

<?xml version="1.0" encoding="UTF-8"?>
<hold-title-parameters>
<pickup-location>13</pickup-location>
<last-interest-date>20091231</last-interest-date>
<comment></comment>
<dbkey>1@QA20012DB20020613131313</dbkey>
</hold-title-parameters>

Will generate the following output that can’t make the request:

<?xml version="1.0" encoding="UTF-8"?>
    <response>
    <reply-text>Failed to create request</reply-text>
    <reply-code>25</reply-code>
    <create-hold-title>
       <note type="error">No items are available for request because they are missing or lost.</note>
    </create-hold-title>
</response>

Possible Error Codes

19: Record does not exist