Pulllist Application

This solution guide will discuss the process of creating a pulllist application which uses WMS Circulation API, WMS NCIP API and the WorldCat Registry API.

Assumptions

  1. Valid staff user with WMS Circulation role will be interacting with the application
  2. A single branch’s Pulllist can be interacted with at a time
  3. Check In operations are performed based on item barcode
  4. When an item is being sent between locations, two check in operations must be performed. One of check in the item when it is pulled, a second must be performed when it is received.

How should it work?

  1. Authenticate the Client Application
  2. Authenticate the User
  3. Obtain a list branch identifiers and names to display for the user staff user
  4. Allow the staff user to select a branch to see the pulllist for
  5. Show the pulllist items for that particular branch
  6. Allow a selected item to be “Checked In”
  7. Display the routing information for that item

Authenticate the Client Application

Because this application needs to perform several requests to different APIs, we highly recommend that developers use Access Token authentication rather than HMAC authentication because it will require less cryptography within the client and the various APIs. A client should obtain a single access token and use this on all the requests to the various APIs.

Authenticate the User

Because this application is going to interact with personal identifiable information related to library patrons, it needs to authenticate the staff user via the OCLC's OAuth server prior to performing any requests to the web services. The client application should use the Explicit Authorization Code flow to authenticate the user and obtain an Access Token.

Obtain a list of branch identifiers and names to display for the staff user

Once the client application and user has authenticated, the application needs to list the possible branch libraries the staff user can choose from. This branch information can be obtained from the WorldCat Registry via a “holding codes” request.

Request

http://www.worldcat.org/webservices/registry/content/holdingcodes/Institutions/128807

Response

<holdingcodes xmlns="info:rfa/rfaRegistry/xmlSchemas/holdingcodes" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="info:rfa/rfaRegistry/xmlSchemas/holdingcodes 
http://worldcat.org/registry/xsd/collections/holdingcodes/holdingcodes.xsd">
    <identifier>info:rfa/oclc/holdingcodes/128807</identifier>
    <versionID>2012-03-06T21:06:55.498Z</versionID>
    <holdingCodeConfig>
        <isDefaultHoldingSymbol>false</isDefaultHoldingSymbol>
        <holdingSymbol>OCPSB</holdingSymbol>
        <holdingCode>EAST</holdingCode>
        <displayName>OCPSB East Branch</displayName>
        <shelvingLocation>EAST Periodicals test</shelvingLocation>
        <shelvingLocation>EAST-Periodicals</shelvingLocation>
        <shelvingLocation>EAST-Reference</shelvingLocation>
        <shelvingLocation>EAST-STACKS</shelvingLocation>
        <shelvingScheme>Library of Congress</shelvingScheme>
        <branchRegistryId>129057</branchRegistryId>
    </holdingCodeConfig>
    <holdingCodeConfig>
        <isDefaultHoldingSymbol>true</isDefaultHoldingSymbol>
        <holdingSymbol>OCPSB</holdingSymbol>
        <holdingCode>MAIN</holdingCode>
        <displayName>OCPSB Main Branch</displayName>
        <shelvingLocation>Main Reserves - 2 hours</shelvingLocation>
        <shelvingLocation>Main Reserves - 24 hours</shelvingLocation>
        <shelvingLocation>Main Reserves - 4 hours</shelvingLocation>
        <shelvingLocation>MAIN-Periodicals</shelvingLocation>
        <shelvingLocation>MAIN-Reference</shelvingLocation>
        <shelvingLocation>MAIN-STACKS</shelvingLocation>
        <shelvingScheme>Library of Congress</shelvingScheme>
        <branchRegistryId>129479</branchRegistryId>
    </holdingCodeConfig>
    <holdingCodeConfig>
        <isDefaultHoldingSymbol>false</isDefaultHoldingSymbol>
        <holdingSymbol>OCPSB</holdingSymbol>
        <holdingCode>NORT</holdingCode>
        <displayName>OCPSB North Branch</displayName>
        <shelvingLocation>1234</shelvingLocation>
        <shelvingLocation>NORT Periodicals test</shelvingLocation>
        <shelvingLocation>NORT-Periodicals</shelvingLocation>
        <shelvingLocation>NORT-Reference</shelvingLocation>
        <shelvingLocation>NORT-STACKS</shelvingLocation>
        <shelvingScheme>Library of Congress</shelvingScheme>
        <branchRegistryId>129055</branchRegistryId>
    </holdingCodeConfig>
    <holdingCodeConfig>
        <isDefaultHoldingSymbol>false</isDefaultHoldingSymbol>
        <holdingSymbol>OCPSB</holdingSymbol>
        <holdingCode>WEST</holdingCode>
        <displayName>OCPSB West Branch</displayName>
        <shelvingLocation>WEST Periodicals test</shelvingLocation>
        <shelvingLocation>WEST-Periodicals</shelvingLocation>
        <shelvingLocation>WEST-Reference</shelvingLocation>
        <shelvingLocation>WEST-STACKS</shelvingLocation>
        <shelvingScheme>Library of Congress</shelvingScheme>
        <branchRegistryId>129058</branchRegistryId>
    </holdingCodeConfig>
    <holdingCodeConfig>
        <isDefaultHoldingSymbol>false</isDefaultHoldingSymbol>
        <holdingSymbol>OCPSB</holdingSymbol>
        <holdingCode>SOUT</holdingCode>
       <displayName>OCPSB South Branch</displayName>
        <shelvingLocation>SOUT Periodicals test</shelvingLocation>
        <shelvingLocation>SOUT-Periodicals</shelvingLocation>
        <shelvingLocation>SOUT-Reference</shelvingLocation>
        <shelvingLocation>SOUT-STACKS</shelvingLocation>
        <shelvingScheme>Library of Congress</shelvingScheme>
        <branchRegistryId>129056</branchRegistryId>
    </holdingCodeConfig>
    <holdingCodeConfig>
        <isDefaultHoldingSymbol>false</isDefaultHoldingSymbol>
        <holdingSymbol>OCPSB</holdingSymbol>
        <holdingCode>ONLN</holdingCode>
        <displayName>Online resource</displayName>
        <shelvingLocation>ebook</shelvingLocation>
        <shelvingLocation>ejournal</shelvingLocation>
        <shelvingScheme>Title</shelvingScheme>
        <branchRegistryId>128963</branchRegistryId>
    </holdingCodeConfig>
