Workflow Lifecycle

Workflows in Ablauf move through various states as they execute. Understanding these states helps you manage and monitor your workflows effectively.

Status States

A workflow can be in one of the following states:

• "created" — Initialized, but not yet running
• "running" — Actively executing steps
• "completed" — Finished successfully with a result
• "errored" — Failed with an unrecoverable error
• "paused" — Manually paused (can be resumed)
• "sleeping" — Waiting for a timer (step.sleep(), step.sleepUntil(), or retry backoff)
• "waiting" — Waiting for an external event
• "terminated" — Manually terminated (permanent)

Getting Status

Check a workflow's current state via a WorkflowHandle:

const order = ablauf.get(OrderWorkflow, { id: workflowId });
const status = await order.getStatus();
// status.payload is typed as OrderPayload
// status.result is typed as OrderResult | null

For the full shape of the status response including StepInfo details, see the API Reference.

Pausing and Resuming

Sometimes you need to temporarily halt a workflow — maybe you're debugging, or waiting for maintenance to complete. Ablauf makes this graceful:

const order = ablauf.get(OrderWorkflow, { id: workflowId });
await order.pause();
// Workflow stops at the next step boundary

When you're ready to continue:

await order.resume();
// Workflow replays and continues from where it left off

The workflow will replay its execution history (using cached results from completed steps) and resume at the point where it paused.

Terminating

If a workflow needs to be permanently stopped, use terminate():

await order.terminate();
// Workflow is permanently stopped — cannot be resumed

Unlike pause, termination is permanent. The workflow moves to the "terminated" state and cannot be resumed. Its execution history and state remain stored, but it will never run again.

When to Terminate

Termination is useful when:

• A workflow was created with incorrect input and needs to be abandoned
• Business logic determines the workflow is no longer needed
• You need to cancel a long-running process

Status Transitions

Here's how workflows move between states:

created → running → completed
              │
              ├─→ sleeping ─→ running  (alarm fires)
              ├─→ waiting  ─→ running  (event arrives)
              ├─→ paused   ─→ running  (manually resumed)
              ├─→ errored
              └─→ terminated

• sleeping, waiting, and paused are all suspended states — the workflow isn't actively executing steps.
• sleeping and waiting resume automatically (when the alarm fires or the event arrives).
• paused requires a manual resume() call.
• terminated is permanent — the workflow cannot be resumed.
• Any running or suspended workflow can be terminated at any time.