<?xml version="1.0" encoding="UTF-8"?>

<appendix xml:id="appendix-scheduling"

xmlns="http://docbook.org/ns/docbook"

version="5.0"

xml:lang="en"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"

xmlns:xlink="http://www.w3.org/1999/xlink"

xmlns:xinclude="http://www.w3.org/2001/XInclude">

<title>Scheduler Reference</title>

<para>OpenIDM lets you schedule many tasks and events including reconciliation

and synchronization, but also arbitrary events by use of scheduler

objects.</para>

<para>OpenIDM supports <command>cron</command>-like syntax to schedule events

and tasks, based on expressions supported by the Quartz Scheduler that OpenIDM

bundles.</para>

<para>If you use configuration files to schedule tasks and events, then the

scheduler files are located in the <filename>openidm/conf</filename> directory.

By convention, OpenIDM uses file names of the form

<filename>scheduler-<replaceable>schedule-name</replaceable>.json</filename>.

OpenIDM dynamically picks up changes to scheduled tasks and events are both

during initialization and also during runtime.</para>

<variablelist xml:id="scheduler-configuration-objects">

<title>Scheduler Configuration Objects</title>

<para>Scheduler configuration objects take the following form.</para>

<programlisting language="javascript">

{

"enabled" : true,

"type" : "cron",

"startTime" : "<replaceable>optional time</replaceable>",

"endTime" : "<replaceable>optional time</replaceable>",

"schedule" : "<replaceable>cron expression</replaceable>",

"timeZone" : "<replaceable>optional time zone</replaceable>",

"invokeService" : "<replaceable>service identifier</replaceable>",

"invokeContext" : "<replaceable>service specific context info</replaceable>"

}</programlisting>

<para>The following simple example prints <literal>Hello World</literal> to

the OpenIDM log, <filename>/openidm/logs/openidm0.log.X</filename>,

each minute.</para>

<programlisting language="javascript">

{

"enabled": true,

"type": "cron",

"schedule": "0 0/1 * * * ?",

"invokeService": "discovery-engine",

"invokeContext": {

"script": {

"type": "text/javascript",

"source": "java.lang.System.out.println('Hello World’);"

},

"input": {

"edit": 26

}

}

}</programlisting>

<para>Scheduler configuration objects take the following properties.</para>

<varlistentry>

<term>enabled</term>

<listitem>

<para>Set to <literal>true</literal> to enable the scheduler. When set to

<literal>false</literal>, OpenIDM considers the scheduler configuration

object dormant, and therefore does not let it be triggered or

executed.</para>

<para>Rather than change the configuration or <command>cron</command>

expressions, set <literal>enabled</literal> to <literal>false</literal>

for task and event schedulers when you want to retain their configuration,

but do not want them used.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>type</term>

<listitem>

<para>Currently OpenIDM supports only <literal>cron</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>startTime (optional)</term>

<listitem>

<para>Used to start the schedule some time in the future. If omitted or

set to a time in the past, the task or event is scheduled starting

immediately.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>endTime (optional)</term>

<listitem>

<para>Used to plan the end of scheduling.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>schedule</term>

<listitem>

<para>Takes <command>cron</command> expression syntax.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>timeZone (optional)</term>

<listitem>

<para>If not set, OpenIDM uses the system time zone.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>invokeService</term>

<listitem>

<para>Defines the type of scheduled event or action. OpenIDM accepts the

following values.</para>

<itemizedlist>

<listitem><para><literal>discovery-engine</literal></para></listitem>

<listitem><para><literal>provisioner</literal></para></listitem>

<listitem><para><literal>script</literal></para></listitem>

<listitem><para><literal>sync</literal></para></listitem>

</itemizedlist>

</listitem>

</varlistentry>

<varlistentry>

<term>invokeContext</term>

<listitem>

<para>Specifies contextual information, such as the JavaScript to invoke.

The discovery engine provides two mechanisms, reconciliation and

synchronization. Both require that you specify the

<literal>invokeContext</literal>.</para>

<para>The following example invokes reconciliation.</para>

<programlisting language="javascript">

{

"enabled": true,

"type": "cron",

"schedule": "0 0/1 * * * ?",

"invokeService": "discovery-engine",

"invokeContext": {

"action": "reconcile",

"mapping": "systemLdapAccount_managedUser"

}

}</programlisting>

<para>For reconciliation tasks, you can add the mapping definition inline

rather than define it in <filename>openidm/conf/sync.json</filename>.</para>

<para>The following example shows a scheduler for LiveSync.</para>

<programlisting language="javascript">

{

"enabled": true,

"type": "cron",

"schedule": "0 0/1 * * * ?",

"invokeService": "discovery-engine",

"invokeContext": {

"action": "liveSync",

"source": "system/OpenDJ/__ACCOUNT__"

}

}</programlisting>

<para>Actual configuration differs from these examples depending on your

configuration.</para>

</listitem>

</varlistentry>

</variablelist>

<section xml:id="scheduled-task-use-cases">

<title>Scheduled Task Use Cases</title>

<para>OpenIDM lets you schedule not only reconciliation and synchronization,

but also lets you use scheduling to trigger scripts, collect and run reports,

trigger workflows, perform custom logging, and so forth. You can find a

set of samples in the <filename>openidm/samples/schedules</filename>

directory.</para>

</section>

<section xml:id="cron-expressions">

<title>Cron Expressions</title>

<para>The Quartz Scheduler accepts expressions like those of the UNIX

<command>cron</command> command. The syntax is documented extensively in

the online Quartz <link xlink:show="new"

xlink:href="http://www.quartz-scheduler.org/documentation/quartz-1.x/tutorials/crontrigger"

><citetitle>CronTrigger Tutorial</citetitle></link>.</para>

</section>

<section xml:id="check-quartz-updates">

<title>Checking For Quartz Updates</title>

<para>The Quartz Scheduler can check for updates over the Internet on the

Quartz project website, and report available updates in the OpenIDM log.

The option is set in <filename>openidm/conf/system.properties</filename>

By default, this option is turned off, and should remain off in

production.</para>

<literallayout class="monospaced">system.properties:org.quartz.scheduler.skipUpdateCheck = true</literallayout>

</section>

<section xml:id="scheduler-service-implementations">

<title>Service Implementer Notes</title>

<para>Services that can be scheduled implement

<literal>ScheduledService</literal>. The service PID is used as a basis for

the service identifier in schedule definitions.</para>

</section>

</appendix>