</holdingcodes>

Allow the staff user to select a branch to see the pullist for

Once a list of branches has been obtained then the application should display this for the staff user to choose to show a particular pullist for. The branch ID will be the identifier used for the pulllist.

Show the pulllist items for that particular branch

The application now needs to make a request to the WMS Circulation Service for a pulllist for that particular branch. This will return an Atom feed which lists each item on the pulllist along with basic metadata for pulling the item from the shelf.

Request

GET /pulllist/129479 HTTP/1.1
Host: circ.sd00.worldcat.org
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="{built-in-api-key}", 
timestamp="1437572604", nonce="81c5c644", 
signature="gQbolJwIeCdoC/hxKGuMIyEYebuy9vbI4ljuG4+SlSI=", 
principalID="{built-in-principal-id}", principalIDNS="urn:oclc:wms:da"

Response

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
ETag: W/"a43a64ba94a752474432817dc492a902"
Content-Type: application/atom+xml;charset=UTF-8
Content-Length: 3080
Date: Wed, 22 Jul 2015 13:43:25 GMT

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:os="http://a9.com/-/spec/opensearch/1.1/">
  <id>urn:oclc:circulation/pulllist/128807/129479</id>
  <title type="text">Pull List</title>
  <updated>2015-07-22T13:43:25.458Z</updated>
  <os:totalResults>2</os:totalResults>
  <os:startIndex>1</os:startIndex>
  <os:itemsPerPage>10</os:itemsPerPage>
  <entry>
    <title type="text" />
    <updated>2015-07-22T13:43:25.459Z</updated>
    <content type="application/xml">
      <itemDescription xmlns="http://worldcat.org/xmlschemas/CirculationPullList-1.0" 
