Scheduling Periodic Events

The Scheduler Service is a Nuxeo Platform service to schedule events at periodic times. This is the best way in Nuxeo Platform to execute things every night, every hour, every five minutes, or at whatever granularity you require.

Scheduler Contribution

To schedule an event, you contribute a <schedule> to the schedule extension point of the SchedulerService component.

A schedule is defined by:

• id: an identifier.
• username: the user under which the event should be executed.
• event: the identifier of the event to execute.
• eventCategory: the event category to use.
• cronExpression: an expression to specify the schedule.

The id is used for informational purposes and programmatic unregistration.

If the username is missing, the event is executed as a system user, otherwise as that user. No password is needed: the login is done internally.

The event specifies the event to execute. See the page about Events and Messages for more.

The eventCategory is also used to specify the event, but usually it can be skipped.

The cronExpression is described in the following section.

Here is an example contribution:

<extension target="org.nuxeo.ecm.core.scheduler.SchedulerService" point="schedule">
  <schedule id="monthly_stuff">
    <eventId>doStuff</eventId>
    <eventCategory>default</eventCategory>
    <!-- Every first of the month at 3am -->
    <cronExpression>0 0 3 1 * ?</cronExpression>
  </schedule>
</extension>

Cron Expression

A Scheduler cron expression is similar to a Unix cron expression, except that it has an additional seconds field (that isn't needed in Unix which doesn't need this kind of precision).

The expression is a sequence of 6 or 7 fields. Each field can hold a number or a wildcard, or in complex cases a sequence of numbers or an additional increment specification. The fields and their allowed values are:

A star (*) can be used to mean "all values". A question mark (?) can be used to mean "no specific value" and is allowed for one (but not both) of the day of month and day of week fields.

Note that in the day of week, 1 stands for Sunday, 2 for Monday, 3 for Tuesday, etc. For clarity it's best to use SUN, MON, TUE, etc.

A range of values can be specified using a dash, for instance 1-6 for the months field or MON-WED for the day of week field.

Several values can be specified by separating them with commas, for instance 0,15,30,45 for the minutes field.

Repetitions can be specified using a slash followed by an increment, for instance 0/15 means start at 0 and repeat every 15. This example means the same as the one above.

There's actually more but rarely used functionality; the Scheduler's full cron expression syntax is described in detail in the Quartz CronExpression Javadoc and in the CronTrigger Tutorial.

Cron Expression Examples

Every first of the month at 3:15am:

0 15 3 1 * ?

At 3:15am every day:

0 15 3 * * ?

Every minute starting at 2pm and ending at 2:15pm, every day:

0 0-15 14 * * ?

At 3:15am every Monday, Tuesday, Wednesday, Thursday and Friday:

0 15 3 ? * MON-FRI

At 3:15a, every 5 days every month, starting on the first day of the month:

0 15 3 1/5 * ?

Scheduler and Events

In order to run the scheduler, you need to register a new event into the Core Event Registry. Navigate to Settings > Registries > Core Events and add the event you've created in the <eventId> tag.

{
  "events": {
    "doStuff": "My scheduler event"
  }
}

Finally, create a new event handler from Configuration > Automation > Event Handlers and activate the event you've just created:

×

In the Event Handler Activation, update the Current document is filter value from “Regular Document” to “Any”.

×

Automation

When using the Scheduler Service to trigger Automation Chains through Event Listener and Event Handler, the Core Session cannot be retrieved and cannot be set within the Operation Context (Core Session is not found).

If the need is to execute operations needing an operation context session, the first operation of the chain should be LoginAs Operation. It will create a new authenticated session and set the Automation context session accordingly.

Clustering

Note that when Nuxeo is used in cluster mode, and a proper cluster-aware Quartz configuration is done, then a given schedule is triggered only on one of the nodes of the cluster, not on all nodes.