Skip to main content

Schedule Exceptions

Schedule Exceptions are named date or date+time windows that override one or more Macro Schedules. Use them for holidays, vacations, parties, or any window where the normal cron rule should skip, run a different macro, or fire only during the window.

Open Schedule Exceptions

Overview​

An exception is a window (one-time or yearly-recurring) attached to one or more schedules. When a schedule fires, the scheduler checks each attached exception that is currently active and applies the link's action:

  • Skip — suppress this firing entirely
  • Substitute — run a different macro in place of the schedule's normal macro
  • Only During — schedule fires only when this exception is active (and is suppressed at all other times)

Each link is per-schedule, so the same exception (e.g., august_vacation) can skip one schedule, substitute another, and gate a third.

Viewing Exceptions​

The grid shows:

  • ID — Unique identifier
  • Name — Internal name (lowercase_with_underscores)
  • Description — Free-text purpose
  • Start Date / End Date — Window bounds (DATEONLY)
  • Start Time / End Time — Optional precise clock times
  • Recurrence — One time (none) or Every year (yearly, same month + day every year)
  • Enabled — Disabled exceptions are ignored by the scheduler

Creating an Exception​

  1. Click Add in the grid toolbar.
  2. Fill in Name, Description, and the Window (dates plus optional times).
  3. Save the exception.
  4. Attach it to schedules (the attachment table appears after the first save).

Window​

Start Date / End Date are required. Time of day is optional:

  • Precise Times toggle off — the window covers the full start and end days (midnight to 23:59:59).
  • Precise Times toggle on — the window is precise to the minute. Use this for late-night events that cross midnight, e.g. a party from Saturday 18:00 to Sunday 02:00.

Recurrence:

  • none — one-time window between the literal start and end dates.
  • yearly — repeats every year on the same month/day. Year-wrap is handled correctly (e.g., Dec 24 → Jan 2 spans the new year).

A live preview line summarizes the resolved window beneath the form.

Attaching Schedules​

After saving, the Attached Schedules section lets you pick one or more macro schedules to affect. For each link choose an action:

ActionEffect when window is activeEffect when window is inactive
SkipSchedule does not runSchedule runs normally
SubstituteRuns the chosen substitute macro insteadSchedule runs normally
Only DuringSchedule runs normallySchedule does not run

For Substitute, pick a macro from the dropdown. If a substitute is missing when the window fires, the schedule is skipped (fail-safe) — the editor warns you when you save a substitute link without a macro chosen, and the attachment row shows "⚠ no substitute macro chosen — will be skipped" until you pick one.

You can also attach exceptions from the other direction — open a schedule in the Schedules editor and use the Exceptions panel.

Effect on Calendar​

Once one or more schedules are attached, an Effect on Calendar preview appears below the attachment table. It forecasts how the attached schedules fire with this exception applied:

  • Struck-through times are firings this exception skips.
  • Times with ⟳ are firings that run a substitute macro instead.
  • Shaded days fall inside this exception's window.

The preview uses the live scheduler resolver, so it reflects exactly what will happen — including edits to a link's action made earlier in the same session. It updates whenever you change the window dates/times, recurrence, or an attached link.

Resolution Rules​

When a schedule fires the scheduler walks every attached link in order:

  1. Any active Skip link wins — the firing is logged as skipped with reason exception:<name>.
  2. An active Substitute link replaces the schedule's macro for this firing and logs exception:<name> -> <substitute_macro>.
  3. If at least one Only During link is attached and none are currently active, the firing is skipped with reason exception:no_only_during_active.
  4. Otherwise the schedule runs its normal macro.

Skipped and substituted firings appear in the schedule's Run History panel with the reason recorded, so you can audit what happened.

tip

"Only During" is the inverse of "Skip" — pair it with a window like [$sunset]-based schedules during a holiday lighting season to gate the schedule to that season without changing the cron rule.

Example Patterns​

Holiday Skip​

Name: thanksgiving_day
Window: 2026-11-26 (full day)
Recurrence: none
Link: morning_lights → Skip

Yearly Vacation Substitution​

Name: christmas_week
Window: 2026-12-24 → 2027-01-02 (full days)
Recurrence: yearly
Link: evening_lights → Substitute → holiday_evening_lights

Late-Night Party (crosses midnight)​

Name: nye_party
Window: 2026-12-31 18:00 → 2027-01-01 02:00 (precise times)
Recurrence: none
Link: bedtime_routine → Skip
Link: outdoor_lights_off → Skip

Seasonal Gate (Only During)​

Name: summer_pool_season
Window: 2026-05-01 → 2026-09-30 (full days)
Recurrence: yearly
Link: pool_filter_cycle → Only During