Maintenance Windows
Start and approve a run ahead of time, and let it do the risky part only inside its maintenance window. The run waits with the status WAITING_WINDOW, so it is easy to tell apart from a run waiting for an approval or a paused run.
Two pieces make this work:
- a Maintenance window field in the flow's form, where the person who starts the run picks the window;
- a Wait for window node in the flow graph, which holds the run until that window opens.
A typical flow: pre-checks, an Approval, then Wait for window, then the change itself and the post-checks.
Set up the flow
- In the form designer, add a Maintenance window field (category Scheduling) and save the form. Mark it required if every run needs a window.
- In the flow graph, add a Wait for window node from the add-node menu. In its panel, choose the window field under Maintenance window input. Optionally add a Message; the run page and the Runs list show it while the run waits. It can use the run's own values: add a text field such as
change_ticketto the form and writeChange {{ inputs.change_ticket }}, and each run shows its own ticket. The message renders once, when the run reaches the node, with the same values an approval's text can use (inputs, step outputs, variables, targets) and never secrets. A message that does not render is shown as written. - Connect the node's success output to the work to do in the window, and its failure output to what should happen when the window is missed (for example a notification step and a failure terminal).
Saving the flow checks that the node names a Maintenance window field of the form. It also warns when:
- the field is optional: a run started without a window fails at the node and follows failure;
- another flow runs this one as a child flow and waits for it. The parent's step cancels the child when the step's time limit runs out (two hours by default), so set that limit longer than the longest wait, or turn off waiting for completion.
Pick a window when starting a run
The Maintenance window field asks for:
- Starts - the date and time the window opens;
- Time zone - the zone the times are in (defaults to your browser's);
- Length - 1, 2, 4 or 8 hours, or Custom to enter an end time.
The platform stores the window as UTC times, with the daylight-saving rules of the chosen zone. The length buttons count real hours, so "2 h" stays two hours on the night the clocks change. A start or end time the clocks skip (02:30 on the night they go forward, in most of Europe) is refused; a time they repeat (the night they go back) means the first of the two. A run whose window has already ended is refused when it is created. The form sends the window as UTC times, and the API (POST /runs) takes the same value:
{"mw": {"start": "2026-11-15T01:00:00Z", "end": "2026-11-15T03:00:00Z", "timezone": "Europe/Prague"}}start and end may also be wall-clock times in the window's zone, without an offset (2026-11-15T02:00).
A schedule stores the dates you pick, not a rule for them. A one-time schedule works when the window ends after the schedule runs. A repeating schedule replays the same window, so every run after the window has passed is refused; the schedule form warns about this.
What happens when the run reaches the node
| When the run reaches the node | What happens |
|---|---|
| Before the window starts | The branch waits. The run status becomes WAITING_WINDOW when nothing else in the run is working. When the window opens, the run is RUNNING again and continues on success. |
| Inside the window | The node succeeds at once. |
| After the window ended | The node fails with "Maintenance window missed" and the run follows failure. |
The wait is a durable Temporal timer: a worker restart does not restart or lose it. If the platform was down when the window opened and comes back after the window ended, the node fails as missed rather than starting the work late.
Only the waiting branch stops. Other branches of a fork keep working and their approvals can be answered. While other branches work, the run stays RUNNING (or WAITING_APPROVAL, or PAUSED) and the run page still shows the window banner. A flow may hold several Wait for window nodes; each waits for its own window.
The API keeps the record of each wait and decides how it ends. When the window opens, the worker asks the API to end the wait. The API answers by its own clock: open, missed when the window is already over, or moved when someone moved the window in the meantime, in which case the run waits for the new window. So a move the API accepted is never lost, and a window that ended while the platform was unreachable counts as missed. Start now is the exception: it continues whatever the time.
The node only decides when the work starts. It does not stop steps that are still running when the window ends; give those steps their own time limits.
While the run waits
In the Runs list, hovering over the run's WAITING_WINDOW status badge (flat and grouped lists), or over Waiting for maintenance window in the grouped list's Runs inside cell, shows the start, the end, how long until it opens and the node's message. The list API carries the window as maintenance_window on each waiting run.
The run page shows a banner with the window (in its own time zone and in yours), a countdown, and the node's message. From there you can:
- Move window - pick a new window. The run keeps waiting, now for the new one; a window that has already started lets the run continue at once. A window that has already ended is refused. The new window replaces the old one in the run's inputs, so later steps, the run page and a re-run all see it. (
POST /runs/{id}/window) - Start now - stop waiting and continue right away, outside the planned window. (
POST /runs/{id}/window/start-now) - Cancel - from the run header, as for any run.
Both actions need the operator role. They answer 409 when the run no longer waits (the window opened first). When the run waits for several windows, name the form field in the body ({"input": "mw"}); the run page does this for you.
Each of these is recorded in the audit log (run.window_moved, with the old and the new window; run.window_started_early; run.cancelled) and in the run's events.
Run limits and notifications
A run waiting for its window holds no slot of the flow's max_concurrent_runs (see run limits), because a window can be days away. It counts again once the window opens and it runs; it is not held back then if the flow is already at its limit. So several runs whose windows open at the same time all run together, even above the limit: give them different windows when that matters. A run whose other branches still work is not WAITING_WINDOW and keeps its slot.
Waiting for the window sends no notification: the run was started on purpose. When the window opens, the run sends run.resumed.
The Home page counts waiting runs as active and shows how many are waiting for a window.