How to Schedule Age to Lost Processes

Owned by Marc Johnson
Last updated: May 17, 2021 by Anne L. Highsmith

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.

Create User Request
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.

Create Credentials Request
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.

Create Permissions User
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.

Login as Scheduled Process User 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.

Start Age to Lost Process Request
POST /circulation/scheduled-age-to-lost

Start the Aged to Lost Billing Process

No body is needed for this request.

Start Aged to Lost Billing Process 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.