Four log lines and what they leave out
A shop's checkout service logs one failed purchase in four lines: reserve LAMP-07 x2, charge 39.80 EUR, declined, release reservation r-17. The order is all there. Two things are not: who asked whom, and who sat waiting for an answer. Did checkout wait for the charge, or send it and move on? Did inventory release the lamps on its own, or because someone told it to? A sequence diagram draws exactly those two things for one interaction.
It answers a different question from a class diagram: not what exists, but what happens, in what order. A call in it is usually one of the receiver's operations, listed in the compartment The class box: name, attributes, operations describes.
Time runs downward
Each participant gets a Lifeline: a head that names it, with a dashed line running down from it. Time flows down each lifeline, so of two messages on the same lifeline the lower one happens later; how far apart the lifelines stand means nothing. A person who starts the interaction gets an Actor Lifeline, the stick figure. Other heads read role: Type, so app: Web is the participant called app, of type Web. It is the form an object diagram uses for an instance, which Object diagrams: one moment of a running system covers.
Start with an interaction that never branches: a shopper signs in.
The dashed reply carries what the call waited for: the session.
A message is an arrow from the lifeline that sends it to the one that receives it. submit(email, password) and verify(credentials) are synchronous calls: the sender waits until the answer comes back. The answer is the reply, session returning from auth to app. Replies can be omitted, since the filled arrowheads already say who waited; drawing them makes explicit what came back.
While auth checks the password, it is busy. An Activation bar, the narrow rectangle laid over a lifeline, marks that stretch, the time an operation is executing there, including any wait for the calls it makes: on auth it would run from the moment verify arrives to the moment session leaves. The Login Sequence Challenge is this diagram grown by one lifeline, the store that holds credentials and sessions, and carried one step further, to the session handed back to the shopper.
Checkout, where the paths split
The login above was drawn with one path, the successful one. Checkout has two, and the second is the reason to draw the diagram at all. The participants are the shopper, checkout, inventory and the payment provider. Checkout reserves the stock before it charges the card, so the shop does not take money for lamps it cannot ship. When inventory reserves, it creates a Reservation, which gets a lifeline of its own, its head placed level with the message that created it. The Money amount passed in the charge does not get one: lifelines are for the participants of this interaction, and a value that only travels as a parameter appears in a message label.
One message in a checkout is sent without waiting: on an approval, checkout sends the receipt email and carries on, with no reply expected. That is an asynchronous message, drawn with the open arrowhead the note below describes.
Here is the declined purchase from the logs, as messages:
- The shopper submits the order to checkout.
- Checkout asks inventory to reserve two lamps, and waits.
- Inventory creates the reservation r-17.
- Inventory replies to checkout with the reservation's id.
- Checkout asks the payment provider to charge 39.80 EUR, and waits.
- The payment provider replies
declined. - Checkout tells inventory to release r-17.
- Inventory ends the reservation.
- Checkout tells the shopper that the payment failed.
Steps 7 to 9 happen only on a decline; on an approval the reply at step 6 says so, and checkout sends the receipt instead. Both paths belong on one diagram, inside a Combined Fragment: a box drawn over the region where they differ, labelled in its corner tag. alt holds alternatives, one operand per branch, separated by a dashed line, each with its guard in square brackets: [approved], [declined]. The other common tags are opt, for a region that may not happen, and loop, for one that repeats.
Step 7 is there because the reservation is a change already made inside another participant, and a decline at the payment provider does nothing to it. Undoing it takes a message of its own, a compensation, sent by checkout, the participant that knows the charge failed. When the steps span services that each commit on their own, the full pattern is Saga.
Step 8, inventory ending the reservation it was told to release, is drawn as a Destruction, an X at the foot of the reservation's lifeline: the reservation object ends there, and after it that participant takes part in nothing more.
1. submit(email, password), 2. verify(credentials)), write each branch's guard in its message label ([approved], [declined]) beside an alt Fragment, label a fire-and-forget message async, and connect an Activation or a Destroy to the lifeline it belongs to.Draw the decline first
Checkout Sequence is the purchase this article has been tracing: the shopper, checkout, inventory, the payment provider and the Reservation that inventory creates. Start with the [declined] branch, because it is the one that tests the design. Number the messages so the reservation comes before the charge, put the release inside the branch, and end the Reservation's lifeline with a Destruction connected to it. The [approved] branch, with its receipt labelled async, is then the easy half.