UML: Sequence, Activity & State Diagrams

State Machine Diagrams

18 min Lesson 7 of 10

State Machine Diagrams

Every object in a system has a life history. An online order is placed, then confirmed, then shipped, then delivered — or it might be cancelled at any point along the way. A library book is available, then checked out, then returned, then perhaps reserved. A state machine diagram (also called a statechart) is the UML tool that captures this life history precisely: it shows every condition an object can be in and every event that causes it to move from one condition to another.

State machine diagrams are especially valuable when an object's behavior depends heavily on its current state — the same event can trigger different actions depending on where the object currently sits in its lifecycle. For a systems analyst, drawing a state machine forces you to ask: "What are all the things that can happen to this entity, and in which situations are they valid?"

Core Notation Elements

State machine diagrams use a small, precise vocabulary:

Initial pseudostate — a solid filled circle (●). Every state machine starts here. It is not a real state; it is simply the entry arrow.
State — a rounded rectangle with the state name inside (e.g., Pending, Shipped). A state represents a condition in which the object waits for something to happen.
Transition — a directed arrow from one state to another, labeled with the triggering event, an optional guard in square brackets, and an optional action after a forward slash: event [guard] / action.
Final state — a bullseye (filled circle inside a ring). The object's lifecycle ends here.

Events, Guards, and Actions — know the difference:

An event is something that happens externally or internally that the object can respond to (e.g., customerPays, timeout).
A guard is a Boolean condition in square brackets that must be true for the transition to fire (e.g., [stock > 0]).
An action is the activity performed as the transition fires (e.g., / sendConfirmationEmail).

Modeling an Order Lifecycle

Consider an online store's Order object. An order moves through well-defined stages from the moment a customer submits it to the moment it is either delivered or cancelled. Here is a state machine that captures the complete lifecycle:

Order Lifecycle State Machine: states, events, guards, and actions across the full order lifecycle.

Reading the Diagram

Walk through the diagram left-to-right, top-to-bottom:

The order begins at Pending the moment it is submitted.
When the customerPays event fires, the order moves to Payment Received.
When the system attempts to confirm the order, the guard [stock > 0] is evaluated. If stock is available, the order enters Processing. If stock is zero, a refundPayment action fires and the order returns to Pending (the customer must choose an alternative item).
When the warehouse dispatches the goods (dispatch event), the system fires a notifyCustomer action and the order moves to Shipped.
Once the courier confirms arrival (delivered), the order reaches Delivered and is then closed.
At any point before dispatch (Pending, Payment Received, Processing), a cancel event moves the order to Cancelled, which then also closes.

Tip — self-transition: A transition that loops back to the same state (e.g., a payment retry that fails) is drawn as an arc that leaves and re-enters the same state rectangle. Label it just like any other transition.

Guard Conditions Enforce Business Rules

Guards are where business rules live inside state machines. In the order diagram, [stock > 0] encodes the inventory policy. Consider a clinic appointment system:

An appointment moves from Requested to Confirmed only if [doctor is available on requested date].
It moves to Completed only if [patient checked in].
A no-show event with guard [patient did not arrive] sends it to a No-Show state, which might trigger a rebooking reminder.

Without guards, the transitions would be ambiguous. Guards turn the diagram from a sketch into a specification that developers can implement directly.

Internal Transitions and Entry/Exit Actions

A state can also contain optional compartments for:

entry / action — runs once when the state is entered (e.g., entry / startPaymentTimer).
exit / action — runs once when the state is left (e.g., exit / logTimestamp).
do / activity — a continuous activity while in the state (e.g., do / processCreditCard).

When to use a state machine diagram: Draw one whenever a single entity (order, patient record, loan application, library book) has a lifecycle with multiple named stages and the valid operations depend on the current stage. If every operation is always valid regardless of history, a state machine adds little value — use an activity diagram instead.

A Second Example: Library Book

Library Book State Machine: Available, Checked Out, Overdue, and Reserved states with event-driven transitions.

Guidelines for Drawing State Machine Diagrams

Start with the happy path. Draw the normal flow first — the sequence of states an object passes through when everything goes right.
Add exception and cancellation paths. Ask: "What can go wrong at each state? What external events can force an early exit?"
Name states as nouns or adjectives (Pending, Confirmed, Overdue), not verbs.
Name events as verb phrases or signal names (customerPays, dueDatePassed, cancel).
Check completeness — every state should have at least one exit transition (except the final state). If an object can be stuck in a state forever, model that explicitly or reconsider the design.
Avoid too many states. If you have more than eight to ten states in a single diagram, consider whether some can be grouped using composite states (covered in the next lesson).

Common mistake — confusing activity diagrams with state machines: Both show flow, but the purpose is different. An activity diagram models a process or workflow (steps people or systems perform). A state machine models the lifecycle of a single object (the conditions it can be in). If you are modeling how a warehouse team picks and packs an order, draw an activity diagram. If you are modeling what stages the order record itself passes through, draw a state machine.

State machine diagrams are one of the most direct paths from a requirements conversation to implementable design. When a developer sees a well-drawn state machine, they can map it almost directly to an enum, a status column, and a set of validation rules in the codebase — which is exactly the kind of precision a systems analyst should aim to deliver.