xmlns:ns2="http://worldcat.org/xmlschemas/Bib-1.0" 
xmlns:ns4="http://worldcat.org/xmlschemas/CirculationRoom-1.0" 
xmlns:ns3="http://worldcat.org/xmlschemas/CirculationNotification-1.0">
        <bibliographicItem>
          <ns2:oclcNumber>2351916</ns2:oclcNumber>
          <ns2:title>Library journal.</ns2:title>
          <ns2:materialFormat>PERIODICAL</ns2:materialFormat>
          <ns2:publisher>[New York, NY] : Reed Business Information</ns2:publisher>
          <ns2:publicationYear>1976</ns2:publicationYear>
          <ns2:language>eng</ns2:language>
        </bibliographicItem>
        <pieceDesignation>22547-361001</pieceDesignation>
        <callNumber>
          <description>020.5 O688</description>
        </callNumber>
        <recordType>SERIAL</recordType>
        <numberOfPieces>1</numberOfPieces>
        <homeHoldingLocation>MAIN</homeHoldingLocation>
        <requestDate>2015-07-13T20:02:36.000Z</requestDate>
        <patronName>Coombs, Karen</patronName>
        <enumeration>no. 1, v. 100000</enumeration>
      </itemDescription>
    </content>
  </entry>
  <entry>
    <title type="text" />
    <updated>2015-07-22T13:43:25.460Z</updated>
    <content type="application/xml">
      <itemDescription xmlns="http://worldcat.org/xmlschemas/CirculationPullList-1.0" 
xmlns:ns2="http://worldcat.org/xmlschemas/Bib-1.0" 
xmlns:ns4="http://worldcat.org/xmlschemas/CirculationRoom-1.0" 
xmlns:ns3="http://worldcat.org/xmlschemas/CirculationNotification-1.0">
        <bibliographicItem>
          <ns2:oclcNumber>317923541</ns2:oclcNumber>
          <ns2:title>Diary of a wimpy kid : dog days /</ns2:title>
          <ns2:author>Kinney, Jeff.</ns2:author>
          <ns2:materialFormat>BOOK</ns2:materialFormat>
          <ns2:publisher>New York : Amulet Books,</ns2:publisher>
          <ns2:publicationYear>2009</ns2:publicationYear>
          <ns2:language>eng</ns2:language>
        </bibliographicItem>
        <pieceDesignation>991112</pieceDesignation>
        <callNumber>
          <description>PZ7.K6232</description>
        </callNumber>
        <recordType>SINGLE_PART</recordType>
        <numberOfPieces>1</numberOfPieces>
        <homeHoldingLocation>MAIN</homeHoldingLocation>
        <permanentShelvingLocation>
          <element>MAIN-STACKS</element>
        </permanentShelvingLocation>
        <requestDate>2014-10-29T16:13:49.000Z</requestDate>
        <patronName>Patron</patronName>
      </itemDescription>
    </content>
  </entry>
</feed>

The pulllist will include an atom entry for each item on the pullist. This will contain basic metadata about the item including:

  • OCLC Number
  • Title
  • Author
  • Format
  • Call Number
  • Barcode
  • Branch Location
  • Shelving Location

Allow a selected item to be “Checked In”

Once a particular item has been “pulled” then the staff user needs to “Check In” the item. This is performed via the WMS NCIP web service using the Staff Profile.  An NCIP CheckIn Message needs to be sent to the web service. The CheckIn message requires the barcode of the item, which is part of the data returned by the Pulllist. The branchID of the location the item is being Checked in at is also required.

Request

POST /ncip?principalID={built-in-principal-id}&principalIDNS=urn%3Aoclc%3Awms%3Ada HTTP/1.1
Host: circ.sd00.worldcat.org
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="{built-in-api-key}", 
timestamp="1437575706", nonce="709dae12", 
signature="Y1z46UdYlo10A3fu/iC0IGrmzq+mzGjSh0LZxU50n4E="

<?xml version="1.0" encoding="UTF-8"?>
<NCIPMessage xmlns="http://www.niso.org/2008/ncip" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ncip="http://www.niso.org/2008/ncip"
xsi:schemaLocation="http://www.niso.org/2008/ncip 
http://www.niso.org/schemas/ncip/v2_01/ncip_v2_01.xsd"
ncip:version="http://www.niso.org/schemas/ncip/v2_01/ncip_v2_01.xsd">
<CheckInItem >
<InitiationHeader>
<FromAgencyId>
<AgencyId ncip:Scheme="http://oclc.org/ncip/schemes/agencyid.scm">129055</AgencyId>
</FromAgencyId>
<ToAgencyId>
<AgencyId>129479</AgencyId>
</ToAgencyId>
<ApplicationProfileType 
ncip:Scheme="http://oclc.org/ncip/schemes/application-profile/platform.scm">
Version 2011</ApplicationProfileType>
</InitiationHeader>
<ItemId>
<AgencyId>128807</AgencyId>
<ItemIdentifierValue>98734172</ItemIdentifierValue>
</ItemId>
</CheckInItem>
</NCIPMessage>

