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.
- The web service being interacted with requires a user with appropriate permissions is sent for the API request to be valid.
- A staff user does not trigger the script to run.
How should it work?
- Setup a user within the system which is assigned to script to use.
- Design a trigger for the script to run
- Create code for the task to be performed in the script
- Authentication and Authorization
- 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:
- Using a existing user for a particular staff person can cause the script to break if that user leaves and their account is suspended
- 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.
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"
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.
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.