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

ParameterTypeDescriptionValueDefaultRequired
record IDpath parameterThe Voyager bibliographic record ID.stringNoneYes
patronquery parameterThe 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.stringNoneYes
patron_homedbquery parameterThe Voyager patron home DB key.stringNoneYes
patron_groupquery parameterThis indicates the Voyager patron group ID. If this parameter is not specified, the server uses its best-guess patron group ID.stringNoneNo

Input XML Elements

ParameterDescriptionValueDefaultRequired
<comment>Comment from the patron regarding this request (maximum 100 characters)stringNoneNo
<dbkey>Database key of the requested itemstringNoneYes
<last-interest-date>The latest date in which the item must be supplied in yyyymmdd formatstringNoneYes
<pickup-location>The code of the requested pickup location, for example 12stringNoneYes
<request-group-id>The id of the request group, for example 2stringNoneNo

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
  1. Either SysAdmin Circulation Request Configuration for Web Service Title Level Hold is set to Y, or
  2. SysAdmin Circulation Request Configuration for Web Service Copy Level Hold is set to Y, or
  3. vxws.properties option.displayRequestGroups is set to Y

Or

  • 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
  1. SysAdmin Circulation Request Configuration for Web Service Title Level Hold is set to N, and
  2. SysAdmin Circulation Request Configuration for Web Service Copy Level Hold is set to N, and
  3. 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>

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 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