Skip to content

Screenplay state machines: follow a business lifecycle

In Cratis Screenplay, a state machine follows recorded events to show where one business item is in its lifecycle. Use it to describe an order moving from Placed to Paid and eventually Delivered, rather than to decide whether a command is allowed.

The machine follows a read model: a view built from events, whose key identifies one instance. After PaymentCaptured, the order can enter Paid and start fulfilment. The state machine describes the lifecycle consequence of that fact; the workflow describes the work that follows, including waits and recovery paths. Command validation and requirements still decide whether a requested change may happen.

Its semantics match Cratis Choreography’s EventSourcedStateMachine. A statemachine is a top-level declaration, beside system, trigger, policy and persona, and can reference declarations in slices of any module. It is admitted from executable semantic model (ESM v36); declaring one selects that version.

statemachine <Name>
[description "<text>"]
follows <ReadModel>
state <Name> [initial] [final]
[entering invokes <Command>]
[entering starts <Workflow>]
[on <Event> [when <condition>] -> <State>]
[specification <Name> ...]
  • Exactly one state is initial. Any number are final, and a final state has no transitions.
  • on <Event> [when <condition>] -> <State> is a transition. The condition is the condition grammar of produces when, over the properties of the followed read model, as the read model is after the event. A condition over an optional property is refused when the model is bound: optional properties have no portable comparison.
  • entering invokes <Command> and entering starts <Workflow> say what entering the state does. Entering may run again on redelivery, so the command or workflow must be safe to repeat.

The following lifecycle is an excerpt: OrderProgress, its events, NotifyCustomer and FulfilOrder must be declared elsewhere in the application. Read it alongside the fulfilment workflow, which uses the same order subject.

statemachine OrderLifecycle
description "Where an order is, from checkout to delivery"
follows OrderProgress
state Placed initial
on PaymentCaptured -> Paid
on OrderWithdrawn -> Cancelled
state Paid
entering starts FulfilOrder
on OrderPacked -> Packed
on OrderWithdrawn -> Cancelled
on RefundIssued -> Refunded
state Packed
on OrderHandedToCarrier -> Shipped
state Shipped
entering invokes NotifyCustomer
on DeliveryConfirmed -> Delivered
on ParcelReturned when returnReason != "" -> Refunded
state Delivered final
state Cancelled final
state Refunded final

A state’s entering line can ask a system for an ability: entering invokes <System>.<Ability> with the inputs mapped on the lines under it. Like every entering effect it may run again on redelivery, and a state machine holds no data to wait for an answer, so an ability that answers later is PLAY1011.

state Paid final
entering invokes PaymentGateway.SendReceipt
invoiceId = invoiceId
email = "accounts@example.com"

A bare entering followed by a C# fence or a file line attaches a body instead of a call. It parses and validates but is not executable yet (PLAY0268, #1252). A specification asserts the call with then invokes <System>.<Ability>.

In the example, PaymentCaptured allows an order in Placed to move to Paid. Entering Paid starts FulfilOrder; entering Shipped invokes NotifyCustomer. These entry effects may run again on redelivery, so their receivers must be safe to repeat.

Transition lookup has a detail worth checking when you add states. A state allows exactly the targets written under it, but the machine searches transitions for an event across the whole declaration, in declaration order. It takes the first transition whose condition holds and whose target the current state allows. The condition sees the followed read model after the event.

A transition is therefore not restricted to the state it is written under. Write it under each state that should allow its target, and check the order of any competing transitions. If none qualifies, the event is ignored rather than rejected. After a restart, the current state is derived from the followed read model; it is never stored separately.

Write a specification inside the state machine to check a lifecycle outcome. Use given <Event> (with for and values) for history, then when append <Event> for the new fact. The expectations describe both the resulting state and any entry effects:

Line Meaning
then is <State> The instance is in the state after the event.
then invokes <Command> Entering the new state invoked the command. Every command invoked is stated, in order.
then starts <Workflow> Entering the new state started the workflow. Every workflow started is stated, in order.
specification AReturnWithoutAReasonIsIgnored
given CheckoutCompleted
for "0e7d9b1a-3c5f-4a2e-8d6b-7c9e1f2a3b01"
given PaymentCaptured
for "0e7d9b1a-3c5f-4a2e-8d6b-7c9e1f2a3b01"
when append ParcelReturned
for "0e7d9b1a-3c5f-4a2e-8d6b-7c9e1f2a3b01"
returnReason = ""
then is Paid

Here, ParcelReturned has an empty reason, so it does not move the paid order to Refunded. The reference evaluator replays the facts, updates the followed read model after each one and applies the transition rule above. screenplay test runs these specifications with the others.

Code When
PLAY0834 The declaration is malformed.
PLAY0835 There is no initial state, or more than one.
PLAY0836 A state can never be reached from the initial state (warning).
PLAY0837 A state that is not final has no way out (warning).
PLAY0838 A final state has transitions out.
PLAY0839 A transition targets a state the machine does not declare.
PLAY0840 An event, read model, command or workflow is not declared.
PLAY0841 A condition reads a property the followed read model does not have.
PLAY0842 Two unguarded transitions on one event leave the same state.

See Workflows for the process a state can start, and decision 0124 for the full contract.

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

Before After
entering send <Command> entering invokes <Command>
entering start <Workflow> entering starts <Workflow>
then sends <Command> then invokes <Command>