Notification Management Application

This solution guide will discuss best practices for an application for managing print notification from WMS Circulation. It will discuss two possible pathes for creating a Notification Management application: a simple web application or a background script.

Web Application

The web application version of the notification management application is a web site that allows a user to login with the WMS account, select a date range of notification to view, lists notifications, and allows the PDFs associated with those notifications to be viewed and printed. The advantages of this type of application is that it is installed on a single server and accessible by all staff.

Assumptions

  1. The web service being interacted with requires a user with appropriate permissions is sent for the API request to be valid.
  2. A staff user interacts with a web page to view and download the notification for a particular data range.

How should it work?

  1. Login the user
  2. Allow the user to select a date range for notifications to view
  3. Display a list of notifications for the particular date range
  4. Allow the PDF of a particular notification to be viewed
  5. Make available a downloadable ZIP file for all the PDF notifications

Login in the user

In order for an application of this type to work properly, the Circulation web service needs to be passed a valid user. The best way to get a valid user is to use the Explicit authorization flow to authenticate a user.

Allow the user to select the data range from notifications to view

Once the user is authenticated then a form needs to be displayed which allows the user to select a date range for which to print notifications. Currently the web services only allows a "from" parameter to be sent. This parameter allows a user print notifications "from" a given date to the present.

Display a List of notifications for a date range

Once the user has input a "from" date, a query to the WMS Circulation API is made based on this date.

GET /circ/notification?from=201506150000 HTTP/1.1
Host: circ.sd00.worldcat.org
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 
clientId="{built-in-api-key}", timestamp="1434397314", 
nonce="af4e968a", signature="QkNSwcfQwa5byb+b8D+1oVwtcaoFUzqzVbQA+ZIGEiY=", 
principalID="{built-in-principal-id}", principalIDNS="urn:oclc:wms:da"

This will return a list of notifications which match the criteria. The notifications returned need to be filtered based on the user's institution id. Once the application filters the notifications, it can display the basic information about the notifications to the user.

Allow the PDF of a particular notification to be viewed

The display of each noticication should contain a link to view the PDF for a particular notification. To obtain the actual PDF notification, a second request to the API for that particular notification must be made based on the notifications ID.

GET /circ/notification/get?id=CIRCULATION%2FNOTIFICATION_LOAN_OVERDUE%2F003_20150615_0700AM.pdf 
HTTP/1.1
Host: circ.sd00.worldcat.org
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="{built-in-api-key}", 
timestamp="1434397568", nonce="702bd840", signature="eRRi4r3wsF86+8CJhAzMAoiIZiKe4ucBV3TRJDQHFmY=", 
principalID="{built-in-principal-id}", principalIDNS="urn:oclc:wms:da"

The response for this request will include a base64 encoded binary verision of the PDF which can be displayed for the inline in the web browser.

Make available a downloadable ZIP file for all the PDF notifications

The notification results page also should contain a link to a ZIP file for all the PDFs related to the notifications returned in the results page.

Things to be mindful of

  1. The PDF file for the notification is stored as base64 binary data element in the response for a single file. You'll .need to decode it
  2. The Circulation API requires a valid and authorized user in order to be able to perform operations

Background script

The background script version of the notification management application is a script that is designed to run at particular intervals and to download notifications to a local directory to be printed by staff. The advantages of this type of application is that the notifications can be downloaded in the background and printed in batch.

Assumptions

  1. The web service being interacted with requires a user with appropriate permissions is sent for the API request to be valid.
  2. A preset user needs to be used to authenticate when the script runs.
  3. The script is scheduled to run at the same time every day.

How should it work?

  1. Setup a configuration file
  2. Allow the data range to be set
  3. Retrieve the notifications for that particular date range
  4. Download each notification for the data range to a local directory

Setup a configuration file

In order to be able to run properly the background script needs a configuration file that contains basic information ot make the script run such as the wskey, secret, institution id, principalID and principalIDNS. These are best stored in a configuration file to keep them secure and allow them to be different for different institutions. The script will draw out configuration options and use them.

Allow the data range to be set

The web service allows a from parameter to be sent which allows notification from a particular date to be the present to be printed. So the script needs to have an option that allows this from value to be set.

Retrieve the notifications for that particular date range

Once a from parameter is set then the script needs to retrieve the notifications associated with that date range by interacting with the web service. The response will contain a list of notifications responding to the data range queried. Each notification in the response will contain an ID for that specific notification.

Download each notification for the data range to a local directory

To download the PDF file for each notification, the script should make a request for the notification based on the ID. This response will contain metadata and the PDF file for the notification. The PDF file will be stored in the response as binary data. The script should save the binary file to a local directory where the user is able to retrieve it.

Things to be mindful of

  1. The PDF file for the notification is stored as binary data element in the response for a single file. You'll need to decode it
  2. The Circulation API requires a valid and authorized user in order to be able to perform operations
  3. If the script should be run at regular intervals then a tool such as cron will need to be setup run the script.