Manage Schedules Over REST
The scheduler service is exposed under the /openidm/scheduler context path. Within this context path, the defined scheduled jobs are accessible at /openidm/scheduler/job. A job is the actual task that is run. Each job contains a trigger that starts the job. The trigger defines the schedule according to which the job is executed. You can read and query the existing triggers on the /openidm/scheduler/trigger context path.
The following examples show how schedules are validated, created, read, queried, updated, and deleted, over REST, by using the scheduler service.
The examples also show how to pause and resume scheduled jobs, when an instance is placed in maintenance mode. For information about placing a server in maintenance mode, see Place a Server in Maintenance Mode.
Note
When you configure schedules over REST, changes made to the schedules are not pushed back into the configuration service. Managing schedules by using the /openidm/scheduler/job context path essentially bypasses the configuration service and sends the request directly to the scheduler.
If you need to perform an operation on a schedule that was created by using the configuration service (by placing a schedule file in the conf/ directory), you must direct your request to the /openidm/config context path, and not to the /openidm/scheduler/job context path.
PATCH operations are not supported on the scheduler context path. To patch a schedule, use the config context path.
Schedules are defined using Quartz cron or simple triggers. If you use a cron trigger, you can validate your cron expression by sending the expression as a JSON object to the scheduler context path:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ --data '{ "cronExpression": "0 0/1 * * * ?" }' \ "http://localhost:8080/openidm/scheduler/job?_action=validateQuartzCronExpression"{ "valid": true }
To define a new schedule, send a PUT or POST request to the scheduler/job context path with the details of the schedule in the JSON payload. A PUT request allows you to specify the ID of the schedule. A POST request assigns an ID automatically.
The following example uses a PUT request to create a schedule that fires a script (script/testlog.js) every second. The example assumes that the script exists in the specified location. The schedule configuration is as described in "Configure Schedules":
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0" \ --request PUT \ --data '{ "enabled": true, "type": "cron", "schedule": "0/1 * * * * ?", "persisted": true, "misfirePolicy": "fireAndProceed", "invokeService": "script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } } }' \ "http://localhost:8080/openidm/scheduler/job/testlog-schedule"{ "_id": "testlog-schedule", "enabled": true, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false, "triggers": [ { "calendar": null, "group": "scheduler-service-group", "jobKey": "scheduler-service-group.testlog-schedule", "name": "trigger-testlog-schedule", "nodeId": "node1", "previousState": null, "serialized": { "type": "CronTriggerImpl", "calendarName": null, "cronEx": { "cronExpression": "0/1 * * * * ?", "timeZone": "Africa/Johannesburg" }, "description": null, "endTime": null, "fireInstanceId": "node1_1570611359345", "group": "scheduler-service-group", "jobDataMap": { "scheduler.invokeService": "org.forgerock.openidm.script", "scheduler.config-name": "scheduler-testlog-schedule", "scheduler.invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "schedule.config": { "enabled": true, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false }, "scheduler.invokeLogLevel": "info" }, "jobGroup": "scheduler-service-group", "jobName": "testlog-schedule", "misfireInstruction": 1, "name": "trigger-testlog-schedule", "nextFireTime": 1570611569000, "previousFireTime": 1570611568000, "priority": 5, "startTime": 1570611391000, "volatility": false }, "state": "NORMAL", "_rev": "000000001d4724d6", "_id": "scheduler-service-group.trigger-testlog-schedule" } ], "previousRunDate": "2019-10-09T08:59:28.000Z", "nextRunDate": "2019-10-09T08:59:29.000Z" }
Note that the output includes the trigger that was created as part of the scheduled job, as well as the nextRunDate for the job. For more information about the trigger properties, see Query Schedule Triggers.
The following example uses a POST request to create an identical schedule to the one created in the previous example, but with a server-assigned ID:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ --data '{ "enabled": true, "type": "cron", "schedule": "0/1 * * * * ?", "persisted": true, "misfirePolicy": "fireAndProceed", "invokeService": "script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } } }' \ "http://localhost:8080/openidm/scheduler/job?_action=create"{ "_id": "b12e4a77-a626-4a38-a1dc-8edc7498ca1c", "enabled": true, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false, "triggers": [ { "calendar": null, "group": "scheduler-service-group", "jobKey": "scheduler-service-group.b12e4a77-a626-4a38-a1dc-8edc7498ca1c", "name": "trigger-b12e4a77-a626-4a38-a1dc-8edc7498ca1c", "nodeId": null, "previousState": null, "serialized": { "type": "CronTriggerImpl", "calendarName": null, "cronEx": { "cronExpression": "0/1 * * * * ?", "timeZone": "Africa/Johannesburg" }, "description": null, "endTime": null, "fireInstanceId": null, "group": "scheduler-service-group", "jobDataMap": { "scheduler.invokeService": "org.forgerock.openidm.script", "scheduler.config-name": "scheduler-b12e4a77-a626-4a38-a1dc-8edc7498ca1c", "scheduler.invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "schedule.config": { "enabled": true, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false }, "scheduler.invokeLogLevel": "info" }, "jobGroup": "scheduler-service-group", "jobName": "b12e4a77-a626-4a38-a1dc-8edc7498ca1c", "misfireInstruction": 1, "name": "trigger-b12e4a77-a626-4a38-a1dc-8edc7498ca1c", "nextFireTime": 1570611659000, "previousFireTime": null, "priority": 5, "startTime": 1570611659000, "volatility": false }, "state": "NORMAL", "_rev": "000000009e2e2212", "_id": "scheduler-service-group.trigger-b12e4a77-a626-4a38-a1dc-8edc7498ca1c" } ], "previousRunDate": null, "nextRunDate": "2019-10-09T09:00:59.000Z" }
The output includes the generated _id of the schedule, in this case "_id": "b12e4a77-a626-4a38-a1dc-8edc7498ca1c".
The following example displays the details of the schedule created in the previous example. Specify the job ID in the URL:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request GET \ "http://localhost:8080/openidm/scheduler/job/testlog-schedule"{ "_id": "testlog-schedule", "enabled": true, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false, "triggers": [ { "calendar": null, "group": "scheduler-service-group", "jobKey": "scheduler-service-group.testlog-schedule", "name": "trigger-testlog-schedule", "nodeId": null, "previousState": null, "serialized": { "type": "CronTriggerImpl", "calendarName": null, "cronEx": { "cronExpression": "0/1 * * * * ?", "timeZone": "Africa/Johannesburg" }, "description": null, "endTime": null, "fireInstanceId": "node1_1570611359712", "group": "scheduler-service-group", "jobDataMap": { "scheduler.invokeService": "org.forgerock.openidm.script", "scheduler.config-name": "scheduler-testlog-schedule", "scheduler.invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "schedule.config": { "enabled": true, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false }, "scheduler.invokeLogLevel": "info" }, "jobGroup": "scheduler-service-group", "jobName": "testlog-schedule", "misfireInstruction": 1, "name": "trigger-testlog-schedule", "nextFireTime": 1570611719000, "previousFireTime": 1570611718000, "priority": 5, "startTime": 1570611391000, "volatility": false }, "state": "NORMAL", "_rev": "000000002d1c2465", "_id": "scheduler-service-group.trigger-testlog-schedule" } ], "previousRunDate": "2019-10-09T09:01:58.000Z", "nextRunDate": "2019-10-09T09:01:59.000Z" }
You can query defined and running scheduled jobs using a regular query filter.
The following query returns the IDs of all defined schedules:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request GET \ "http://localhost:8080/openidm/scheduler/job?_queryFilter=true&_fields=_id"{ "result": [ { "_id": "reconcile_systemLdapAccounts_managedUser" }, { "_id": "testlog-schedule" } ] ... }
The following query returns the IDs, enabled status, and next run date of all defined schedules:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request GET \ "http://localhost:8080/openidm/scheduler/job?_queryFilter=true&_fields=_id,enabled,nextRunDate"{ "result": [ { "_id": "reconcile_systemLdapAccounts_managedUser", "enabled": false, "nextRunDate": null }, { "_id": "testlog-schedule", "enabled": true, "nextRunDate": "2019-10-09T09:43:17.000Z" } ] ... }
To update a schedule definition, use a PUT request and update all the static properties of the object.
This example disables the testlog schedule created in the previous example by setting "enabled":false:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0" \ --request PUT \ --data '{ "enabled": false, "type": "cron", "schedule": "0/1 * * * * ?", "persisted": true, "misfirePolicy": "fireAndProceed", "invokeService": "script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } } }' \ "http://localhost:8080/openidm/scheduler/job/testlog-schedule"{ "_id": "testlog-schedule", "enabled": false, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false, "triggers": [], "previousRunDate": null, "nextRunDate": null }
When you disable a schedule, all triggers are removed and the nextRunDate is set to null. If you re-enable the schedule, a new trigger is generated, and the nextRunDate is recalculated.
This example returns a list of the jobs that are currently executing. The list lets you decide whether to wait for a specific job to complete before you place a server in maintenance mode.
This action does not list the jobs across a cluster, only the jobs currently executing on the node to which the request is routed.
Note that this list is accurate only at the moment the request was issued. The list can change at any time after the response is received.
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ "http://localhost:8080/openidm/scheduler/job?_action=listCurrentlyExecutingJobs"[ { "enabled": true, "persisted": true, "misfirePolicy": "fireAndProceed", "type": "simple", "repeatInterval": 3600000, "repeatCount": -1, "invokeService": "org.forgerock.openidm.sync", "invokeContext": { "action": "reconcile", "mapping": "systemLdapAccounts_managedUser" }, "invokeLogLevel": "info", "timeZone": null, "startTime": null, "endTime": null, "concurrentExecution": false } ]
For testing purposes, and for certain administrative tasks, you can trigger a scheduled task manually, outside of its specified schedule. A scheduled task must be enabled before it can be triggered.
This command triggers the testlog-schedule job created previously:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ "http://localhost:8080/openidm/scheduler/job/testlog-schedule?_action=trigger"{ "success": true }
Note
This action is available only from version 2.0 of the scheduler API onwards.
Instead of deleting and recreating scheduled jobs, you can pause and resume them if necessary. This command pauses the testlog-schedule job:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ "http://localhost:8080/openidm/scheduler/job/testlog-schedule?_action=pause"{ "success": true }
This command resumes the testlog-schedule job:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ "http://localhost:8080/openidm/scheduler/job/testlog-schedule?_action=resume"{ "success": true }
Note
These actions are available only from version 2.0 of the scheduler API onwards.
In preparation for placing a server in maintenance mode, you can temporarily suspend all scheduled jobs. This action does not cancel or interrupt jobs that are already in progress; it simply prevents any scheduled jobs from being invoked during the suspension period.
This command suspends all scheduled tasks and returns true if the tasks could be suspended successfully:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ "http://localhost:8080/openidm/scheduler/job?_action=pauseJobs"{ "success": true }
When an update has been completed, and your instance is no longer in maintenance mode, you can resume scheduled jobs to start them up again. Any jobs that were missed during the downtime will follow their configured misfire policy to determine whether they should be reinvoked.
This command resumes all scheduled jobs and returns true if the jobs could be resumed successfully:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ "http://localhost:8080/openidm/scheduler/job?_action=resumeJobs"{ "success": true }
When a scheduled job is created, a trigger for that job is created automatically and is included in the schedule definition. The trigger is essentially what causes the job to be started. You can read all the triggers that have been generated on a system with the following query on the openidm/scheduler/trigger context path:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request GET \ "http://localhost:8080/openidm/scheduler/trigger?_queryFilter=true"{ "result": [ { "_id": "scheduler-service-group.trigger-testlog-schedule", "_rev": "00000000db3523f1", "calendar": null, "group": "scheduler-service-group", "jobKey": "scheduler-service-group.testlog-schedule", "name": "trigger-testlog-schedule", "nodeId": "node1", "previousState": null, "serialized": { ... }, "state": "NORMAL" } ] }
The contents of a trigger object are as follows:
_idThe ID of the trigger, which is based on the schedule ID. The trigger ID is made up of the group name, followed by
trigger-prepended to the schedule ID:group.trigger-schedule-id. For example, if the schedule ID wastestlog-schedule, then the trigger ID would bescheduler-service-group.trigger-testlog-schedule._revThe revision of the trigger object. This property is reserved for internal use and specifies the revision of the object in the repository. This is the same value that is exposed as the object's ETag through the REST API. The content of this property is not defined. No consumer should make any assumptions of its content beyond equivalence comparison.
previousStateThe previous state of the trigger, before its current state. For a description of Quartz trigger states, see the Quartz API documentation.
nameThe trigger name, which matches the ID of the schedule that created the trigger, with
trigger-added:trigger-schedule-id.stateThe current state of the trigger. For a description of Quartz trigger states, see the Quartz API documentation.
nodeIdThe ID of the node that has acquired the trigger, useful in a clustered deployment. If the trigger has not been acquired by a node yet, this will return
null.calendarThis is a part of the Quartz implementation, but is not currently supported by IDM. This will always return
null.serializedThe JSON serialization of the trigger class.
groupThe name of the group that the trigger is in, always
scheduler-service-group.jobKeyThe name of the job associated with the trigger:
group.schedule-id.
To read the contents of a specific trigger send a GET request to the trigger ID, for example:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request GET \ "http://localhost:8080/openidm/scheduler/trigger/scheduler-service-group.trigger-testlog-schedule"{ "_id": "scheduler-service-group.trigger-testlog-schedule", "_rev": "00000000cd1723dd", "calendar": null, "group": "scheduler-service-group", "jobKey": "scheduler-service-group.testlog-schedule", "name": "trigger-testlog-schedule", "nodeId": "node1", "previousState": null, "serialized": { ... }, "state": "NORMAL" }
To view the triggers that have been acquired, send a GET request to the scheduler, with a _queryFilter of nodeId. For example:
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=2.0" \
--request GET \
"http://localhost:8080/openidm/scheduler/trigger?_queryFilter=(nodeId+pr)" To view the triggers that have not yet been acquired by any node, send a GET request to the scheduler, with a _queryFilter to list the triggers with a null nodeId. For example:
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=2.0" \
--request GET \
"http://localhost:8080/openidm/scheduler/trigger?_queryFilter=%21(nodeId+pr)"To delete a schedule, send a DELETE request to the schedule ID. For example:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=2.0" \ --request DELETE \ "http://localhost:8080/openidm/scheduler/job/testlog-schedule"{ "_id": "testlog-schedule", "enabled": false, "persisted": true, "recoverable": false, "misfirePolicy": "fireAndProceed", "schedule": "0/1 * * * * ?", "repeatInterval": 0, "repeatCount": 0, "type": "cron", "invokeService": "org.forgerock.openidm.script", "invokeContext": { "script": { "type": "text/javascript", "file": "script/testlog.js" } }, "invokeLogLevel": "info", "startTime": null, "endTime": null, "concurrentExecution": false, "triggers": [], "previousRunDate": null, "nextRunDate": null }
The DELETE request returns the entire JSON object.