Recall Per Title

General Purpose

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

The resource may be accessed with a PUT method to create a recall 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 feature

  • Use request group to submit recall request.
  • Allow title level recall request when all items are either missing or lost.

Input Parameters

ParameterTypeDescriptionValueDefaultRequired
record IDpath parameterThe Voyager bibliographic record IDstringNoneYes
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 request group id, for example 2stringNoneNo

Input URL Syntax

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

Example

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

http://10.100.2.37:30114/vxws/record/155/recall?patron=185&patron_homedb=1@QA20012DB20020613131313&patron_group=1

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

<recall-title-parameters>
<pickup-location>1</pickup-location>
<last-interest-date>20091019</last-interest-date>
<comment>testing recall request</comment>
<dbkey>1@QA20012DB20020613131313</dbkey>
</recall-title-parameters>

Output XML Format

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

<?xml version="1.0" encoding="UTF-8" ?>
 <response>
  <reply-text>ok</reply-text>
  <reply-code>0</reply-code>
 <recall 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.</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>
</recall>
</response>

The following is an output of patron’s recall request using the PUT method.

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

Note that a patron can recall an item is when the item is charged by other patron.
The request group is displayed when
the bib has items from different locations, and each location belong to different request groups.
In addition, one or more items from different locations are charged, and either the SysAdmin web service
title recall flag or title hold flag or vxws.properties option.displayRequestGroup flag is Y.

The following example shows the output from this URL

http://10.100.3.87:58814/vxws/record/145372/recall?patron=1000806&patron_homedb=1@QA20012DB20020613131313
<?xml version="1.0" encoding="UTF-8" ?>
 <response>
  <reply-text>ok</reply-text>
  <reply-code>0</reply-code>
 <recall 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.</instructions>
  <last-interest-date usage="Mandatory">2013-08-08</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>
  </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="75">CDVYG499hasright</pickup-location>
  <pickup-location code="45">DLC Test</pickup-location>
  <pickup-location code="16">Offsite</pickup-location>
  <pickup-location code="31">Other Branch Circ. Desk</pickup-location>
  <pickup-location code="49">QA ILL Test</pickup-location>
  </pickupLocations>
  <group_id>4</group_id>
  <group_desc>Super Request Group 3</group_desc>
  </group>
  </groups>
  </recall>
  </response>

if there is a single item is charged, then when both SysAdmin web service title hold and copy hold flags
are N and the vxws.properties option.displayRequestGroup flag is Y, the request group will display.

The following is an example of recall input with the request group:

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

When all items for a bib are either lost or missing, and
Sysadmin OPAC circulation policy items tab settings
don’t allow OPAC recall for missing and lost items,
the title level recall request for the bib will be blocked.

The following is the GET input URL for recall request on a bib with all items lost or missing.

http://10.100.3.87:58814/vxws/record/145549/recall?view=full&patron=1000875&patron_homedb=1@QA20012DB20020613131313

The output XML for the recall request shows the title request is not allowed.

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

When all items for a bib are either lost or missing, and
Sysadmin OPAC circulation policy items tab settings
don’t allow OPAC recall for missing and lost items,
the title level recall request for the bib will be blocked.

The following is the PUT input URL for recall request on a bib with all items lost or missing.

http://10.100.3.87:58814/vxws/record/145549/recall?view=full&patron=1000875&patron_homedb=1@QA20012DB20020613131313

With the following input XML

<recall-title-parameters>
<pickup-location>12</pickup-location>
<last-interest-date>20091019</last-interest-date>
<comment>testing recall request</comment>
<dbkey>1@QA20012DB20020613131313</dbkey>
</recall-title-parameters>

The output XML for the recall request shows the title request 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-recall-title>
         <note type="error">No items are available for request because they are missing or lost.</note>
    </create-recall-title>
</response>

Possible Error Codes

19: Record does not exist