Blue text — tips or rules not dictated by UML, but borrowed from other useful theories or practical experience.
Italics — examples.
A UML State Machine Diagram is a type of behavioral diagram that shows what states an object (the one we’re modeling) can be in and how these states change over the course of the object’s life.
What does “state” even mean? A state is a situation in which an object has certain fixed characteristics. Sounds complex, but for example, our “states” throughout the day might include: tired, inspired, hungry, sleepy, and so on — and we can be in multiple of them at once. Take the state tired: that just means the parameter “energy level” is low. Some triggers (events or actions) can change that parameter and thereby cause a shift in state — for example, the action take a nap (though not only that one).
To show the full picture of how our states change throughout the day — what states we can be in, and what triggers lead to transitions — we use a state diagram.
Business analysts use these diagrams to show the lifecycle of some data class from the logical data model, or to describe/analyze the states of a business domain entity while exploring the subject area. It’s useful when the object in question has a non-trivial lifecycle — in other words, when a data class or domain entity goes through several clearly defined states during its existence.
For instance, let’s say we’re building an electronic document management system. One of the key data classes is Document. In such a system, documents have a fairly complex life: scanned, sent for review, approved, archived, and so on. These are its statuses throughout its journey in the system — i.e., its states.
Elements:
There’s one key element here — the State. It's drawn just like an action in an activity diagram: a rectangle with rounded corners.
Initial State (sometimes formally called a Pseudostate, though that's diving into scary depths of UML philosophy) — This is the starting point of an object’s life, or of the part of its life we’re modeling. Like in the activity diagram, it's drawn as a filled black circle. It (and the outgoing transition) simply shows where the object’s life begins — i.e., which state is the starting one. For example, if we’re modeling a person’s food-related states throughout the day, we assume their day starts hungry. So that’s the initial state we mark.
Final State — This marks the end of the object’s life (or of the modeled segment of it). It’s shown, again like in activity diagrams, as a black circle inside another circle. In our example, it means the person can go to bed from any current state.
There’s only one type of connection we care about here:
Behavioral Transition — A link between states that marks a possible change from one to another. This connection can contain several parameters, but we’ll focus on:
Trigger — A label without brackets, specifying what action or event causes the transition from one state to another.
Guard — Like in activity diagrams, a guard is the condition under which a trigger actually causes the transition. If the guard isn’t met, the trigger won’t do anything. Just like in activity diagrams, it’s placed in square brackets.
In earlier articles, we discussed a video hosting system, built a use case diagram and a logical data model for it. I won’t repeat the scenario here, but recall that a data class called Comment had a status (shown in the data model). Moderators can make decisions on comments, effectively changing their status — i.e., transitioning between states.
This makes it a perfect use case for a state diagram.
Advanced Aspects:
Composite State — A state that contains substates. You can show transitions within it on the same diagram or split it out into a separate diagram (linked with the “double circle” symbol):
That’s pretty much it. UML does allow for additional elements in this diagram, but considering that business analysts don’t need this type of diagram often (and when you do, it’s very useful), we’re not going to dive into that extra complexity. No need to overcomplicate things.
Common Mistakes:
There aren’t many, since the diagram is simple to draw. But here are the usual suspects:
Pointless Usage
Don’t create “logically meaningful” states just for the sake of it. That’s just wasted effort. If you define states in your requirements, they should be driven by actual needs. Take our original example of a Comment: we shouldn’t say “conceptually, a Comment can be created, edited, viewed, deleted — so let’s make all those into states.” That’s useless. It adds no value to the understanding or implementation of the system. When you define states, you’re saying the system has to track them — which probably means you now need an attribute like Status on the Comment entity, which must change according to transition rules. The system needs to do this for a reason. If there’s no reason — don’t add the states.
Confusing Actions with States (And Misunderstanding the Diagram’s Purpose)
At a glance, someone might go: “Wait, isn’t this just another activity diagram? Why do we even need this thing?” I thought the same thing myself, back when I was trying to grasp the dao of this diagram. Maybe I’m just a little dense, but it took some digging to get that there’s a fundamental difference between a process and an object’s lifecycle. We’re not showing a scenario here — steps, branches, actors, etc. We’re showing what states an object can be in, and how it transitions between them over time. This isn’t a “Have a meal” process (what steps it has, who’s involved, what can go wrong), but rather: what hunger-related states a person can be in during the day, and what transitions between them are possible — including when the day begins and ends.
Still don’t see the value? Well: you probably need to work with some complex entities in real life before this clicks. Or just consider the example above: Document in a document management system. Now imagine that document can have 20+ statuses as it moves through the system — all of which must be tracked. Why? At the very least, to show users the right status icon. And at most, to allow or block certain operations depending on current status. This diagram makes it easier not to miss key requirements, because it forces you to ask:
Can a document go from status A to status B?
Can it go back?
What causes the transition?
Under what conditions?
In which states can a document be created?
Or deleted?
What does it even mean for a document to “die”? Deletion? Archival?
These are critical questions you might overlook unless you zoom out and look at the bigger picture — and look at it from this angle.