UML state machine diagrams
One object, every state it can be in, and every event that moves it between them. The diagram that turns "can a captured payment be voided?" from an argument into something you can point at.
9 min readUML 2.5.16 of 15
01What it shows
A state machine diagram describes the life of one thing. Not a process, not an interaction - one object, or one component, and the states it passes through from creation to disposal.
Its power is in the negative space. The diagram above draws six transitions. Everything else is thereby forbidden: a Refunded payment cannot go back to Captured, a Failed one cannot be captured, and a Pendingone cannot be refunded. In a class diagram those constraints live in prose or in nobody's head. Here they are the picture.
02States and transitions
| Element | Notation | What it means |
|---|---|---|
| Initial pseudostate | filled disc | Where the object begins. It is not a state - nothing rests here; the outgoing transition fires immediately. |
| State | rounded rectangle | A condition the object remains in while waiting for something. Named as an adjective or past participle: Authorized, not Authorizing it. |
| Transition | arrow with a label | A move between states, triggered by an event. Labelled trigger [guard] / effect. |
| Final state | ring around a disc | The object's life ends. There is nothing after it. |
| Composite state | a state containing states | Groups sub-states. A transition out of the composite applies to every state inside it. |
| History | a circled H | Re-entering a composite resumes at the sub-state it was last in, rather than at its initial one. |
03Where behaviour goes
Behaviour can hang off a transition or off a state, and choosing correctly removes a great deal of duplication.
- Effect on a transition - written after the slash. Runs once, on that specific move. Use it when the behaviour belongs to that path.
entry / …- runs every time the state is entered, by any transition. If three arrows intoCapturedall need to write a ledger entry, that is oneentryaction, not three effects.exit / …- runs every time the state is left, by any transition.do / …- runs continuously while in the state, and is interrupted when it is left. This is the one for long-running work.
The rule of thumb: if the behaviour is about being in the state, use entry/do/exit. If it is about the particular journey between two states, put it on the transition.
04Composite states and history
Real lifecycles grow a common case: several states that all respond identically to one event. A payment in Pending, Authorized or Captured can all be cancelled, and drawing three separate cancel arrows to Cancelled is noise.
A composite state solves this. Wrap those three in an enclosing state called Active, and draw one cancel transition out of Active. It applies to whichever sub-state is current. Three arrows become one, and adding a fourth sub-state later costs nothing.
A history pseudostate - a circled H - handles resumption. Without it, re-entering a composite starts at its initial sub-state. With it, the machine returns to whichever sub-state it was in when it left. Shallow history (H) remembers one level; deep history (H*) remembers the whole nesting. This is what you want for anything suspendable.
05When to draw one
Reach for it when
- An entity has a status field and rules about which changes are allowed
- Order, payment, subscription, ticket, document approval - anything with a lifecycle
- A protocol or device with modes, where illegal transitions cause real damage
- You are about to write a status enum and want to get the transitions right first
Reach for something else when
- The object has two states - a sentence covers it
- You are describing a process spanning several objects; use an activity diagram
- The states are really just steps that always follow one another in order
- The interesting part is who calls whom, not what state anything is in
A state machine diagram maps almost directly onto code, which is unusual for UML. The states become an enum, the transitions become a table, and the guards become the conditions on each entry. Drawing it first and implementing from it is one of the few places where modelling straightforwardly saves time rather than merely documenting.
06Common mistakes
- States named as activities.
Authorizingsuggests work in progress; if the object is waiting there, name the condition -Authorized,Awaiting capture. - Modelling a process, not an object.If your "states" are steps performed by different people, you want an activity diagram.
- Transitions with no trigger. Legal - it fires when the state's
doactivity completes - but usually a sign that an event is missing. - No final state, and no explanation. Either the object genuinely lives forever, or a terminal state was forgotten. Both happen; only one is intended.
- Repeating the same transition from every state. That is what a composite state is for.
In one line each
- 01One object, its states, and the events that move it. Not a process.
- 02The transitions you do not draw are the constraint the diagram exists to record.
- 03Transition labels read trigger [guard] / effect, and every part is optional.
- 04entry, exit and do actions belong to the state; effects belong to one transition.
- 05Composite states collapse an event shared by several sub-states into one arrow.
- 06History pseudostates resume where the machine left off, instead of restarting.
Related reading