Recurring scheduled event starters

Three different starters let you schedule an automation in advance:

  1. Time.ScheduledTimeEvent
  2. Time.RecurringClockTimeScheduledEvent
  3. Time.RecurringSolarTimeScheduledEvent

The first, Time.ScheduledTimeEvent, lets you schedule an automation to start at either a single precise instant in the future, or on a recurring basis, based on either clock time or a solar event (that is, sunrise or sunset).

For example, this starter starts the automation at 10:00pm every day:

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(22, 0, 0, 0)))
}

Alternatively, you can specify solar time event instead of clock time. The parameter for this type of starter is a SolarTimeStruct consisting of:

  1. type, which is either SolarTimeType.Sunrise or SolarTimeType.Sunset.
  2. offset, which lets you shift the start time relative to the solar event by any amount of time. Positive values introduce a delay after the solar event, and negative values cause the starter to trigger before the solar event.

The following example is a starter that starts the automation 15 minutes before sunrise every day:

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(
    Time.ScheduledTimeEvent.solarTime(
      SolarTimeStruct(SolarTimeType.Sunrise, java.time.Duration.ofMinutes(-15))
    )
  )
}

The second two starters are recurring scheduled event starters, which let you create automations that run periodically according to more specific criteria that can include both time- and calendar-based conditions.

Time.RecurringClockTimeScheduledEvent lets you schedule an automation based on one or more time or date conditions. This starter uses a syntax that is similar to the one used by the Unix cron utility to specify the schedule for a recurring automation.

Time.RecurringSolarTimeScheduledEvent lets you schedule an automation based on either the sunrise or sunset time, optionally in combination with a calendar-based condition.

cron expressions

You may already be familiar with cron, a command used on Unix and Linux systems to schedule recurring jobs.

Recurring scheduled event starters use a scheduling expression syntax that is similar to the one used by cron, and for this reason, the scheduling expressions used with these starters are referred to as cron expressions.

There are several different 'flavors' of cron, and several variations of syntax across these implementations. Recurring scheduled event starter cron expressions use the same syntax as the Quartz scheduler. Quartz cron expression syntax is explained in the documentation for Quartz's CronExpression.

Examples

Here are a few examples to illustrate.

Use case Second Minute Hour Day-of-Month Month Day-of-Week Year
Run every 24 hours, at midnight 0 0 0 ? * * *
Run at 6:00am every Tuesday 0 30 19 ? * 3 *
Run at quarter past the hour, every hour, during the month of February 0 15 * ? 2 * *
Run once an hour 0 0 * ? * * *
Run every 24 hours, at midnight, from January to March, on the weekday closest to the 1st of the month 0 0 0 ? 1-3 1W *
On the second Thursday of February, once an hour, at a quarter past 0 15 * ? 2 5#2 *
Run at quarter past the hour, every hour, on the last day of the month of February 0 15 * L 2 ? *
Run at 6:00am every Tuesday and Thursday 0 30 19 ? * 3,5 *

RecurringClockTimeScheduledEvent

In a RecurringClockTimeScheduledEvent starter, the cron expression string is assigned to the Time.RecurringClockTimeScheduledEvent.cronExpression field.

The following is an example of a RecurringClockTimeScheduledEvent starter that starts the automation at 8:00pm, every Wednesday in April:

starter<_>(structure, event = Time.RecurringClockTimeScheduledEvent) {
  parameter(Time.RecurringClockTimeScheduledEvent.cronExpression("0 0 20 ? 4 4 *"))
}

RecurringSolarTimeScheduleEvent

The RecurringSolarTimeScheduleEvent starter takes two parameters:

  1. A SolarTimeStruct.
  2. cronExpression: A subset of a cron expression consisting of only the Day-of-Month, Month, Day-of-Week, and Year fields. The solar time determines the exact time the automation will start, therefore the Second, Minute, and Hour fields are omitted.

The following example is a starter that causes an automation to start one hour after sunrise, every Wednesday in April:

starter<_>(structure, event = Time.RecurringSolarTimeScheduledEvent) {
  parameter(
    Time.RecurringSolarTimeScheduledEvent.solarTime(
      TimeTrait.SolarTimeStruct(SolarTimeType.Sunrise, Duration.ofHours(1))
    )
  )
  parameter(Time.RecurringSolarTimeScheduledEvent.cronExpression("? 4 4 *"))
}
Previous
Complex automations
Next
Operator reference