Zum Hauptinhalt springen

Recurring workflow triggers

Workflow definition format 1 supports one recurring trigger with an explicit IANA timezone. Save it in a working workflow version, then publish that version. First publication also enables the workflow; publishing a newer version preserves its current live or paused state. Saving a draft does not change its schedule. The workflow scheduler starts each eligible occurrence.

{
"id": "00000000-0000-4000-8000-000000000001",
"type": "recurring",
"timezone": "Europe/Vienna",
"schedule": {
"frequency": "weekly",
"weekdays": [1, 3, 5],
"time": "09:00"
}
}
FrequencySchedule fields
dailytime in HH:mm form
weeklytime and nonempty weekdays, ISO Monday 1 through Sunday 7
monthlytime and nonempty days_of_month, from 1 through 31
cronexpression, five numeric fields: minute, hour, day-of-month, month, weekday

Weekly and monthly selections accept multiple days. Cron supports *, comma-separated lists, ascending ranges and positive steps. Cron weekdays use 0 or 7 for Sunday. For example, 0 9 * * 1-5 means weekdays at 09:00. When day-of-month and weekday are both restricted, both must match. Seconds, year fields, named weekdays/months and inline timezone overrides are not supported. Each frequency accepts only its own fields.

The timezone is retained in the publication. Changing workspace regional settings does not change an existing published schedule.

Preview​

POST /frontend/v2/workflows/editor/schedule-preview requires workflows:manage and returns 200 with up to five eligible occurrences. It creates no workflow, schedule or run.

{
"timezone": "Europe/Vienna",
"schedule": {"frequency": "monthly", "days_of_month": [1, 15], "time": "09:00"},
"scheduled_after": "2026-09-08T00:00:00Z"
}

Omit scheduled_after to use current server time. An explicit cutoff accepts RFC 3339 timestamps from year 1970 through 9999. Results are strictly after that instant. Evaluation stops when either the local calendar year or the UTC occurrence year exceeds 2100, so the response can contain fewer than five items, including an empty list. Sparse calendars also return only the dates remaining within that horizon. The response contains timezone and items; each item includes scheduled_at as an RFC 3339 instant, local_time as yyyy-MM-dd'T'HH:mm, and utc_offset, such as +02:00 or Z. Invalid calendars, timezones, fields or query parameters return field-level 422 problems. Missing authentication returns 401; missing permission returns 403 with the usual denial data. These read-only endpoints support the workflow editor. They have no public or MCP equivalent; public clients author and publish recurring versions directly using the documented calendar contract and returned version validation issues.

Full workflow preview uses POST /frontend/v2/workflows/editor/preview with draft and no record_id. It simulates the next eligible occurrence and returns its schedule context. If none remains within the supported horizon, it returns 422 at #/draft/triggers/0/schedule. Preview does not simulate runtime overlap or outages and does not create Tasks or answer questions.

Execution and timing​

  • An open earlier run, including a pending approval, causes overlapping occurrences to be skipped.
  • Starts more than five minutes late are skipped. Already admitted runs retain durable recovery.
  • Enabling or re-enabling begins with a future occurrence; the disabled period is not replayed.
  • Nonexistent monthly days and local times during a daylight-saving gap are skipped. Ambiguous repeated local times are skipped at both UTC offsets.
  • Disabling stops new admissions. An active run continues and can still be answered or cancelled.
  • Publishing changes affects future admissions. Existing runs retain their original publication and captured inputs. A failed run does not pause future occurrences.

Recurring triggers provide schedule.scheduled_at and schedule.admitted_at as date/time fields, and schedule.timezone as text. They do not provide a triggering record. Task and question steps must set link_trigger_record: false; record actions must choose their record inputs explicitly. No implicit record search or iteration occurs.

Run inspection returns trigger_input.type: "recurring", event_id, occurred_at, scheduled_at, admitted_at and timezone. Record runs use trigger_input.type: "record". Internal schedule and operation diagnostics are available to system support through the admin inspection API.

Schedule status​

Workflow reads and list summaries include schedule_status for a published recurring workflow. Its state is active when the workflow is enabled and paused when disabled; next_occurrence reports the next computed firing timestamp when active. Schedule state and next_occurrence are updated synchronously when publishing, enabling, disabling or deleting a workflow; existing active-run deletion blockers still apply. System support can inspect retained schedule state through the admin API.