Configure schedules
You can configure schedules in two ways:
Configure static schedule configuration
When you configure schedules in a static configuration, you can use environment secrets and variables (ESVs) in schedules to allow different settings between environments. For example, you can use ESVs to control whether a schedule is enabled and when it should run.
To use ESVs in your schedules, create or update your schedule definition by using a PUT
request against the /openidm/config/schedule/
endpoint. This endpoint creates the schedule as a static configuration and includes it in promotions.
Learn more in Configure schedules in static configuration.
Configure dynamic schedule configuration
Creating a schedule directly in your staging or production environment allows you to have greater control over your schedules on a per-environment basis. For example, you can control the intervals and enable or disable different schedules as required. Creating schedules directly in an environment sets them as a dynamic configuration that won’t be included in any subsequent promotions.
Learn more in Configure schedules in dynamic configuration.
You can use the PingIDM REST API to create dynamic schedules. However, you cannot create dynamic schedules through the UI in staging and production environments. |
Use static or dynamic schedule configuration in development
When you create schedules in your development environment, consider the following:
-
If you create a schedule through the Advanced Identity Cloud user interface (UI) in your development environment, the schedule will have a static configuration and be promoted.
-
If you use PingIDM REST to create a schedule in your development environment or you include ESVs in the schedule definition, you must use a
PUT
request against the/openidm/config/schedule/
endpoint. This endpoint ensures you create the schedule as a static configuration that is included in promotions. -
If you use the
/openidm/scheduler/job/
endpoint to create a schedule, it will bypass the configuration service and send the request directly to the scheduler. The schedule won’t be promoted because it will have a dynamic configuration. Learn more in Manage schedules using REST.
Schedule configuration format and properties
Each schedule configuration has the following format:
{
"enabled" : boolean,
"persisted" : boolean,
"recoverable" : boolean,
"concurrentExecution" : boolean,
"type" : "simple | cron",
"repeatInterval" : (optional) integer,
"repeatCount" : (optional) integer,
"startTime" : "(optional) time",
"endTime" : "(optional) time",
"schedule" : "cron expression",
"misfirePolicy" : "optional, string",
"invokeService" : "service identifier",
"invokeContext" : "service specific context info",
"invokeLogLevel" : "(optional) level"
}
The schedule configuration properties are defined as follows:
enabled
-
Set to
true
to enable the schedule. When this property isfalse
, PingIDM considers the schedule configuration inactive and does not allow it to be triggered or launched.If you want to retain a schedule configuration, but do not want it used, set
enabled
tofalse
for task and event schedulers, instead of changing the configuration orcron
expressions. persisted
(optional)-
Specifies whether the schedule state should be persisted or stored only in RAM. Boolean (
true
orfalse
),true
by default.If the schedule is stored only in RAM, the schedule will be lost when PingIDM is restarted.
recoverable
(optional)-
Specifies whether jobs that have failed mid-execution (as a result of a JVM crash or otherwise unexpected termination) should be recovered. Boolean (
true
orfalse
),false
by default. concurrentExecution
-
Specifies whether multiple instances of the same schedule can run concurrently. Boolean (
true
orfalse
),false
by default. Multiple instances of the same schedule cannot run concurrently by default. This setting prevents a new scheduled task from being launched before the same previously launched task has completed. For example, under normal circumstances you would want a liveSync operation to complete before the same operation was launched again. To enable multiple schedules to run concurrently, set this parameter totrue
. The behavior of missed scheduled tasks is governed by the misfire policy. type
-
The trigger type, either
simple
orcron
.Learn more about these trigger types in the Quartz documentation on SimpleTriggers and CronTriggers.
repeatCount
-
Used only for simple triggers (
"type" : "simple"
).The number of times the schedule must be repeated. The repeat count can be
0
, a positive integer, or-1
. A value of-1
indicates that the schedule should repeat indefinitely.If you do not specify a repeat count, the value defaults to
-1
. repeatInterval
-
Used only for simple triggers (
"type" : "simple"
).Specifies the interval, in milliseconds, between trigger firings. The repeat interval must be zero or a positive long value. If you set the repeat interval to zero, the scheduler will trigger
repeatCount
firings concurrently (or as close to concurrently as possible).If you do not specify a repeat interval, the value defaults to 0.
startTime
(optional)-
This parameter starts the schedule at some time in the future. If the parameter is omitted, empty, or set to a time in the past, the task or event is scheduled to start immediately.
Use ISO 8601 format to specify times and dates (
yyyy-MM-dd’T’HH:mm:ss
).To specify a time zone, include the time zone at the end of the
startTime
, in the format+|-hh:mm
; for example2017-10-31T15:53:00+05:00
. If you specify both astartTime
and anendTime
, they must have the same time zone. endTime
(optional)-
Specifies when the schedule must end, in ISO 8601 format (
yyyy-MM-dd’T’HH:mm:ss+|-hh:mm
. schedule
-
Used only for cron triggers (
"type" : "cron"
).Takes
cron
expression syntax. Learn more in the CronTrigger Tutorial and in Lesson 6: CronTrigger.
misfirePolicy
-
This optional parameter specifies the system behavior if the scheduled task is missed. Possible values are:
-
fireAndProceed
: The first run of a missed schedule is immediately launched when the server is back online. Subsequent runs are discarded. After this, the normal schedule is resumed. -
doNothing
: All missed schedules are discarded and the normal schedule is resumed when the server is back online.
-
invokeService
-
Defines the type of scheduled event or action. The value of this parameter can be one of the following:
-
sync
for reconciliation. -
provisioner
for liveSync. -
script
to call some other scheduled operation defined in a script. -
taskScanner
to define a scheduled task that queries a set of objects. Learn more in Scan data to trigger tasks.
-
invokeContext
-
Specifies contextual information, depending on the type of scheduled event (the value of the
invokeService
parameter).The following example invokes reconciliation:
{ "invokeService": "sync", "invokeContext": { "action": "reconcile", "mapping": "systemLdapAccount_managedUser" } }
The following example invokes a liveSync operation:
{ "invokeService": "provisioner", "invokeContext": { "action": "liveSync", "source": "system/ldap/__ACCOUNT__" } }
For scheduled liveSync tasks, the
source
property follows PingIDM’s convention for a pointer to an external resource object and takes the formsystem/resource-name/object-type
.The following example invokes a script, which prints the node ID performing the scheduled job and the time to the console.
{ "enabled" : true, "type": "simple", "repeatInterval": 3600000, "persisted" : true, "concurrentExecution" : false, "invokeService": "script", "invokeContext": { "script" : { "type" : "text/javascript", "source" : "java.lang.System.out.println('Job executing on ' + identityServer.getProperty('openidm.node.id') + ' at: ' + java.lang.System.currentTimeMillis());" } } }
These are sample configurations only. Your schedule configuration will differ according to your specific requirements.
invokeLogLevel
(optional)-
Specifies the level at which the invocation will be logged. For schedules that run very frequently, such as liveSync, the scheduled task can generate significant output to the log file. You should adjust this parameter accordingly. The default schedule log level is
info
. The value can be set to any one of the SLF4J log levels:-
trace
-
debug
-
info
-
warn
-
error
-
fatal
-