Example Implementation from Johns Hopkins

Part 1:
http://www.screencast.com/users/jrochkind/folders/Jing/media/151bf85a-2102-46d7-b6a9-e0986ea36daf

Part 2:
http://www.screencast.com/users/jrochkind/folders/Jing/media/c6f686e2-e424-4dae-9c43-de455b06c885

Summary

E-ZBorrow contracted with Relais to develop web services that will allow the integration of item availability, material requesting, and user experience into our core library discovery and patron service infrastructure.  These discovery web services (dws) allow developers to access E-ZBorrow programmatically.  Web services are defined by W3C as "a software system designed to support interoperable machine-to-machine interaction over a network" (http://en.wikipedia.org/wiki/Web_service).  Making use of the documentation and setting up these services will require an advanced level of technical expertise.  For a non-technical description of the services and their intended use, please see the functional specifications developed for this project.

Testing

          Since E-ZBorrow does not have a test system special testing needs to be set up. Please let Kaitlyn know if you want to test and she can get you in contact with the right people.  

Please No High Volume Testing: Relais has asked that we not attempt to perform high volume testing against the test system. 

Authentication and Authorization Overview

The E-ZBorrow system is tightly integrated with your library patron database to manage authentication and authorization of users.  All of the web services here, except FindItem, make use of an authorization id to manage user interaction.  FindItem requires a valid patron barcode, which for pre-authentication queries may be a "generic" valid patron record created in the ILS for that purpose.  The generic record would simply need to be created with an authorized status for E-ZBorrow purposes (faculty, staff, or student).

Authentication Service in Proxy Mode:  This document has some background information about the Authentication and Authorization web services, and it outlines how these services could eventually be adapted for use during user login to Discovery.  Use of the Authentication web service for Discovery is dependent upon upgrades to the Discovery environment that have not yet been schedule with Relais.

Authentication Web Service 

The authentication web service uses the patron's credentials to validate the user against your library's ILS.  For authentication purposes, libraries must pass the patron's credentials, which generally mean the library barcode (encryption available, see documentation), as this is required for Relais to interface with your library system.  Upon successful authentication, Relais will assign an "authorization id" (aid) that will be used in subsequent calls (RequestItem and RequestQuery) in place of the patron's credentials for enhanced security.  The authorization id will be set to expire based on system settings and is configurable.

BUG ALERT:  For this web service, an "Accept-Language" value of "en-US" must be included.  This is a bug which will be corrected eventually, but for now, will not work without this value.

Authorization Web Service 

The authorization web service is used to validate that an authorization id (aid) is still valid and optionally, to extend the session while making additional calls against other services.

FindItem Web Service

The FindItem web service allows libraries to pass a known item search to Relais and get back a true/false response regarding item availability within E-Zborrow ("availability" is based on the existing E-Zborrow circulating collections and status logic).  Besides the true/false availability response, the web service will return data that may be used as part of the RequestItem web service, such as library pickup location options.

FindItem Authorization Considerations:  It is likely that institutions may want to offer the FindItem service without requiring users to log in.  It would be possible for libraries to create a generic authorized user in the patron database and use this generic user to send FindItem requests when valid patron credentials are not available.  It would then only be necessary to invoke the campus login when the user actions a request using the RequestItem web service.

SearchCatalog Web Service (Word version available here)

For Testing and Troubleshooting Only:  Relais released documentation for the CatalogSearch service  that runs as part of the FindItem and RequestItem web services.  The CatalogSearch service returns the raw Pazpar2 results from a structured search.  The raw Pazpar2 data is the information that FindItem and RequestItem use to analyze availability and route submitted requests to potential suppliers.  The SearchCatalog service may prove useful for testing and troubleshooting, but Relais does not intend to maintain access to SearchCatalog as a stand-alone service for libraries to directly develop against.

RequestQuery Web Service (Word version available here)

The RequestQuery service will allow libraries to retrieve patron request information from E-ZBorrow and integrate the E-ZBorrow experience into your library account services portal.  In the documentation you will notice that it is possible to pull transaction data based on date ranges, status, or individual transaction number.

RequestItem Web Service

The RequestItem service will allow libraries to initiate E-ZBorrow requests through the web service framework.  RequestItem documentation covers how to structure data to pass requests into E-ZBorrow.