How to Schedule Age to Lost Processes
Context
Applies to versions of mod-circulation included in 2021 R1. It is likely that this configuration will need to be removed in future distributions when the scheduling becomes part of the system again.
The age to lost processes are made up of two processes:
- age to lost (the /circulation/scheduled-age-to-lost endpoint)
- aged to lost fee charging (the /circulation/scheduled-age-to-lost-fee-charging endpoint)
As the request to execute these processes comes from outside the system, they need to be executed by a specific user.
This documentation assumes that the same user will be used for both processes.
Preparation
If a suitable user is already set up in your environment, these steps are not needed.
Create a User
Using a token (with X-Okapi-Token header) that has permissions to create a user, make the following request to create the age to lost process user. Make a note of the id
of the record, it will be needed for future steps.
POST /users { "username": "age-to-lost-process-user", "personal": { "lastName": "Age to Lost Scheduling User" }, "active": true }
Create Credentials for the User
Using a token (with X-Okapi-Token header) that has permissions to create a user, make the following request to create the credentials for the user created in the previous step.
POST /authn/credentials { "username": "age-to-lost-process-user", "password": "something-secret" }
Assigning Permissions to the User
Using a token (with X-Okapi-Token header) that has permissions to create a permissions user, make the following request to grant the permissions needed for these processes to the the user created in the first step. The SCHEDULED-TASK-USER
part of the request needs to be substituted with the ID of the user created in a first step.
POST /perms/users { "userId": "{{SCHEDULED-TASK-USER}}", "permissions": [ "circulation.scheduled-age-to-lost.post", "circulation.scheduled-age-to-lost-fee-charging.post" ] }
Scheduling
Any appropriate scheduling tool can be used, e.g. cron
.
It is advised that separate schedules are set up for each of the processes, as the billing step relies on the items having been aged to lost during the first process and so if they run together, extra delays to billing may be introduced.
Steps to Include
Irrespective of the scheduling tool chosen, each scheduled task requires that the user be logged in first before making a request to the process endpoint.
Login as Appropriate User
Login as a user that has the permission needed for the process being scheduled.
The default parameters are the same as in the preparation steps, if your environment uses a different user or password, change these as appropriate.
The token (from the X-Okapi-Token header in the response) needs to be remembered to be included in the subsequent request.
POST /authn/login { "username": "age-to-lost-process-user", "password": "something-secret" }
Start the Age to Lost Process
No body is needed for this request.
POST /circulation/scheduled-age-to-lost
Start the Aged to Lost Billing Process
No body is needed for this request.
POST /circulation/scheduled-age-to-lost-fee-charging
Example Scheduling Tool
The FOLIO DevOps team did some work to schedule these hosted reference environments. This uses Python to provide a cron like scheduler for FOLIO and the default config includes both of these processes.
There is documentation for both the library and ansible task, which I won't repeat here. As I understand it, folks can use the same Python library to schedule these processes in their environments.