Background or Automated Scripts

This solution guide will discuss best practices for creating background or automated scripts that run without staff user interaction with the application.

What are automated scripts

Automated scripts are code which run without user interaction typically at a specific date and time or when a particular action occurs. Automated scripts are often used to synchronize data between two systems at regular intervals. An example of this type of automated script would be a script which runs on a weekly basis to load thesis and dissertation metadata from an institution repository to WorldCat using the WorldCat Metadata API.

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 does not trigger the script to run.

How should it work?

  1. Setup a user within the system which is assigned to script to use.
  2. Design a trigger for the script to run
  3. Create code for the task to be performed in the script
    1. Authentication and Authorization
  4. Log the results of the script to a file

Setup a user within the system which is assigned to script to use

In order for a script like this to run without human intervention a preset user in the system needs to be sent on every request to the web service(s). We strongly advice developers to create a specific account for each background application they build. This is for two reasons:

  1. Using a existing user for a particular staff person can cause the script to break if that user leaves and their account is suspended
  2. Using an existing user conflates in the system actions actually taken by that staff person and actions taken by a script using that staff person's account. If there is ever an issue it is better to be able to clearly determine that given actions are associated with the script

Create the user within the system and assign to the user only the roles necessary to perform the task which is being automated. Once you have created the user, user identity information in the form of a principalID and principalIDNS will be created and can be viewed within the WMS Admin module.

Design a trigger for the script to run

Because a script is designed to run without human intervention, the developer of the application needs to determine a trigger for the action to be taken. One frequently used trigger is the system reaching a particular date and time. An example of this would be running the script daily at 12:01 am. Tools like cron within Unix/Linux operating systems can be used to setup this type of trigger. Another possible type of trigger is when a particular action happens within the system. For example, when a thesis moves to a particular status in an institution repository.

Create code for the task to be performed in the script

Once a user for the script exists and the developer has determined how to trigger the script, then the actual script code can be developed. This includes all the typical code used to interact with OCLC's web services including property authenticating and authorizing both the application and user.

Authentication and Authorization

Using the WSKey and secret, create code that will authenticate and authorize the application using either the HMAC or Access Token methods. User identity information in the form of a principalID and principalIDS must be passed as part of either of these methods. It is highly recomended that the WSKey, secret and user identity information be stored in a configuration file separate from the actual application file.

When performing HMAC authentication the principalID and principalIDS are passed in the Authorization Header.

Example
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1
clientId="tsFsoBXToV1uR8GEMJCcxz9NYpVvutsA5cJAD9cnKUc4FGYEntM6UkcIVlYp4ZhYFteVLAxOWJDUV85W",
timestamp="1361306811",
nonce="762343395744465450467911322335",
signature="2DwPAIYqlCOH9xCHM7PSnOBoVKk/PHrHPeIGmmEK/AI=",
principalID="8eaa9f92-3951-431c-975a-d7dfkd9rd131",
principalIDNS="urn:oclc:wms:da"

When performing Access Token authentication, request an Access Token using the client credential grant flow and include the user identity information.

Example
POST /oauth2/accessToken?grant_type=client_credentials&authenticatingInstitutionId=128807
&contextInstitutionId=128807&scope=WMS_ACQUISITIONS HTTP/1.1
Host: https://authn.sd00.worldcat.org
Accept: application/json
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1
clientId="LXAjXFWEtkA5MHrbpu2YElhMypGHXEPORjp2pTt4E2GwZ1Bx0RhA7YyQutyuSXX5AAjJv3aYH0FWirC6",
timestamp="1361378384", nonce="5e98cf0c", signature="s0oPalwN4/J0bsKj9RTkc/BaD9oxbrsA+jOOw/G/Kc4=",
principalID="8eaa9f92-3951-431c-975a-d7dfkd9rd131",
principalIDNS="urn:oclc:wms:da
Content-Length: 0

This will generate an Access Token which is tied to that user and can be passed directly to the web service.

Example
Authorization: Bearer tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW

Log the results of the script to a file

For each action taken, the script should log the results to a file which can be inspected on regular basis. This is necessary in order to capture any potential failures that occur since the script doesn't have human interaction. It is also advisable that the script notify an appropriate staff person should the script encounter errors.

Things to be mindful of

Each automated script should have its own user

If a single user is created for all automated tasks, then the roles that user has are more numerous than if the user is for a single script. This created a greater threat if the user information is exposed. Additionally, if a single user is used for all automated tasks and errors occur it will be more difficult which automated script might be causing the issue.