Updraft ScheduleScheduling StableSince v1.0

Updraft::Schedule::CronExpression

Builds a cron expression from a described intent and a named time zone, so a template can say “03:00 in Toronto, weekdays only” instead of a UTC field string that silently drifts by an hour twice a year.

Required properties 2 of 12, plus 6 conditional

Ref returns The expressioncron(0 7 ? * MON-FRI *)

Fn::GetAtt 7 attributes

Replacement risk None no property forces replacement

Minimal template

Every required property, nothing else

Resources:
  NightlyBackup:
    Type: Updraft::Schedule::CronExpression
    Properties:
      Behavior: Daily
      Time: "03:00"
      TimeZone: America/Toronto

{
  "Resources": {
    "NightlyBackup": {
      "Type": "Updraft::Schedule::CronExpression",
      "Properties": {
        "Behavior": "Daily",
        "Time": "03:00",
        "TimeZone": "America/Toronto"
      }
    }
  }
}

import { CfnResource } from 'aws-cdk-lib';

const nightly = new CfnResource(this, 'NightlyBackup', {
  type: 'Updraft::Schedule::CronExpression',
  properties: {
    Behavior: 'Daily',
    Time: '03:00',
    TimeZone: 'America/Toronto',
  },
});

// nightly.getAtt('Expression').toString() -> "cron(0 7 * * ? *)"

Read the result with Fn::GetAtt on Expression. It is already wrapped in cron(...), so it drops straight into an EventBridge ScheduleExpression.

Overview #

Cron expressions describe when badly. They have no time zone, three incompatible dialects across AWS services, and a day-of-week field whose numbering differs between them. The gap between “run at 3am Toronto time on weekdays” and cron(0 7 ? * MON-FRI *) is small enough to cross by hand and large enough to get wrong.

This resource takes the intent and emits the expression, along with a plain-English description you can check in review.

Why daylight saving is a property and not a default

EventBridge evaluates cron in UTC. It has no notion of a time zone, so a schedule in a zone that observes daylight saving cannot be expressed as a single correct UTC expression — the offset changes twice a year and the expression does not.

Every tool that generates cron from local time has to choose what to do about this, and most choose silently: they convert using today’s offset and ship. The schedule is correct for a few months, then moves by an hour, and the change is attributed to almost anything except the deployment that caused it.

DaylightSaving makes the choice explicit and defaults to Reject, which fails the stack rather than shipping a schedule that will drift. That is deliberately inconvenient. The inconvenience is one line of template against a class of bug that is genuinely hard to find later.

If the exact local hour does not matter — and for most nightly batch work it does not — set TimeZone: UTC and the whole question disappears.

What it generates #

Intent

Resources:
  NightlyBackup:
    Type: Updraft::Schedule::CronExpression
    Properties:
      Behavior: Weekly
      DaysOfWeek: [MON, TUE, WED, THU, FRI]
      Time: "03:00"
      TimeZone: America/Toronto
      DaylightSaving: PinStandard
      Jitter: 10

Result

Expression:  "cron(7 8 ? * MON-FRI *)"
UtcTime:     "08:07"
UtcOffsetMinutes: -300
ObservesDaylightSaving: true
LocalDescription: >-
  Every weekday at 03:07 America/Toronto
  (08:07 UTC, pinned to standard time)
NextOccurrences:
  - "2026-08-10T08:07:00Z"
  - "2026-08-11T08:07:00Z"
  - "2026-08-12T08:07:00Z"

The seven minutes of jitter come from hashing the stack ID. The same stack lands on the same minute every deployment; a different stack lands somewhere else.

Using it with EventBridge #

Expression is already wrapped in cron(...) for the EventBridge dialect, so it drops straight in:

Resources:
  NightlyBackup:
    Type: Updraft::Schedule::CronExpression
    Properties:
      Behavior: Daily
      Time: "03:00"
      TimeZone: UTC

  BackupRule:
    Type: AWS::Events::Rule
    Properties:
      ScheduleExpression: !GetAtt NightlyBackup.Expression
      State: ENABLED
      Targets:
        - Id: backup-lambda
          Arn: !GetAtt BackupFunction.Arn

