Scheduled Workflow Runs

A schedule runs a selected Workflow entrypoint according to a fixed rule. Conversation and Kanban projects cannot be scheduled. Each fire creates an independent run for the selected entrypoint; it does not run the default entrypoint first.

Trigger rules

Schedules use an IANA time zone and support two trigger types:

• window-interval: choose weekdays, one or more time windows, and an interval in minutes. A window includes both endpoints, so 09:30-11:30 / every 5 minutes fires at both 09:30 and 11:30.
• cron: a five-field Cron expression evaluated in the schedule time zone. Cron seconds are not supported.

type WorkflowScheduleTrigger =
  | {
      kind: "window-interval";
      weekdays: number[]; // 1-7, Monday through Sunday
      windows: Array<{ start: string; end: string }>;
      intervalMinutes: number;
    }
  | {
      kind: "cron";
      expression: string;
    };

When a schedule is saved, its host validates the time zone, windows, Cron expression, target entrypoint, and parameters, then shows the next five fire times. Parameters may only use the entrypoint's existing static values; date placeholder templates are not supported. For dynamic values such as "today", read the current time inside the Workflow using the business time zone.

Recommended schedules

A Workflow can provide recommendations through package.json.workflowCode.schedulePresets:

{
  "workflowCode": {
    "schedulePresets": [
      {
        "id": "market-hours",
        "title": "Market data sync",
        "description": "Synchronizes market data every five minutes during trading hours on weekdays.",
        "entrypointId": "sync-minute",
        "timezone": "Asia/Shanghai",
        "trigger": {
          "kind": "window-interval",
          "weekdays": [1, 2, 3, 4, 5],
          "windows": [
            { "start": "09:30", "end": "11:30" },
            { "start": "13:00", "end": "15:10" }
          ],
          "intervalMinutes": 5
        },
        "paramValues": {
          "symbols": "000725.SZ,002594.SZ"
        }
      }
    ]
  }
}

A preset ID must match /^[a-z][a-z0-9_-]{0,63}$/, be unique within the project, and reference a declared Workflow entrypoint. A preset is only a recommendation: Desktop and Server Web display it, but the user must confirm it before a schedule is created. Importing or publishing a project never enables a schedule automatically.

Desktop and Server behavior

Host	Target	Continuous operation	Missed fires
Desktop	The current local project's dev source; validates the entrypoint before every fire	Continues from the system tray after the window closes; stops on explicit exit, shutdown, or hibernation	After recovery, records one summarized skipped_missed result and does not catch up
Server	An exact published version and entrypoint; never latest or draft	Schedules continuously while the Server process is running	After restart, advances to the first future fire and records one summarized skipped_missed result

Desktop's "start in the background at login" option is off by default. When enabled, Desktop starts in the background at system sign-in and continues local schedules without opening its main window. Server runs a schedule using its creator's identity and quota. On every fire, it verifies that the account is still active, has runs.create, can access the project, and can run the fixed version and entrypoint.

After receiving a normal shutdown signal, Server stops claiming new fires and waits for already claimed fires to finish within the process shutdown window. If it is forcibly stopped, another instance or a restarted instance can recover incomplete fires after their leases expire. It does not catch up other fires that would have occurred during the outage.

Overlap, waiting, and history

If the previous run for a schedule has not finished, the new fire is recorded as skipped_overlap; it is neither queued nor retried. A run that is waiting for user input is still unfinished, so later fires are skipped as well. The user can continue the original run by providing the requested input.

Every scheduled run records the following information in its run history, summary, and report:

{
  source: "schedule";
  scheduleId: string;
  scheduleName: string;
  fireId: string;
  scheduledFor: string;
  triggerKind: "window-interval" | "cron";
}

The Schedule page shows the enabled state, rule, time zone, version, entrypoint, next fire, recent results, and skip reason. It also lets you trigger the schedule once and inspect its fire history. Manual triggers still follow the same overlap rules.

You cannot edit or delete a schedule while it has a pending, running, or waiting_for_input fire. This prevents a recovered fire from switching to a different version, entrypoint, or parameter set, and preserves the schedule and fire history while its run continues. Wait for the run to finish or for the pending input to be completed before changing the schedule.

Kanban integration

Project KV updates the project revision after a write transaction commits successfully. A Kanban project with a confirmed direct relationship and read access can subscribe by alias and reread data through the same host backend. Rolled-back transactions produce no revision change, and revoking the relationship or read grant closes the subscription.

Desktop listens to each related project's own local KV. Server Web previews and Embeds receive revisions through authenticated SSE. A revision already included in the initial SSE snapshot is not sent again; rapid consecutive writes to the same project send only the latest revision in the batch. The two databases remain independent: local Desktop runs update only local Desktop Kanban, while Server schedules, manual runs, Webhooks, and External API runs update only Kanban connected to that Server. Market data and other KV data are not synchronized automatically between Desktop and Server.