State machines
State machines
A state machine tracks the lifecycle of individuals, such as a pump that moves from Ordered to Installed to Retired. It defines the states an individual can be in, the events that move it, and the transitions between states. A machine belongs to an ontology and applies to the individuals of the classes you bind to it.
A state machine is part of the ontology's definition. You create and change it in a draft version, and it takes effect when you promote the version. Events always run against the live version. For more information, see Versions and drafts.
Figure: Example state machine

States
Each state has a name and a value. The value is what the service stores for the individual, and can be a string, a number, or a Boolean. Names and values must be unique in the machine.
Exactly one state is the initial state, marked with _initial. New individuals of a bound class start in it.
Events and transitions
An event is a named trigger that you fire against individuals, such as Approve.
A transition moves an individual from one state to another. Each transition has one from-state, one to-state, and the events that fire it. When several transitions share an event, the one with the lowest _executionOrder wins. Execution orders start at 0 and have no gaps.
A transition can run actions, such as starting a workflow or sending a notification. For more information, see Actions.
For the full definition, see Create a state machine.
Class binding
A machine applies to the classes listed in its _classIds. To add or remove classes without resending the whole definition, bind or unbind them. At least one class must stay bound. For more information, see Bind classes to a state machine.
Keep the following in mind when you bind classes:
- A machine applies only to the classes you bind, not to their subclasses. Bind each class whose individuals use the machine.
- The classes bound to a machine can use different collections. The service reads and writes each individual in the collection of its own class.
- Each class you fire events on needs a collection mapping. For more information, see Collection mapping.
- You can't bind the platform lifecycle classes
State,Event,Action, andStateTransition. - A class can have several machines, which track their states separately. Machines that share a class need different names.
State on the individual
Each individual holds its current states in its _aostates field, with one entry for each machine:
"_aostates": [
{ "stateMachineId": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e", "state": "draft" }
]
When you create an individual, the service adds an entry for each live machine bound to its class, set to the machine's initial state. After that, only events change the entry. You can't set _aostates on a create, and an update keeps the stored value whatever you send.
Individuals that existed before a machine was bound don't get an entry. On its first event, such an individual takes the transition whatever its from-state, and gets its first entry.
Firing an event
To move individuals, fire an event against them, grouped by class. Each group can hold up to 500 individuals. The service takes the from-state and to-state from the transition bound to the event. For more information, see Fire an event.
The service checks the request and then queues the event. A 201 response means the event is queued, not that any individual moved. The response has an _eventTriggerId that identifies the request.
The service then processes each individual on its own. If an individual's current state matches the transition's from-state, it moves to the to-state, and the transition's actions run. If it doesn't match, that individual is rejected, and the others still move.
To retry an event safely, send an Idempotency-Key header. The service applies an event at most once for each key, and remembers keys for seven days. If the request fails with 503, the event may still be applied, so retry with the same key, never a new one.
Transition history
The service records a history row for every individual it processes, whether it moved or was rejected. _success tells you which. To find the outcome of a request, match the rows on _eventTriggerId. An individual with no row yet hasn't been processed.
You can read the history of one individual, or the newest rows of a machine across all its individuals. For more information, see Get the transition history of an individual and Get state machine history.
The history doesn't record what a transition's actions did. To see that, use List action executions.
Permissions
Reading a machine needs READ on the ontology, and changing one needs EDIT.
To fire an event, you need CREATE on the event and INDIVIDUALS_EDIT on every class bound to the machine, not only the classes you target. When you create a machine, or add events to it, the service grants you CREATE on its events. Other users need their own grant. TODO: document how to grant another user CREATE on an event.
For more information, see Permissions.