Outputs:
  BackupSchedule:
    Description: Human-readable form of the backup schedule, for review.
    Value: !GetAtt NightlyBackup.LocalDescription

Properties

Expand a row for the full reference; nested types open in place

Behavior StringThe shape of the schedule, which determines which other properties apply. Required

Each behavior consumes a different subset of the remaining properties. A property that does not apply to the chosen behavior is rejected rather than ignored, so a misplaced DaysOfWeek fails the stack instead of quietly doing nothing.

Behavior	Uses
`Daily`	`Time`
`Weekly`	`Time`, `DaysOfWeek`
`Monthly`	`Time`, `DayOfMonth`
`EveryNHours`	`Interval`, `Time` (as the offset within the hour)
`EveryNMinutes`	`Interval`
`BusinessHours`	`Time`, `EndTime`, `DaysOfWeek`, `Interval`
`Custom`	`Expression`

Type: String
Required: Yes
Update behaviour: No interruption

Allowed values

Daily
Weekly
Monthly
EveryNHours
EveryNMinutes
BusinessHours
Custom

Example values

Daily

TimeZone StringIANA time zone name that Time is expressed in. Required No interruption — updates in place
The zone is resolved against the IANA database at stack-operation time and converted to a fixed UTC expression.
Type
String
Required
Yes
Update behaviour
No interruption
Pattern
^([A-Za-z_]+/[A-Za-z_+\-0-9/]+|UTC)$ IANA zone name. Fixed offsets such as `-05:00` are deliberately not accepted.
Example values
- America/Toronto
- Europe/London
- UTC
The conversion happens once, at deploy time
EventBridge cron expressions are evaluated in UTC and have no concept of a time zone. This resource converts your local time to UTC when the stack runs, using the offset in effect on that date.
For a zone that observes daylight saving, that means the schedule is correct for half the year and an hour off for the other half. A 03:00 America/Toronto schedule deployed in January fires at 03:00 local until March, then at 04:00 local until November.
DaylightSaving controls what to do about it, and defaults to failing loudly rather than shipping a schedule that will quietly move.
DayOfMonth StringDay of the month, or L for the last day. Conditional No interruption — updates in place
Days 29 to 31 simply do not fire in months that lack them; EventBridge does not clamp. Use L for “end of month” rather than 31.
Type
String
Required
ConditionalRequired for Monthly.
Update behaviour
No interruption
Pattern
^(L|[1-9]|[12]\d|3[01])$
Example values
- 1
- 15
- L
DaysOfWeek Array of StringDays the schedule fires on. Conditional No interruption — updates in place
Days the schedule fires on.
Type
Array of String
Required
ConditionalRequired for Weekly. Optional for BusinessHours, where it defaults to Monday–Friday.
Update behaviour
No interruption
Items
1 – 7 must be unique
Allowed values
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
Example values
- ["MON","TUE","WED","THU","FRI"]
A time zone conversion can move the day, not just the hour
Time: "23:30" on MON in America/Toronto is 03:30 UTC on Tuesday. The generated expression accounts for this and shifts the day-of-week field accordingly — which means the UTC expression will not look like what you wrote, and that is correct.
Check LocalDescription rather than reading the raw cron fields back.
EndTime StringLocal end of the window for BusinessHours, exclusive. Conditional No interruption — updates in place
Local end of the window for BusinessHours, exclusive.
Type
String
Required
ConditionalRequired for BusinessHours.
Update behaviour
No interruption
Pattern
^([01]\d|2[0-3]):([0-5]\d)$
Example values
- 17:00
Expression StringA raw six-field cron expression, validated and passed through. Conditional No interruption — updates in place
Escape hatch for schedules the other behaviors cannot express. The expression is still parsed and validated, and NextOccurrences is still computed, so Custom does not mean unchecked.
Type
String
Required
ConditionalRequired for Custom.
Update behaviour
No interruption
Example values
- 0 7 ? * MON-FRI *
Interval IntegerRepeat interval, in the unit implied by Behavior. Conditional No interruption — updates in place
For EveryNHours the interval must divide 24 evenly, otherwise the schedule skips at midnight. 5 is rejected for that reason; 6 and 8 are fine.
Type
Integer
Required
ConditionalRequired for EveryNHours, EveryNMinutes, and BusinessHours.
Update behaviour
No interruption
Range
1 – 23
Example values
- 6
Time StringLocal time of day in 24-hour HH:MM. Conditional No interruption — updates in place
For EveryNHours this is interpreted as the offset within each hour, so Time: "00:20" with Interval: 6 fires at 00:20, 06:20, 12:20 and 18:20.
Type
String
Required
ConditionalRequired for Daily, Weekly, Monthly, and BusinessHours.
Update behaviour
No interruption
Pattern
^([01]\d|2[0-3]):([0-5]\d)$ 24-hour clock, zero-padded.
Example values
- 03:00
- 23:30
DaylightSaving StringHow to handle a zone whose UTC offset changes during the year. No interruption — updates in place
- Reject — fail the stack operation if the zone observes DST. Forces the decision to be made explicitly, in the template, by whoever can judge it.
- PinStandard — always use the zone’s standard-time offset. The schedule is an hour late during summer time, and never moves.
- PinCurrent — use whichever offset is in effect on the deployment date. The schedule is correct today and wrong in six months.
- SplitExpressions — emit two expressions in ExpressionSet, one per offset, each with a month range. Correct all year, but requires the consumer to accept a list of schedules.
Type
String
Required
No
Update behaviour
No interruption
Default
Reject
Allowed values
- Reject
- PinStandard
- PinCurrent
- SplitExpressions
Tip
If the job’s exact local hour does not actually matter — most nightly batch work — set TimeZone: UTC and stop thinking about it. The machinery below exists for the schedules where it genuinely does matter, such as anything that must not overlap a business day.
Jitter IntegerDeterministic spread, in minutes, applied to the computed time. No interruption — updates in place
The offset is derived by hashing JitterSeed, so it is stable across deployments — the same stack always lands on the same minute. This spreads a fleet of identically-scheduled stacks without making any single stack’s schedule unpredictable.
Type
Integer
Required
No
Update behaviour
No interruption
Default
0
Range
−∞ – 59
Remarks
Jitter matters more than it sounds. A hundred accounts all running a backup at exactly 03:00 UTC produce a hundred simultaneous API bursts against the same regional endpoints, and the resulting throttling looks like a service problem rather than a scheduling one. Ten minutes of spread costs nothing and removes the thundering herd.
JitterSeed StringSeed for the jitter hash. Defaults to the stack ID. No interruption — updates in place
Give two stacks the same seed and they land on the same minute — occasionally useful when two schedules must stay aligned.
Type
String
Required
No
Update behaviour
No interruption
Example values
- ${AWS::StackId}
Target StringWhich service will consume the expression, which changes its syntax. No interruption — updates in place
EventBridge cron takes six fields and wraps them in cron(...). Auto Scaling takes five fields, unwrapped, and treats day-of-week 0 as Sunday. Emitting the wrong dialect is one of the more tedious ways to lose an afternoon, so the resource emits the right one.
Type
String
Required
No
Update behaviour
No interruption
Default
EventBridge
Allowed values
- EventBridge
- AutoScaling
- Backup
- SSM

