Workflows
A workflow orchestrates tasks, timers, events and child workflows. Its progress is kept in a journal in the engine. After a crash, a restart or simply a wait, the workflow's code runs again from the top and every step it already took returns its journaled result, so the code carries on from where it was. That only works if the code is deterministic: given the same input and the same step results, it makes the same calls in the same order.
- No I/O in workflow code. Calls to the outside world go in tasks, or in
ctx.execute(). - No
Math.random(),Date.now()ornew Date(). Usectx.randomandctx.time. - No injected dependencies. Workflow classes are constructed with no arguments; put services in tasks.
Defining a Workflow
Functional
1export const fulfillOrder = workflow({2 name: 'fulfillOrder', // the type name clients start it by3 run: async (ctx: WorkflowContext, order: Order): Promise<string> => {4 await ctx.executeTask(chargePayment, order);5 return ctx.executeTask(orderTasks.ship, order.orderId);6 },7});Class-Based
@Workflow() requires a name, and the class must have a run(ctx, input) method. Both are
checked when the class is defined.
1@Workflow({ name: 'fulfillOrderClass' })2export class FulfillOrder {3 async run(ctx: WorkflowContext, order: Order): Promise<string> {4 await ctx.executeTask(chargePayment, order);5 return ctx.executeTask(orderTasks.ship, order.orderId);6 }7}Both forms register the workflow under its name, which is the workflowType clients start it
by. A workflow takes one input: an object, an array, or a single string, number or boolean.
The other workflow() and @Workflow() options (version, description, timeout,
cronSchedule) are recorded but have no effect on how the workflow runs. Set timeouts and
schedules when you start the workflow; see Client.
ctx.version() returns the version label (default '1.0'); the engine does not route or
replay by it.
Running Tasks
Task References
ctx.executeTask() takes a reference from task({ ... }) or from createTaskRefs() on a
@Tasks() class, and the task's input. The input and result types come from the task's
definition.
1// A reference from task(): input and output types come from its definition.2const charge = await ctx.executeTask(chargePayment, order);34// A reference from createTaskRefs() on a @Tasks class.5const tracking = await ctx.executeTask(orderTasks.ship, order.orderId);The task runs on whichever worker polls the queue, not inside the workflow. The first time the workflow reaches the call, it schedules the task and waits; when the task completes, the workflow runs again and the call returns the journaled result.
Per-Call Options
1await ctx.executeTask(orderTasks.sendReminder, order.email, {2 timeout: Duration.fromSeconds(30), // per attempt3 heartbeatTimeout: Duration.fromSeconds(10),4 queueTimeout: Duration.fromMinutes(5), // longest wait for a worker to pick it up5});| Option | Description |
|---|---|
timeout | How long one attempt may run. Overrides the task's own timeout; with neither, 5 minutes. |
heartbeatTimeout | How long an attempt may go without a heartbeat. Overrides the task's own; with neither, the engine's default applies. |
queueTimeout | How long the task may wait for a worker to start it. Unbounded when omitted. |
Each takes a Duration or a number of milliseconds.
Inline Steps
ctx.execute(name, fn) runs a closure inside the workflow worker and journals its result under
the name. On replay it returns the journaled result without running the closure again. Use it
for a small call that doesn't warrant a task; it has no retry policy or timeout of its own, and
a closure that throws is not journaled.
1// Runs inside the workflow worker; the result is journaled under the step name2// and returned from the journal on replay.3const rate = await ctx.execute('fetchExchangeRate', async () => {4 const response = await fetch('https://rates.example.com/usd-eur');5 return (await response.json()) as { rate: number };6});| Scenario | Use |
|---|---|
| A step reused across workflows, or needing injected services | ctx.executeTask(ref, input) |
| A step that needs retries, timeouts or heartbeats | ctx.executeTask(ref, input) |
| A small one-off call | ctx.execute('name', closure) |
Timers
ctx.sleep() takes a Duration. The timer is held by the engine, so a worker restart does not
reset it, and no worker needs to be running while it waits.
1export const reminder = workflow({2 name: 'reminder',3 run: async (ctx: WorkflowContext, order: Order): Promise<void> => {4 // Held by the engine: a worker restart doesn't reset it.5 await ctx.sleep(Duration.fromDays(3));6 await ctx.executeTask(orderTasks.sendReminder, order.email);78 // The same, with an id you choose instead of a generated one.9 await ctx.sleepWithId('final-reminder', Duration.fromDays(4));10 await ctx.executeTask(orderTasks.sendReminder, order.email);11 },12});Child Workflows
ctx.executeChildWorkflow() starts a workflow by name and waits for its result:
1export const shipOrder = workflow({2 name: 'shipOrder',3 run: async (_ctx: WorkflowContext, orderId: string): Promise<string> => `trk_${orderId}`,4});56export const parent = workflow({7 name: 'parent',8 run: async (ctx: WorkflowContext, order: Order): Promise<string> => {9 // Start the child and wait for its result.10 return ctx.executeChildWorkflow<string>('shipOrder', order.orderId, {11 workflowId: `ship-${order.orderId}`,12 timeout: Duration.fromHours(1),13 parentClosePolicy: ParentClosePolicy.ABANDON, // keep running if the parent ends14 });15 },16});| Option | Default | Description |
|---|---|---|
workflowId | derived from the parent's step | The child's workflow id |
taskQueue | the parent's queue | The queue whose workers run the child |
timeout | none | The child's execution timeout, as a Duration |
parentClosePolicy | ParentClosePolicy.REQUEST_CANCEL | What happens to the child when the parent closes: REQUEST_CANCEL, TERMINATE or ABANDON |
ctx.startChildWorkflow() starts the child without waiting and returns a handle, so you can
start several and wait for them together:
1export const shipAll = workflow({2 name: 'shipAll',3 run: async (ctx: WorkflowContext, { orderIds }: { orderIds: string[] }): Promise<string[]> => {4 // Start every child first; starting doesn't wait.5 const handles = [];6 for (const orderId of orderIds) {7 handles.push(await ctx.startChildWorkflow<string>('shipOrder', orderId));8 }9 // Then wait for all of them.10 return Promise.all(handles.map((handle) => handle.result()));11 },12});A child that fails throws a ChildWorkflowFailedError in the parent, with the child's
workflowType, workflowId and failure reason:
1export const tolerant = workflow({2 name: 'tolerant',3 run: async (ctx: WorkflowContext, orderId: string): Promise<string> => {4 try {5 return await ctx.executeChildWorkflow<string>('shipOrder', orderId);6 } catch (err) {7 if (isWorkflowSuspension(err)) throw err; // waiting, not failing8 if (err instanceof ChildWorkflowFailedError) {9 return `not shipped: ${err.reason}`;10 }11 throw err;12 }13 },14});Events
A workflow can wait for an event that a client sends with handle.sendEvent(name, payload).
1export const approval = workflow({2 name: 'approval',3 run: async (ctx: WorkflowContext, requestId: string): Promise<string> => {4 const decision = await ctx.waitForEvent<Approval>('approval');5 return decision.approved ? `${requestId} approved` : `${requestId} rejected`;6 },7});waitForEventWithTimeout() returns null when the timeout passes first; it does not throw. The
timeout is a durable timer, like ctx.sleep():
1export const timedApproval = workflow({2 name: 'timedApproval',3 run: async (ctx: WorkflowContext, requestId: string): Promise<string> => {4 // null when the timeout passes first; it does not throw.5 const decision = await ctx.waitForEventWithTimeout<Approval>('approval', Duration.fromHours(24));6 if (decision === null) {7 return `${requestId} timed out`;8 }9 return decision.approved ? `${requestId} approved` : `${requestId} rejected`;10 },11});An event that arrives before the workflow waits for it is kept, and the next wait for that name returns it.
Queries and State
ctx.registerQueryHandler(name, fn) answers handle.query(name) from a client. The handler
should only read; it is called with the workflow's state as of its latest step.
1export const batch = workflow({2 name: 'batch',3 run: async (ctx: WorkflowContext, { items }: { items: number[] }): Promise<number> => {4 let done = 0;5 // Clients read this with handle.query('progress').6 ctx.registerQueryHandler('progress', () => ({ done, total: items.length }));78 let sum = 0;9 for (const item of items) {10 sum += await ctx.executeTask(orderTasks.processItem, item);11 done += 1;12 ctx.setState('lastItem', item);13 }14 return sum;15 },16});ctx.setState(key, value) and ctx.getState(key) keep named values for the current run of the
code. They are not journaled: like local variables, they are rebuilt when the code runs again,
so set them only from the input and step results.
Deterministic Helpers
ctx.random returns the same values in the same order every time the code runs, seeded by the
workflow id. ctx.time is the workflow's clock, read from its journal: it starts at the moment
the engine journaled the workflow's start, and moves forward to when each task result, fired
timer, child outcome or event the workflow receives was journaled. A run of the code reads the
same time at the same point as every earlier run. A closure run with ctx.execute() does not
move it.
1export const deterministic = workflow({2 name: 'deterministic',3 run: async (ctx: WorkflowContext, order: Order): Promise<string> => {4 // The same values in the same order on every replay.5 const referenceId = ctx.random.uuid();6 const warehouse = ctx.random.choose(['east', 'west']);7 const jitterSeconds = ctx.random.randomRange(1, 30);89 // The time the engine journaled the workflow's start.10 const receivedAt = ctx.time.now();1112 await ctx.executeTask(chargePayment, order);13 await ctx.sleep(Duration.fromSeconds(jitterSeconds));1415 // The clock has moved to when the timer fired.16 if (ctx.time.elapsedSecs() > 3600) {17 await ctx.executeTask(orderTasks.sendReminder, order.email);18 }19 return `${referenceId} ${warehouse} ${receivedAt.toISOString()}`;20 },21});| Helper | Returns |
|---|---|
ctx.random.uuid() | A UUID string |
ctx.random.random() | A number in [0, 1) |
ctx.random.randomRange(min, max) | An integer in [min, max], both included |
ctx.random.choose(items) / shuffle(items) / weightedChoose(pairs) | A pick, a shuffled copy, a weighted pick |
ctx.time.now() | The workflow's current time, as a Date |
ctx.time.startedAt() | When the workflow started |
ctx.time.elapsed() / elapsedSecs() | Time since the start, in milliseconds or whole seconds |
ctx.time.hasElapsed(ms) | Whether at least ms milliseconds have passed since the start |
What Is Checked on Replay
On replay the SDK checks the code against the journal. A run whose code no longer matches what it recorded is held: the activation is not applied, the run stays open with its journal unchanged, the worker logs an error naming the workflow and run, and the activation is tried again after a pause that grows with each attempt. Nothing is lost, and a run held because of a bad deploy continues once code that replays it is running again.
What is caught:
- code that no longer reaches a step the journal recorded, and then issues new work or finishes; and
- code that issues different work at a recorded position, for example a different task where another used to be.
What is not caught (tracked in sdk-core#14):
- reordering steps of different kinds, such as moving a timer before a task; and
- changing a timer's duration.
To change a workflow with runs in flight, let those runs finish before deploying an
incompatible change, or put the new code under a new workflow name and start new runs there.
Give each worker a versionId for the code it
runs; the engine records it on each execution.
Handling Failures in a Workflow
A task that fails after its retries makes ctx.executeTask() throw a WorkflowError with code
TASK_EXECUTION_FAILED. Uncaught, it fails the workflow.
To catch it, know one thing about how waiting works: when the workflow reaches a step whose
result isn't in the journal yet, ctx.executeTask() (and sleep, waitForEvent, child
workflows and sessions) throws a suspension to stop the run until the result
arrives. A catch around those calls sees that suspension too. Re-throw it first, with
isWorkflowSuspension(), or the catch treats every wait as a failure:
1export const chargeOrRemind = workflow({2 name: 'chargeOrRemind',3 run: async (ctx: WorkflowContext, order: Order): Promise<string> => {4 try {5 const charge = await ctx.executeTask(chargePayment, order);6 return charge.chargeId;7 } catch (err) {8 // Waiting for the task also arrives here as a thrown suspension: pass it on.9 if (isWorkflowSuspension(err)) throw err;10 if (err instanceof WorkflowError && err.code === ExecutionErrorCode.TASK_EXECUTION_FAILED) {11 // The task failed after its retries.12 await ctx.executeTask(orderTasks.sendReminder, order.email);13 return 'payment failed';14 }15 throw err;16 }17 },18});The same applies to finally: it runs on every suspension, so don't put steps in it.
Restarting with a Fresh Journal
A workflow that loops for a long time grows its journal with every step. ctx.restartFresh(input)
ends the current run and starts a new run of the same workflow with an empty journal and the
given input. Call it once, then return.
1export const drain = workflow({2 name: 'drain',3 run: async (ctx: WorkflowContext, input: { cursor: string | null }): Promise<void> => {4 const page = await ctx.executeTask(orderTasks.fetchBatch, { cursor: input.cursor });5 for (const item of page.items) {6 await ctx.executeTask(orderTasks.processItem, item);7 }8 if (page.next !== null) {9 // Carry on in a new run of the same workflow id, with an empty journal.10 ctx.restartFresh({ cursor: page.next });11 return;12 }13 },14});Everything the next run needs must be in that input: nothing else carries over. options can
set a different workflowType, taskQueue or timeout for the new run.
Workflow Metadata
1export const describeSelf = workflow({2 name: 'describeSelf',3 run: async (ctx: WorkflowContext): Promise<Record<string, string | number | boolean>> => ({4 workflowId: ctx.workflowId(),5 runId: ctx.runId(),6 workflowType: ctx.workflowType(),7 namespace: ctx.namespace(),8 taskQueue: ctx.taskQueue(),9 attempt: ctx.attempt(), // starts at 110 replaying: ctx.isReplaying(),11 }),12});WorkflowContext Reference
| Method | Description |
|---|---|
ctx.executeTask(ref, input, options?) | Run a task and wait for its result |
ctx.execute(name, closure) | Run a closure once and journal its result |
ctx.sleep(duration) | Durable timer, for a Duration |
ctx.sleepWithId(id, duration) | Durable timer with an id you choose |
ctx.waitForEvent<T>(name) | Wait for an event |
ctx.waitForEventWithTimeout<T>(name, timeout) | Wait for an event; null on timeout |
ctx.executeChildWorkflow<T>(type, input, options?) | Start a child workflow and wait for its result |
ctx.startChildWorkflow<T>(type, input, options?) | Start a child workflow; returns a handle |
ctx.createSession() | Pin tasks to one worker; see Sessions |
ctx.registerQueryHandler(name, handler) | Answer client queries |
ctx.setState(key, value) / ctx.getState(key) | Named values for the current run of the code |
ctx.random | Deterministic random values |
ctx.time | The workflow's clock |
ctx.restartFresh(input, options?) | End this run and start a new one with an empty journal |
ctx.workflowId() / runId() / workflowType() / namespace() / taskQueue() / attempt() / isReplaying() | Metadata |