Docs Designing the system 8
Schedules: running a service by the clock
On this page
A schedule is a trigger that the clock sets off. On the service's Triggers tab, Add schedule:
| Setting | Meaning |
|---|---|
| Runs every… | Every N minutes (1–720) or hours (1–24), counted from midnight |
| Runs at times of day | A list such as 06:00, 14:00, 22:00 |
| Only between | For "every": a window of the day, such as 06:00–22:00. It may cross midnight (22:00–06:00). Empty: all day |
| Days | The weekdays it runs, by the calendar day of each run |
| Time zone | Empty: the plant's. Times follow daylight saving: a time the clock skips runs once when it would have been, and a time that happens twice runs once |
| Missed runs | What to do with runs that could not start on time because the system was down: run the latest one (the default), skip them, or run each (up to 100) |
| While a run is still going | Skip the new run (the default) or queue it |


Under each schedule, Next runs shows the next five times, and the legend reads it back in words ("every 15 min, 06:00–22:00, Mon Tue Wed Thu Fri (Europe/Berlin)").


What the script reads: ctx.event is
{ kind: "schedule", scheduledAt, previous: { at, output } }. previous is the last successful
run's output, so keep your position there:
// Every 15 minutes: pull the orders ERP changed since the last successful run.
export default async function erp_orders_pull(ctx) {
const since = ctx.event.previous?.output?.cursor ?? "2026-01-01T00:00:00Z";
const res = await ctx.http("erp", { method: "GET", path: "/orders", query: { changedSince: since } });
if (res.status >= 500) throw Object.assign(new Error("ERP is unavailable"), { retry: true });
for (const order of res.body.orders) { /* create or update work orders */ }
ctx.output = { cursor: res.body.until, more: res.body.hasMore === true };
return ctx;
}
- Large jobs in pages. Answer
ctx.output.more = trueand the next page runs at once (ctx.event.pagecounts them, up to 100), each reading the previous page's output. Each page must finish within the script's time limit. - Identity. A scheduled service acts as its service role or a named user; it cannot run as "its caller", since the clock calls nobody.
- Where it runs. Leave Run on nodes tagged empty to let any node run it. Give a tag (such as
erp) to keep its runs, and its record triggers, to the nodes IT started with that tag: typically the ones inside the network that can reach the other system. Changing it is a design change. - It runs once per time due, however many nodes the plant runs. On the day the clocks go forward, a time that does not exist that day (02:30) runs once at the moment it would have been, and the times after it still run.
- A schedule starts from the moment its change executes: it never runs the times it would have had before.
Test it with a dry run on an event such as
{ "kind": "schedule", "scheduledAt": "2026-10-01T06:00:00Z", "previous": { "output": { "cursor": "…" } } },
once as a first run (no previous) and once as a later one.
Schedules from an installed suite
Some times only an installed suite can work out: "at every shift end" of a calendar the suite keeps, say. A suite may add kinds of schedule of its own. Each one appears on the Triggers tab as a button Add schedule: <its name>, and in the Runs list of any schedule.
- Its settings are the suite's: each one is empty until you fill it in, and the ones marked (needed) must be. The suite checks them with the rest of the change, and says in words what is wrong.
- Time zone, Missed runs and While a run is still going work as for a clock schedule; it has no every, at, between or days, since the suite gives the times.
- The card's legend is the kind's name. Next runs, under it, asks the server, which asks the suite, for the next five times, after the suite's own words for the schedule; or what is wrong with its settings, in the suite's words.
- The scheduler plans its runs like any other: once per time due, however many nodes plan it. If the suite cannot give its times (its calendar cannot be read, say), nothing is planned for that schedule then, the event log says so, and every other service goes on.
- If the suite is removed, the service stays published and labelled as it is. Nothing is planned for that schedule, the integration monitor says which suite it needs, and a change to the service says so too. Once the suite is back, it runs again from then on.
In JSON: { "schedule": { "from": "<suite>.<kind>", "<setting>": value, "tz": "Europe/Berlin" },
"missed": "last", "overlap": "skip" }.
The core has no calendar object of its own: a schedule that follows a shift calendar comes from an installed suite that keeps one.