UB Request Per Item

General Purpose

The Universal Borrowing Request resource is used to determine what can be requested and where it can be picked up. The resource is accessed with a POST method to retrieve a specific patron’s UB request information with an accompanying XML form with a list of record IDs and associated database codes.

The Universal Borrowing Request Item resource may be accessed with a PUT method to create a UB request for a specific patron and on a specific item.

Product Version Compatibility

Voyager 7.2.0 and later.

Input Parameters

ParameterTypeDescriptionValueDefaultRequired
record IDpath parameterThe Voyager bibliographic record identifier.stringNoneYes
item IDpath parameterThe Voyager item record identifier.stringNoneYes
patron IDpath parameterThe Voyager patron record identifier. This is used for retrieving a patron’s UB request resource information.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
<pickup-library>Database key of the requested pickup librarystringNoneYes
<record>The record is composed of the db code (defined in the vxws.properties file. For example, connectDb.dev720dmadb=LOCAL) + |(vertical bar) + the system bib ID such as dev720dmadb|10000stringNoneYes

Input URL Syntax

<Base URL>:/patron/<patron ID>/ubrequest?patron_homedb=homedb&patron_group=NN

Example

The following is a URL to access a patron’s UB request information for a list of given records and dbcode with a POST method:

http://server:port/vxws/patron/204/ubrequest?patron_homedb=1@DMADB20010103091142&patron_group=4

And the POST XML must have the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<ubrequest>
<record>dev720dmadb|10000</record>
<record>ubgwcc720db|500</record>
</ubrequest>
<Base URL>:/record/<record ID>/items/<item ID>/ubrequest?patron=patId&patron_homedb=homedb&patron_group=NN

Example

To create a new item-level UB request, use the following URL with a PUT method:

http://server:port/vxws/record/10000/items/27054/ubrequest?patron=212&patron_homedb=1@DMADB20010103091142&patron_group=4

And the PUT XML must have the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<ub-request-parameters>
<pickup-library>1@WHOIDB200501002112461</pickup-library>
<pickup-location>2</pickup-location>
<last-interest-date>20091008</last-interest-date>
<comment>testing ub request</comment>
<dbkey>1@DMADB20010103091142</dbkey>
</ub-request-parameters>

Output XML Format

The following is an output of a patron’s UB request information for a list of records and dbcode using the POST method:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <reply-text>ok</reply-text>
    <reply-code>0</reply-code>
    <ubrequest allowed="Y">
        <instructions usage="read-only">Please select an item.</instructions>
        <last-interest-date usage="Mandatory">2010-01-08</last-interest-date>
        <db>
            <dbname code="1@DMADB20010103091142" usage="Mandatory">DEV720DMADB</dbname>
            <pickup-libraries usage="Mandatory">
                <pickup-library>
                    <pickup-library-name code="1@WHOIDB200501002112461">clustered - dev720db</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="2">MBL Library Office/staff</pickup-location>
                        <pickup-location code="3">WHOI-Clark Office /staff</pickup-location>
                        <pickup-location code="43">WHOI-DLA/staff</pickup-location>
                    </pickup-locations>
                </pickup-library>
                <pickup-library>
                    <pickup-library-name code="2@WHOIDB200501002112461">clustered - dev720db</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="63">CL2 Circulation Desk</pickup-location>
                    </pickup-locations>
                </pickup-library>
                <pickup-library>
                    <pickup-library-name code="1@MAST20001DB20020910104124">ubvoy70db on KC</pickup-library-name>
                    <pickup-locations usage="Mandatory"/>
                </pickup-library>
                <pickup-library>
                    <pickup-library-name code="1@GWCCDB20010402131061">ubgwcc720db</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="16">DWC-Res</pickup-location>
                        <pickup-location code="19">GWCC Circulation Desk</pickup-location>
                    </pickup-locations>
                </pickup-library>
                <pickup-library>
                    <pickup-library-name code="1@RSCCDB20010402160646">ubrscc720db</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="32">RCCD Circulation Desk</pickup-location>
                    </pickup-locations>
                </pickup-library>
            </pickup-libraries>
            <item>
                <item_id>10021.10000</item_id>
                <description>  31279000084320 Main Stacks (DMA)</description>
                <link></link>
            </item>
            <item>
                <item_id>27054.10000</item_id>
                <description>  10000100211 Main Stacks (DMA)</description>
                <link></link>
            </item>
        </db>
        <db>
            <dbname code="1@GWCCDB20010402131061" usage="Mandatory">DEV720GWCCDB</dbname>
            <pickup-libraries usage="Mandatory">
                <pickup-library>
                    <pickup-library-name code="1@WHOIDB200501002112461">dev720db on KC</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="2">MBL Library Office/staff</pickup-location>
                        <pickup-location code="3">WHOI-Clark Office /staff</pickup-location>
                        <pickup-location code="43">WHOI-DLA/staff</pickup-location>
                    </pickup-locations>
                </pickup-library>
                <pickup-library>
                    <pickup-library-name code="2@WHOIDB200501002112461">dev720db on KC</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="63">CL2 Circulation Desk</pickup-location>
                    </pickup-locations>
                </pickup-library>
                <pickup-library>
                    <pickup-library-name code="1@DMADB20010103091142">ubdma720db</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="10">Circulation Desk</pickup-location>
                        <pickup-location code="5">Reves Collection</pickup-location>
                    </pickup-locations>
                </pickup-library>
                <pickup-library>
                    <pickup-library-name code="1@RSCCDB20010402160646">ubrscc70db</pickup-library-name>
                    <pickup-locations usage="Mandatory">
                        <pickup-location code="32">RCCD Circulation Desk</pickup-location>
                    </pickup-locations>
                </pickup-library>
            </pickup-libraries>
            <item>
                <item_id>652.500</item_id>
                <description>  31004000071527 DWC-Stacks (GWCC)</description>
                <link></link>
            </item>
        </db>
    </ubrequest>
</response>

The following is an output of a patron’s UB request for a specific item using the PUT method:

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

Possible Error Codes

2: The patron ID is invalid
19: Record does not exist
25: Failed to create request
27: Item does not exist
51: patron_homedb is a required parameter
53: XML file not formulated properly