Skip to content

Add calendar schedules (day, time and timezone) to workflows #1544

Open

Description

@paullizer

Summary

Part of #1543 (Phase 1). Add a calendar schedule so a workflow can run at a local time on chosen days, such as "Mondays at 08:00 America/New_York". Today a workflow can only repeat on a fixed interval of seconds, minutes or hours (at most 59, 59 or 24), with no day of week, time of day or timezone.

User Value

People describe recurring work in calendar terms: "every Monday morning", "weekdays at 7", "the 1st of every month". An interval schedule can't express those, can't repeat less often than once a day, and has no timezone, so it drifts by an hour across daylight saving changes. Orchestration-proposed workflows (Phase 4) need calendar schedules to set up what the user actually asked for.

Proposed Behavior

  • New schedule.kind = 'calendar':
    • frequency: daily, weekdays, weekly or monthly
    • days_of_week and day_of_month
    • time_of_day as HH:MM
    • an IANA timezone
  • Personal and group normalization (_normalize_schedule, functions_personal_workflows.py:143) and compute_next_run_at (:724) support it.
  • Daylight saving is handled with zoneinfo (tzdata==2026.3 is already pinned). A local time that doesn't exist moves forward, an ambiguous one uses the first occurrence, and a day of month past the end of the month is clamped.
  • Existing interval schedules keep exactly the same stored shape. schedule is part of the Microsoft 365 Run-as fingerprint (functions_m365_workflow_binding.py:18-35), so reshaping it would invalidate existing approvals.
  • Catch-up doesn't change: a missed occurrence runs once, then the next occurrence after now is scheduled (background_tasks.py:667-704).
  • An admin minimum for new interval schedules. The minimum today is 1 second.
  • UI:
    • schedule fields in the V2 workflow editor
    • the classic UI opens calendar workflows in the V2 editor through workflowNeedsNativeEditor (workspace_workflows.js:4046-4058) instead of editing them itself
    • the MCP workflow summary shows the schedule

Acceptance Criteria

  • "Mondays 08:00 America/New_York" can be saved and edited in V2, and runs at the right UTC instant on both sides of a daylight saving change.
  • Existing interval workflows keep their next-run times and their Microsoft 365 Run-as approvals.
  • The classic UI sends calendar workflows to the V2 editor and never drops the schedule.
  • Functional tests cover daylight saving gaps and overlaps, weekly and weekday sets, monthly day 31, catch-up, and unchanged legacy fingerprints. Playwright covers the V2 schedule fields.
  • Docs updated: docs/guides/create-a-workflow.md, docs/admin/workflow.md, a feature doc and release notes. Any new setting is added to docs/_data/features.yml and the regenerated inventory. config.py version bumped.

Notes

  • Roadmap: §6, Phase 1. Related gotchas in §8: 1 (schedule gap and the 1 s minimum), 13 (relative time resolves in the schedule's timezone), 15 (fingerprint sensitivity), 16 (the classic UI can't edit calendar workflows).
  • Open decision (§9), with the recommendation: include monthly (day of month, clamped), and add an admin minimum that applies only to new interval schedules.
  • Depends on: nothing. Phase 2 (Add a workflow draft service: dry-run build, blueprint builder and provenance #1545) depends on this.

Metadata

Metadata

Labels

P1Priority 1: urgent, address before P2 workenhancementNew feature or request

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions