Reference

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() or new Date(). Use ctx.random and ctx.time.
  • No injected dependencies. Workflow classes are constructed with no arguments; put services in tasks.

Defining a Workflow

Functional

1
export const fulfillOrder = workflow({
2
name: 'fulfillOrder', // the type name clients start it by
3
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' })
2
export 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.
2
const charge = await ctx.executeTask(chargePayment, order);
3
4
// A reference from createTaskRefs() on a @Tasks class.
5
const 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

1
await ctx.executeTask(orderTasks.sendReminder, order.email, {
2
timeout: Duration.fromSeconds(30), // per attempt
3
heartbeatTimeout: Duration.fromSeconds(10),
4
queueTimeout: Duration.fromMinutes(5), // longest wait for a worker to pick it up
5
});
OptionDescription
timeoutHow long one attempt may run. Overrides the task's own timeout; with neither, 5 minutes.
heartbeatTimeoutHow long an attempt may go without a heartbeat. Overrides the task's own; with neither, the engine's default applies.
queueTimeoutHow 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 name
2
// and returned from the journal on replay.
3
const 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
});
ScenarioUse
A step reused across workflows, or needing injected servicesctx.executeTask(ref, input)
A step that needs retries, timeouts or heartbeatsctx.executeTask(ref, input)
A small one-off callctx.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.

1
export 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);
7
8
// 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:

1
export const shipOrder = workflow({
2
name: 'shipOrder',
3
run: async (_ctx: WorkflowContext, orderId: string): Promise<string> => `trk_${orderId}`,
4
});
5
6
export 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 ends
14
});
15
},
16
});
OptionDefaultDescription
workflowIdderived from the parent's stepThe child's workflow id
taskQueuethe parent's queueThe queue whose workers run the child
timeoutnoneThe child's execution timeout, as a Duration
parentClosePolicyParentClosePolicy.REQUEST_CANCELWhat 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:

1
export 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:

1
export 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 failing
8
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).

1
export 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():

1
export 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.

1
export 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 }));
7
8
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.

1
export 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);
8
9
// The time the engine journaled the workflow's start.
10
const receivedAt = ctx.time.now();
11
12
await ctx.executeTask(chargePayment, order);
13
await ctx.sleep(Duration.fromSeconds(jitterSeconds));
14
15
// 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
});
HelperReturns
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:

1
export 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.

1
export 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

1
export 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 1
10
replaying: ctx.isReplaying(),
11
}),
12
});

WorkflowContext Reference

MethodDescription
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.randomDeterministic random values
ctx.timeThe 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

Next Steps

  • Tasks: task options, retries, heartbeats
  • Client: starting workflows, sending events, queries
  • Patterns: sagas, fan-out, approvals