Skip to Content

*.workflow.ts

A workflow is a chain of steps written in code, running durably on the same engine as a BPMN process: each step.run runs exactly once and its result is remembered, so if the app restarts or a later step fails the run resumes from where it stopped. It fits technical multi-step work — importing a batch of data, syncing with another system — where the chain of steps is code, not a diagram for a person to read.

Not open to apps yet. check does not accept *.workflow.ts files yet (rule process.code-later) — this is an advanced, preview surface. Model multi-step business work (approvals, waiting for payment, reminders) as a BPMN process instead: the same engine, the same Operations › Workflows view, the same tools, and something a business person can read as a diagram.

Exports

  • *.workflow.ts: default is an async (input, step) function. Start a run with start("app/…/x.workflow.ts", input, { key }) from a non-GET handler — the same engine and tools as a BPMN process.
  • step.run(name, fn): runs fn exactly once and remembers its result; a later wake-up returns the remembered result without re-running. Put Date.now(), Math.random() and DB reads inside a step.run.
  • step.sleep(name, seconds | Date): sleeps until a moment (seconds or a Date, up to 365 days); nothing is used while it sleeps.
  • step.waitFor(name, event, { timeoutSeconds }): waits for an event sent by send(); returns the event’s data, or null on timeout.

Example

app/sync/import.workflow.ts
export default async function (input: { batchId: number }, step) { const rows = await step.run("fetch", () => fetchBatch(input.batchId)); // runs once, result remembered await step.sleep("cool-down", 600); // seconds or a Date, ≤ 365 days const ok = await step.waitFor("confirm", "confirmed", { timeoutSeconds: 86400 }); // data of send(), or null on timeout if (!ok) return { skipped: true }; await step.run("apply", () => applyRows(rows), { attempts: 5 }); }

Visual workflow (*.workflow.json)

A visual workflow is a node + edge graph in one JSON file, built to be drawn on a canvas (open the file in the Code tab for the diagram: a step palette, a properties panel on the right, drag to connect; the JSON tab edits the same text). It runs on the same durable engine as a process: runs, steps, timers, retries, started with start("app/…/x.workflow.json", { … }) from a non-GET handler. The input must be an object; it becomes the run’s variables (vars in the file are the defaults).

app/orders/welcome.workflow.json
{ "nodes": [ { "id": "start", "type": "start" }, { "id": "reserve", "type": "run-code", "config": { "task": "orders/reserve", "inputs": { "id": "=orderId" } } }, { "id": "big", "type": "condition" }, { "id": "wait", "type": "sleep", "config": { "duration": "PT30M" } }, { "id": "done", "type": "output" } ], "edges": [ { "from": "start", "to": "reserve" }, { "from": "reserve", "to": "big" }, { "id": "yes", "from": "big", "to": "wait", "when": "=total >= 1000" }, { "id": "no", "from": "big", "to": "done" }, { "from": "wait", "to": "done" } ] }
  • Basic nodes: start, run-code (calls app/<task>.task.ts), condition (outgoing edges carry a FEEL when; exactly one edge without when is the else branch), sleep, set-var, output.
  • Advanced nodes: a config value starting with = is a FEEL expression; in the text fields (prompt, subject, text, html, url) {{name}} inserts a variable’s value.
    • loop: goes through a list one item at a time (items: a list or an =expression), at most 1000 items (default 100). It has two outgoing edges: "branch": "body" (the steps that run per item; the last one connects back to the loop) and "branch": "done" (taken after the last item). collect + resultVariable gather one value per pass into a list.
    • wait-for: stops until send(<run>, "<event>", data) arrives and uses nothing while it waits. Set timeout and a second edge, "branch": "timeout", covers the time running out.
    • call-process: runs another .bpmn or .workflow.json as a child run and waits for it; cancelling the parent cancels the child. check fails when the called file does not exist.
    • http: calls a public address (method, url, headers, body) and stores { ok, status, body } in a variable. 5xx / 429 are retried, a 4xx stops. A step can run again after a crash, so a non-idempotent POST may arrive twice: send an idempotency key when that matters.
    • llm: calls the app’s AI service (the same service and the same quota as manh/openai) and stores the reply (or the parsed JSON) in a variable. 429 / 503 / 504 are retried; turn on continueOnError so the workflow keeps going when the AI is busy.
    • email: sends mail through the app’s mail service (manh/email, same recipient limits).
  • Not open yet: db (read tables in a run-code that calls a *.task.ts), parallel branches, merge, map, trigger and cycles other than a loop. check names the node that is missing.
  • check catches broken JSON, edges pointing nowhere, FEEL syntax errors, a run-code without its *.task.ts and a call-process pointing at a missing file.

Process or workflow

  • Business work — multi-level approval, waiting for payment, SLAs, reminders, tasks handed to people — is a BPMN process: it is drawable, has user tasks / DMN decision tables / boundary timers, and is the surface open to apps today.
  • Technical work — a chain of steps that is code, with no need for a diagram — fits *.workflow.ts. But because check does not accept the file yet, model those steps as a BPMN process for now (a service task calling a *.task.ts), or a *.job.ts if it is just one background task after a request.

Good to know

  • Replay: on every wake-up the function runs from the top, and a step that already finished returns its remembered result. Keep code between steps free of Date.now(), Math.random() and DB reads (put those inside a step.run); give every step its own name ("send-" + i in loops).
  • A step can run twice if it fails half-way — make its writes idempotent (upsert, check the status first).
  • Runs, incidents, retry and cancel: the same Operations › Workflows view as a BPMN process.

Next steps

  • Processes (*.bpmn) — multi-step business work, approvals, timers, waiting on people (the surface open to apps).
  • *.job.ts — one slow task in the background after a request.
Last updated