Skip to main content

Interface: ScheduleSpec

client.ScheduleSpec

A complete description of a set of absolute times (possibly infinite) that an Action should occur at. The times are the union of calendars, intervals, and cronExpressions, minus the skip times. These times never change, except that the definition of a time zone can change over time (most commonly, when daylight saving time policy changes for an area). To create a totally self-contained ScheduleSpec, use UTC.

Properties​

calendars​

• Optional calendars: CalendarSpec[]

Calendar-based specifications of times.

cronExpressions​

• Optional cronExpressions: string[]

Cron expressions. This is provided for easy migration from legacy Cron Workflows. For new use cases, we recommend using calendars or intervals for readability and maintainability.

For example, 0 12 * * MON-WED,FRI is every M/Tu/W/F at noon, and is equivalent to this CalendarSpec:

{
  hour: 12,
  dayOfWeek: [{
    start: 'MONDAY'
    end: 'WEDNESDAY'
  }, 'FRIDAY']
}

The string can have 5, 6, or 7 fields, separated by spaces, and they are interpreted in the same way as a CalendarSpec.

  • 5 fields: minute, hour, day_of_month, month, day_of_week
  • 6 fields: minute, hour, day_of_month, month, day_of_week, year
  • 7 fields: second, minute, hour, day_of_month, month, day_of_week, year

Notes:

  • If year is not given, it defaults to *.
  • If second is not given, it defaults to 0.
  • Shorthands @yearly, @monthly, @weekly, @daily, and @hourly are also accepted instead of the 5-7 time fields.
  • @every interval[/<phase>] is accepted and gets compiled into an IntervalSpec instead. <interval> and <phase> should be a decimal integer with a unit suffix s, m, h, or d.
  • Optionally, the string can be preceded by CRON_TZ=<timezone name> or TZ=<timezone name>, which will get copied to timezone. (In which case the timezone field should be left empty.)
  • Optionally, "#" followed by a comment can appear at the end of the string.
  • Note that the special case that some cron implementations have for treating day_of_month and day_of_week as "or" instead of "and" when both are set is not implemented.

endAt​

• Optional endAt: Date

Any times after endAt will be skipped.

Default

The end of time

intervals​

• Optional intervals: IntervalSpec[]

Interval-based specifications of times.

jitter​

• Optional jitter: Duration

All times will be incremented by a random value from 0 to this amount of jitter.

Default

0

Format

number of milliseconds or ms-formatted string

skip​

• Optional skip: CalendarSpec[]

Any matching times will be skipped.

All aspects of the CalendarSpec—including seconds—must match a time for the time to be skipped.

startAt​

• Optional startAt: Date

Any times before startAt will be skipped. Together, startAt and endAt make an inclusive interval.

Default

The beginning of time

timezone​

• Optional timezone: string

IANA timezone name, for example US/Pacific.

https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

The definition will be loaded by Temporal Server from the environment it runs in.

Calendar spec matching is based on literal matching of the clock time with no special handling of DST: if you write a calendar spec that fires at 2:30am and specify a time zone that follows DST, that action will not be triggered on the day that has no 2:30am. Similarly, an action that fires at 1:30am will be triggered twice on the day that has two 1:30s.

Also note that no actions are taken on leap-seconds (e.g. 23:59:60 UTC).

Default

UTC