---
title: 'Screenplay workflows: model a durable business process'
editUrl: https://github.com/Cratis/Screenplay/edit/main/Documentation/screenplay/workflows.md
description: 'Model order fulfilment with a Screenplay workflow: invoke commands, wait for events or approvals, and specify where the process completes or fails.'
lastUpdated: 2026-11-12T00:00:00.000Z
---

A workflow in Cratis Screenplay describes a durable business process that continues through several steps, including waits for events or a person's approval. Use it when an order being Paid is only the start of the work: stock must be reserved, a parcel dispatched and delays handled.

A [state machine](/screenplay/statemachines/) observes where the order is in its lifecycle. A [reaction](/screenplay/reactions/) responds to an occurrence with effects or command requests. The workflow makes the longer process explicit, including where it suspends and which path it takes after a failure.

A workflow runs one at a time per subject. The subject is the read model named by `for`, and its key identifies the order or other item the run is about. The declaration is top-level and uses the semantics of Cratis Choreography's durable workflow engine. It is admitted from executable semantic model ([ESM v36](/screenplay/interoperability/)).

## Syntax

Each named step is a node. Its outlets are the possible outcomes, and an edge connects an outlet to the next node: `<outlet> -> <Node>`.

This excerpt continues the [order lifecycle](/screenplay/statemachines/#syntax). It assumes the `OrderProgress` read model and the referenced commands, events and approver are declared elsewhere in the application.

```screenplay
workflow FulfilOrder
  description "Reserves stock, ships the order and tells the shopper; a backorder needs a warehouse sign-off"
  for OrderProgress
  trigger when OrderLifecycle enters Paid
    -> ReserveStock
  action ReserveStock invokes HoldStock attempts 3 timeout 1 minute retry after 30 seconds
    next -> InStock
    failed -> Escalate
  decide InStock when itemsInStock == true
    "in stock" -> CreateParcel
    "backorder" -> AcceptBackorder
  action CreateParcel invokes CreateParcel
    next -> ParcelLeaves
  wait ParcelLeaves for OrderHandedToCarrier expires after 2 days
    resumed -> TellCustomer
    expired -> Escalate
  approval AcceptBackorder by WarehouseClerk expires after 1 day
    approved -> PlaceBackorder
    rejected -> CancelOrder
    expired -> Escalate
  action PlaceBackorder invokes PlaceBackorder
    next -> ParcelLeaves
  action CancelOrder invokes WithdrawOrder
  action TellCustomer invokes NotifyCustomer
  action Escalate invokes EscalateOrder
```

When the order enters Paid, the run invokes `HoldStock`. A successful reservation leads to a decision over `itemsInStock` on the subject read model. Stock on hand leads to parcel creation; otherwise a warehouse clerk must approve the backorder. The run then waits for the carrier event, or escalates if the deadline passes.

Node words are recognized only directly inside a `workflow`. This leaves `trigger` available as a top-level declaration and `join` as a projection word elsewhere.

| Node | Line | Outlets |
| --- | --- | --- |
| trigger | `trigger [Name] on <Event>`, `when <StateMachine> enters <State>`, `every <n> <unit>`, `at <HH:mm> [on <Weekday>]` (the [reaction](/screenplay/reactions/) schedule forms) or `manual`. Write its edge as `-> <Node>`. | `next` |
| action | `action <Name> invokes <Command> [attempts <n>] [timeout <n> <unit>] [retry after <n> <unit>]` | `next`, `failed`, `refused` |
| decide | `decide <Name> when <condition>`; the condition is over the subject read model | exactly two of your own: the first is taken when the condition holds, the second when it does not |
| wait | `wait <Name> for <Event> [expires after <n> <unit>]` waits for an event about the subject; `wait <Name> for <n> <unit>` lets time pass | `resumed`, `expired` |
| approval | `approval <Name> by <Persona or Policy> [expires after <n> <unit>]` | `approved`, `rejected`, `expired` |
| foreach | `foreach <Name> over <collection property of the subject> [parallel <n>]` | `each`, `completed` |
| join | `join <Name> all`, `join <Name> any` or `join <Name> at least <n>` | `next` |

An unnamed trigger is called `Trigger`, then `Trigger2` and so on. A workflow may have several triggers. Units are `second`, `minute`, `hour` and `day`, singular or plural.

Connect each negative outcome you want to recover from. An unconnected `failed`, `refused`, `rejected` or `expired` outlet fails the run; an unconnected positive outlet ends that branch. In the example, reservation failure reaches `Escalate`, whose successful action ends its branch. Outlet names match Cratis Choreography's `WellKnownOutlets`.

An action's command receives the subject key and subject properties with matching names. The executor defines how to fill any remaining inputs. The reference evaluator records that the command was sent; it does not execute that command's business effects.

## Invoking an ability

An action asks a [system](/screenplay/systems/#invoke-an-ability) for an ability with `action <Name> invokes <System>.<Ability>`. Its inputs are mapped on the lines under it from a literal, a property of the workflow's subject or an earlier node's result (`Node.field`). The node has a `next` edge for a normal answer, a `failed` edge and one edge per outcome the ability declares (an outlet that can never be taken, such as `expired` on an ability that does not answer later, is `PLAY1007`, and an outcome the ability does not declare is `PLAY1002`).

```play
action BookPickup invokes Carrier.BookPickup attempts 3
  parcelId = parcelId
  address = "1 Main Street"
  next -> Risk
  NoCapacity -> Done
  failed -> Done
```

A `compute <Name>` node, with its `returns` fields and a C# body, and an approval answered through an ability (`approval <Name> by <Policy> via <System>.<Ability> expires after 2 days`) parse and validate. They are not executable yet; binding reports `PLAY0268` naming #1252. A node may only read the result of a node that always ran before it (`PLAY1009`).

## Specifications

Write specifications inside the workflow to check its paths before relying on an executor. Establish the history, append the triggering event or start the run, then state the outcomes needed for that path.

The reference evaluator computes decisions from the subject read model and records commands sent by actions. A wait or approval takes the outcome supplied by the specification; without one, it suspends the run. This checks the process graph, not a live carrier integration or a person's response.

| Line | Meaning |
| --- | --- |
| `given <Event>` | A fact that already happened (with `for` and values). |
| `when append <Event>` | The event that sets the run off: it starts the run when it matches an `on` trigger, or moves a state machine into the state a `when ... enters` trigger waits for. |
| `when start <key>` | Starts the run by hand for the subject key, through a `manual` or scheduled trigger. |
| `outcome <Node> <outlet>` | The outlet an action (`next`, `failed`, `refused`), wait (`resumed`, `expired`), approval (`approved`, `rejected`, `expired`) or foreach takes. An action defaults to `next`; a failed action invokes its command once per attempt. `refused` means the command was handed on and something rejected it; it is distinct from `failed`, which means the invocation itself broke, and a refused command is not retried. |
| `then invokes <Command>` | A command was invoked. Every command invoked is stated, in order. |
| `then completes` | The run ended without failing. |
| `then fails at <Node>` | The run failed at the node. |
| `then waits at <Node>` | The run is suspended at a wait or an approval. |

```text
specification TheRunWaitsForTheCarrier
  description "With no word from the carrier the run waits at ParcelLeaves"
  given CheckoutCompleted
    for "0e7d9b1a-3c5f-4a2e-8d6b-7c9e1f2a3b01"
  when append PaymentCaptured
    for "0e7d9b1a-3c5f-4a2e-8d6b-7c9e1f2a3b01"
  then invokes HoldStock
  then invokes CreateParcel
  then waits at ParcelLeaves
```

The example expects the stock to be available in `OrderProgress` after its given history. With no outcome supplied for `ParcelLeaves`, the run stops there after sending `HoldStock` and `CreateParcel`. Add specifications with `outcome ParcelLeaves resumed` or `outcome ParcelLeaves expired` to cover dispatch and escalation.

For collection work, a `foreach` runs its `each` branch once per item in item order, then takes `completed`. Its `parallel` setting bounds the executor, not the reference run. A `join` counts arrivals: `all` waits for every branch (the incoming edges, times the items of a `foreach` that feeds it), `any` for the first and `at least n` for n. A duration wait resumes immediately in a reference run, so it does not test elapsed wall-clock time.

## Checks

| Code | When |
| --- | --- |
| `PLAY0843` | The declaration is malformed. |
| `PLAY0844` | There is no trigger. |
| `PLAY0845` | A node can never be reached from a trigger (warning). |
| `PLAY0846` | An edge points at a node the workflow does not declare. |
| `PLAY0847` | An edge leaves by an outlet the node kind does not have. |
| `PLAY0848` | A decision does not have exactly two outlets, or one leads nowhere. |
| `PLAY0849` | A wait for an event or an approval has no expiry (warning). |
| `PLAY0850` | A join has a single incoming branch (information). |
| `PLAY0851` | A command, event, persona or policy, state machine or property is not declared. |
| `PLAY0839` | A trigger waits for a state its state machine does not declare. |
| `PLAY0841` | A condition or a foreach reads a property the subject does not have. |

See [State machines](/screenplay/statemachines/) for the lifecycle that can start a workflow, and decision [0124](https://github.com/Cratis/Screenplay/blob/main/decisions/0124-state-machines-and-workflows-esm-v36.md) for the full contract.

## Migrating from `sends`

`invokes` is the one verb for asking a command to run, here and in reactions. The old forms still compile and raise the deprecation warning `PLAY0397` with a repair; printing a document writes the new forms.

| Before | After |
| --- | --- |
| `action <Node> sends <Command>` | `action <Node> invokes <Command>` |
| `then sends <Command>` | `then invokes <Command>` |

An action that invoked a command and treated a rejection as `failed` can now route `refused` separately.
