*.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:defaultis anasync (input, step)function. Start a run withstart("app/…/x.workflow.ts", input, { key })from a non-GET handler — the same engine and tools as a BPMN process.step.run(name, fn): runsfnexactly once and remembers its result; a later wake-up returns the remembered result without re-running. PutDate.now(),Math.random()and DB reads inside astep.run.step.sleep(name, seconds | Date): sleeps until a moment (seconds or aDate, up to 365 days); nothing is used while it sleeps.step.waitFor(name, event, { timeoutSeconds }): waits for an event sent bysend(); returns the event’s data, ornullon timeout.
Example
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).
{
"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(callsapp/<task>.task.ts),condition(outgoing edges carry a FEELwhen; exactly one edge withoutwhenis the else branch),sleep,set-var,output. - Advanced nodes: a
configvalue 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 theloop) and"branch": "done"(taken after the last item).collect+resultVariablegather one value per pass into a list.wait-for: stops untilsend(<run>, "<event>", data)arrives and uses nothing while it waits. Settimeoutand a second edge,"branch": "timeout", covers the time running out.call-process: runs another.bpmnor.workflow.jsonas a child run and waits for it; cancelling the parent cancels the child.checkfails 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 asmanh/openai) and stores the reply (or the parsed JSON) in a variable. 429 / 503 / 504 are retried; turn oncontinueOnErrorso 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 arun-codethat calls a*.task.ts), parallel branches,merge,map,triggerand cycles other than aloop.checknames the node that is missing. checkcatches broken JSON, edges pointing nowhere, FEEL syntax errors, arun-codewithout its*.task.tsand acall-processpointing 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 becausecheckdoes 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 astep.run); give every step its own name ("send-" + iin 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.