Property	Type	Required	Update	Description
Behavior	`String`	Yes	None	The shape of the schedule, which determines which other properties apply.
TimeZone	`String`	Yes	None	IANA time zone name that Time is expressed in.
DayOfMonth	`String`	Conditional	None	Day of the month, or L for the last day.
DaysOfWeek	`Array of String`	Conditional	None	Days the schedule fires on.
EndTime	`String`	Conditional	None	Local end of the window for BusinessHours, exclusive.
Expression	`String`	Conditional	None	A raw six-field cron expression, validated and passed through.
Interval	`Integer`	Conditional	None	Repeat interval, in the unit implied by Behavior.
Time	`String`	Conditional	None	Local time of day in 24-hour HH:MM.
DaylightSaving	`String`	No	None	How to handle a zone whose UTC offset changes during the year.
Jitter	`Integer`	No	None	Deterministic spread, in minutes, applied to the computed time.
JitterSeed	`String`	No	None	Seed for the jitter hash. Defaults to the stack ID.
Target	`String`	No	None	Which service will consume the expression, which changes its syntax.

Generated from the schema. The first pair shows only required and conditionally-required properties — a template you can paste and deploy. Property keys are ordered alphabetically here rather than required-first, because that is the order a template file conventionally uses.

Type: Updraft::Schedule::CronExpression
Properties:
  Behavior: Daily
  DayOfMonth: '1'
  DaysOfWeek:
  - String
  EndTime: '17:00'
  Expression: 0 7 ? * MON-FRI *
  Interval: '6'
  Time: '03:00'
  TimeZone: America/Toronto

