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 org.nuxeo.ecm.core.scheduler.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 and does not need password.

The event specifies the event to execute. See the section about Events and Listeners 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:

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

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 * ?