How to model an interaction sequence with Yantra Studio
Record an interaction as an ordered sequence over the components that take part in it, then set the order the diagram is revealed in so it can be presented as a walkthrough rather than explained over a static picture.
When this is useful
- A structural diagram is on the table and the first question is "so what actually happens when a user clicks buy?".
- Two teams disagree about which service calls which, and the disagreement is really about ordering.
- You are handing a design over and the sequence is the part that lives in your head.
Before you start
- The participants as shapes on a page. A sequence is modelled over components, so they need to exist first.
- One concrete scenario. Model the checkout, not "checkout and also the refund path and also the retry" — a sequence that tries to cover every branch stops being readable.
Step 1: Put the participants on the page
Insert a shape for each participant in the interaction — the caller, each service it reaches, the store at the end. Keep it to the components that actually take part; a participant that appears once and does nothing belongs in the structural diagram, not this one.
Page ▸ Entity / TablePage ▸ Text box
Step 2: Record each step as a connector
Draw a connector for every message, in the direction the call travels, and label it with what is being asked for. The label is what turns a diagram of arrows into a sequence someone can read without you standing next to it.
Where a participant is busy for the duration of several downstream calls, that span is an activation — the part of the sequence where it is holding the request open rather than merely being mentioned.
Page ▸ Connector
Step 3: Set the order the sequence runs in
Open flow order and put the steps into the order they actually happen. Until you do, the diagram knows the connections but not the sequence, and a presentation of it will reveal things in whatever order they were drawn.
Number badges make the order visible on the canvas while you are still adjusting it.
Page ▸ Flow order
Step 4: Walk somebody through it
Present in flow mode to reveal the diagram one step at a time in the order you just set. That is usually enough for a design review.
Designer mode is the scripted alternative, for a presentation where you want finer control over what appears when — a stakeholder session rather than a working discussion.
Page ▸ PresentPage ▸ Flow (default)Page ▸ Designer (script)
What happens next
The sequence is part of the model rather than a separate drawing, so the participants in it are the same components impact analysis and simulation work over.
If the sequence came out longer than about a dozen steps, that is usually a signal to split it — one sequence per scenario reads far better than one that branches.
Example
A checkout: browser to the orders API, the API to inventory, inventory back, the API to payments, payments back, the API to the queue for fulfilment.
Six steps, flow order set, presented in flow mode. The disagreement in the room turned out to be that half the team thought payments was called before inventory, which the walkthrough settled in about a minute.
Tips
- Model the successful path first and completely. Error branches added before the happy path is agreed tend to obscure the thing everyone is actually arguing about.
- If the interaction was generated from a codebase, guided views may already describe named paths through the system — check for those before drawing one by hand.
- Presentation is read-only for the audience, so you can present to people who should never edit the model.
Limitations
- Presentation modes are separately enabled, so flow and designer presentation may not be available in every organisation.
- Flow order describes one ordering per page. A page that needs two different orderings needs two pages.