{
  "Type": "Updraft::Schedule::CronExpression",
  "Properties": {
    "Behavior": "Daily",
    "DayOfMonth": "1",
    "DaysOfWeek": [
      "String"
    ],
    "EndTime": "17:00",
    "Expression": "0 7 ? * MON-FRI *",
    "Interval": "6",
    "Time": "03:00",
    "TimeZone": "America/Toronto"
  }
}

Every property, three levels deep:

Type: Updraft::Schedule::CronExpression
Properties:
  Behavior: Daily
  DayOfMonth: '1'
  DaylightSaving: Reject
  DaysOfWeek:
  - String
  EndTime: '17:00'
  Expression: 0 7 ? * MON-FRI *
  Interval: '6'
  Jitter: 0
  JitterSeed: ${AWS::StackId}
  Target: EventBridge
  Time: '03:00'
  TimeZone: America/Toronto

{
  "Type": "Updraft::Schedule::CronExpression",
  "Properties": {
    "Behavior": "Daily",
    "DayOfMonth": "1",
    "DaylightSaving": "Reject",
    "DaysOfWeek": [
      "String"
    ],
    "EndTime": "17:00",
    "Expression": "0 7 ? * MON-FRI *",
    "Interval": "6",
    "Jitter": 0,
    "JitterSeed": "${AWS::StackId}",
    "Target": "EventBridge",
    "Time": "03:00",
    "TimeZone": "America/Toronto"
  }
}

updates in place some interruption replacement create-only read-only write-only

Return values

What other resources can read from this one

Ref

Returns the generated expression — the same value as Fn::GetAtt [ Schedule, Expression ], so it can be dropped straight into a ScheduleExpression property.

!Ref MyResource → cron(0 7 ? * MON-FRI *)

`Fn::GetAtt` attributes

Attribute	Type	Description	Example value
Expression	`String`	The generated expression, in the dialect selected by Target.	`cron(0 7 ? * MON-FRI *)`
ExpressionSet	`Array`	All generated expressions. One entry unless DaylightSaving is SplitExpressions.	`["cron(0 8 ? * MON-FRI )","cron(0 7 ? MON-FRI *)"]`
LocalDescription	`String`	A plain-English rendering of the schedule. Put it in a stack output — it is the fastest way to catch a wrong schedule during review.	`Every weekday at 03:00 America/Toronto (07:00 UTC during standard time)`
NextOccurrences	`Array`	The next five fire times in UTC, computed at deploy time.	`["2026-08-10T07:00:00Z","2026-08-11T07:00:00Z"]`
ObservesDaylightSaving	`Boolean`	Whether the named zone changes offset during the year.	`true`
UtcOffsetMinutes	`Integer`	The zone offset applied, in minutes east of UTC.	`-300`
UtcTime	`String`	The computed UTC time of day, for eyeballing against the local time you asked for.	`07:00`

Required permissions

For the principal running the stack operation

This type makes no AWS API calls. It is computed entirely from its own properties during the stack operation, so it needs no permissions beyond those CloudFormation already holds to manage the stack.

Examples

1 worked scenario

Region-staggered maintenance One template, deployed to eight regions, that gives each region a different maintenance window in a deliberate order — so a bad change reaches the regions you watch first. AdvancedUpdraft::Schedule::CronExpressionUpdraft::Region::StaggerUpdraft::Region::MetadataDiagram

Minimal template

Overview #

What it generates #

Using it with EventBridge #

Properties

Return values

Fn::GetAtt attributes

Required permissions

Examples

Related types

`Fn::GetAtt` attributes