Disclaimer
If you are an experienced IT professional, feel free to skip to the 'Interesting Features' chapter, which is likely why you came to this page.
What is it?
A sequence diagram is used to visualize the interaction between objects in a system. It shows the order of messages exchanged between objects over time and their lifecycle. In my opinion, it is the simplest and most convenient tool for demonstrating all integrations and interactions within a designed business process.
What does it consist of?
The main elements of a sequence diagram are: objects (green), lifelines (red), and messages (blue).
Objects— are entities that interact with each other. For example, a user, a topic or queue, a microservice. In addition to a name, objects can also differ by their type:
Lifelines (lifelines) represent the flow of time, as well as the activity or execution of certain object functions. They are represented as a vertical line with an activation bar.
Messages (messages) show the exchange of information between objects. For example, a user clicking a button, but more often it's a request or response, a stored procedure call, or sending a message. Messages are displayed as arrows pointing from one lifeline to another, and come in several types:
Where and how to use it?
There are many options for drawing UML diagrams. The most popular are:
Graphical editor draw.io
The simplest solution that doesn't require learning UML syntax is the graphical editor draw.io, also known as diagrams.net. To create a diagram using draw.io, you just need to get a little familiar with the program's interface, find the shapes for creating sequence diagrams in the search, and start dragging them onto the canvas:
It's all quite simple, but problems begin when you need to make a diagram with a large number of object interactions. There will be a lot of editing, and drawing such a diagram will take much more time. Therefore, it's better to understand UML syntax and master the other 2 options for "drawing" diagrams.
Let's understand the syntax
Unfortunately, you can't just start using a UML diagram right away. You need to at least superficially study the PlantUML syntax. It's very simple, so basic examples will be enough to start working on diagrams.
First, you need to realize again that there are the entities described above: objects, lifelines, and messages. For lifelines to appear, you must clearly define the objects at the beginning of the document:
actor "Пользователь" as u participant "Фронт" as f participant "Бэк" as b
Or you can choose not to do this (which I don't recommend, as readability, in my opinion, will significantly worsen), as they will appear automatically when describing the second entity — messages. To describe messages, arrows '->' are used. You just need to specify which object the message comes from and which it goes to — 'client -> server':
actor "Пользователь" as u participant "Фронт" as f participant "Бэк" as b u -> f f -> b b -->> f f -->> u
Based on my experience, I'll highlight right away that usually no one uses all types of objects and arrows at once. Among the object types, the most common are:
actor — user or 'client';
participant — server, system component;
database — database;
queue — topic or queue.
Among the frequently used arrows:
a ->> b: Асинхронный вызов a -> b: Синхронный вызов a -->> b: Ответ a -x b: Запрос, который будет удален 'или от которого решили отказаться/устаревший
Synchronous/Asynchronous call is –
Synchronous call — an interaction in which one object sends a request and must receive something in response from another object. For example, the interaction between a browser and a server.
Asynchronous call — an interaction where one object sends a request to another but does not receive a response. For example, the operation of queues or topics: one object puts data into a topic, and a second object retrieves this data, but no acknowledgment is sent back to the first object.
Grouping
Now that we've covered the most common types of arrows and objects, let's look at another important concept — message grouping. Here again, I will discuss the most popular ones that I actually encounter in my practice. Grouping is needed to meaningfully arrange messages, as well as to apply certain rules to specific messages. For example, you can group several messages by meaning and give them a name, or you can group them into a 'par' group, thereby highlighting that the messages in this group are executed in parallel.
Alt — a grouping that imposes certain rules. It is used to show alternative cases for interaction, used with the else operator. For example, an object can send a request, and the second object, depending on the data received, will perform different actions:
Syntax and example
alt case 1 a -> b else case 2 a -> c end
Opt — used to highlight a message as an optional case. For example, an object can send a request, and the second object, depending on the data received, may perform an additional action:
Syntax and example
opt a -> c end
Par — used to highlight messages that are executed in parallel. Used with the else operator. For example, an object can send a request, and the second object will perform internal calculations in parallel and return a response to the first object:
Syntax and example
par a -> b else a -> c end
Loop — used to highlight messages that are executed multiple times. For example, an object can send a request, and the second object will perform internal actions several times depending on the data sent:
Syntax and example
loop a -> c end
Group — used to group messages by meaning. For example, a diagram may have many interactions, and to reduce confusion, you can label groups of messages:
Syntax and example
group a -> c end
You can also group the objects themselves. This can be useful for describing the interaction of multiple systems with microservices:
Syntax and example
box Название participant "Название 1" participant "Название 2" box end
A detailed description of all the features of sequence diagrams can be read here, including all types of objects, arrows, and groupings that I decided not to describe in this article.
plantUML sandbox and plugins
After we've understood the UML syntax, we can 'draw' more complex diagrams, for example, in the sandbox from plantUML. It looks like this:
Source code
@startuml actor "Браузер" as b box "Работа с пользователем" participant "Модуль клиентов" as c participant "Модуль обработки данных" as d box end box "Хранение данных" participant "Модуль хранения данных" as s database "База данных" as db box end b -> c: Запрос данных activate c opt В запросе параметр обработки = true c -> d: Запрос на обработку данных activate d d -->> c: Ответ deactivate d end c -> s: Сохранение данных activate s s -> db: Запрос в БД activate db db -> db: Сохранение db -->> s deactivate db s -->> c deactivate s c -> c: Формирование ответа c -->> b: Ответ deactivate c @enduml
But the most convenient tool for working with sequence diagrams is your favorite IDE. For example, you can install a plugin directly in WebStorm from JetBrains.
More details:
Creating diagrams through your favorite IDE is the most convenient way, plus the files are stored directly on your device. The UML format for describing sequence diagrams works very well with version control systems, so you can safely manage your projects using git.
Interesting Features
Colors
Changing the arrow color
-[#blue]> -[#ff00ff]>
This feature is useful in cases where you need to highlight something.
I've encountered situations where certain companies had specific regulations for arrow colors. For example, existing flows had to be colored blue, existing ones being modified — orange, and new ones — red.
Besides arrows, you can also color the text itself. How to use this — you can figure it out yourself.
Changing the text color
A -> B: <color #f0f>Запрос</color> B -->> A: <color #green>Ответ</color>
You can also configure colors for the 'lifeline' and the object itself. By the way, you can find a huge number of settings online for customizing basic styles, including fonts, line thickness, margins, and much more. Such settings usually start with the 'skinparam' operator.
Changing styles
Yes, yes, I know, it looks
crappy... I mean, not great.
Activation bar
I recently discovered that you don't have to write 'activate' and 'deactivate' every time; '++' and '--' are sufficient.
Example:
#было: Alice -> Bob: Authentication Request activate Bob Bob -> Sanya: Another authentication Request activate Sanya Sanya --> Bob: Authentication Response deactivate Sanya Alice <-- Bob: another authentication Response deactivate Bob #------------ #стало: Alice -> Bob++: Authentication Request Bob -> Sanya++: Another authentication Request Sanya --> Bob--: Authentication Response Alice <-- Bob--: another authentication Response
You have to agree, there's much less UML code, and readability has even improved. And this is what it looks like:
Autonumber
Many people know what this operator is and how it works, but not many know that its functionality is much broader than just incrementing the message number.
The number can also be styled, overridden, have sub-items added, be used as a variable, and much more (more details here).
Changing autonumber
autonumber 10 5 "<b>(<u>##</u>)" Alice -> Bob Alice <-- Bob Alice -> Bob ||| autonumber 1 "<font color=red><b>Message 0 " Alice -> Bob autonumber "<b>[000]" Alice <-- Bob ||| autonumber 2.1 Alice -> Bob Alice <-- Bob Alice -> Bob
I personally use sub-items quite often.
Note
In my practice, I have very rarely seen diagrams where someone used this cool feature. With it, you can describe some nuances of interaction in more detail or simply specify an address (host:port).
Note
note right REST: **some.adress.com:433/new** end note
Divider
Despite how cool notes are, I rarely use them, but I use dividers quite often. There are cases where an integration has, for example, 2 scenarios. To avoid cluttering the analytics page and duplicating a lot of UML code, you can draw one diagram but split it into 2.
Divider
#Синтаксис == Сохранение данных ==
Conclusion
In conclusion, I want to say that the sequence diagram is a very cool and powerful tool for describing interactions and integrations, and learning to use it is quite easy, especially when you have material with a syntax description at hand.
I also have a Telegram channel, Ordinary IT Guy, where I share my experience and knowledge of the IT industry. The best support is to subscribe to my channel ❤️
P.S.Perhaps I forgot to write about some features or didn't even know about them. Please share in the comments if you use anything else that I haven't covered in this article. If there's something worthwhile, I will definitely add that feature/peculiarity, as well as credit you as the author.
All the best!
You can also check out my guides on BPMN and on XSD, in which I tried to briefly explain the main message for beginners in the same format.