Response

Response:HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
ETag: W/"3f4361d7eeecf02aa32582fadb1b29b7"
Content-Type: application/xml;charset=UTF-8
Content-Length: 1390
Date: Wed, 22 Jul 2015 14:35:07 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:NCIPMessage ns1:version="2.0" 
xmlns:ns2="http://oclc.org/WCL/ncip/2011/extensions" 
xmlns:ns1="http://www.niso.org/2008/ncip" 
xmlns:ns3="http://www.oclc.org/ncip/usernote/2012">
  <ns1:CheckInItemResponse>
    <ns1:ItemId>
      <ns1:AgencyId>128807</ns1:AgencyId>
      <ns1:ItemIdentifierValue>98734172</ns1:ItemIdentifierValue>
    </ns1:ItemId>
    <ns1:RoutingInformation>
      <ns1:RoutingInstructions>Request</ns1:RoutingInstructions>
      <ns1:Destination>
        <ns1:Location>
          <ns1:LocationType 
ns1:Scheme="http://www.niso.org/ncip/v2_0/schemes/locationtype/locationtype.scm">
Current Location</ns1:LocationType>
          <ns1:LocationName>
            <ns1:LocationNameInstance>
              <ns1:LocationNameLevel>1</ns1:LocationNameLevel>
              <ns1:LocationNameValue>MAIN</ns1:LocationNameValue>
            </ns1:LocationNameInstance>
          </ns1:LocationName>
        </ns1:Location>
      </ns1:Destination>
      <ns1:RequestType 
ns1:Scheme="http://www.niso.org/ncip/v2_0/schemes/requesttype/requesttype.scm">
Hold</ns1:RequestType>
      <ns1:UserId>
        <ns1:AgencyId>128807</ns1:AgencyId>
        <ns1:UserIdentifierValue>2200998</ns1:UserIdentifierValue>
      </ns1:UserId>
      <ns1:NameInformation>
        <ns1:PersonalNameInformation>
          <ns1:StructuredPersonalUserName>
            <ns1:GivenName>Karen</ns1:GivenName>
            <ns1:Surname>Coombs</ns1:Surname>
          </ns1:StructuredPersonalUserName>
        </ns1:PersonalNameInformation>
      </ns1:NameInformation>
    </ns1:RoutingInformation>
  </ns1:CheckInItemResponse>
</ns1:NCIPMessage>

Display the Routing information for the item

The NCIP web service returns a response that contains the Routing Information for the item.  The Routing information includes:

  • Routing Instructions. For Holds this says “Request”
  • Request Type. For Holds this has a value of “Hold”.
  • Destination
    • The holding code for the location where the item needs to be routed
  • Information on the patron who placed the request.

In the case where the item is already at the location where it needs to be then the Check In response will include:

  • a blank Destination element
  • information on the patron for whom the item is being held.

Things to be mindful of

Items which are moving locations need two check ins

When pulling an item for a request that is transferring the item from one branch location to another, the system requires the item be checked in twice. The first check in takes place when the item is pulled from the shelf at its originating location. The check in sets the items status to “On Route”. The second check in takes place when the item is received at the location it is being transporting to. This will change the status of the item to “On Shelf” and alerts the patron that the item is available to pick up and will be held for a certain amount of time.

User interacting with the application needs an appropriate WMS Circulation role

The user who is interacting with this application needs to have an appropriate WMS Circulation role. Without this role then the user will not be able to view the pulllist or check in items.

Multiple Identifiers for branch locations

Different identifiers are used for branch locations in the APIs necessary to build this application. Each branch location has two key types of identifiers: branch registryID and holdingCode. The branch registryID is used

  • by the pulllist web service to obtain a pulllist for a particular branch
  • by the WMS NCIP service when performing Check In to tell the system a given item’s location (where it is being checked in)

The holdingCode is used

  • when Check In response is returned. The holdingCode is returned as part of the Destination and tells where the item should be routed to.

Both of these values are returned within the response for a holding code request. Using this map it is possible to convert from one value to another or to the staff display name for that location.