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
Sandbox from plantUML
Using a plugin in JetBrains tools or VSCode

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:

Создание диаграммы в draw.io — Creating a diagram in draw.io

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: Запрос, который будет удален
'или от которого решили отказаться/устаревший

Часто используемые стрелки — Frequently used arrows

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

Пример группировки объектов — Example of object grouping

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:

Пример работы в plantUML — Example of working in plantUML

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:

Установка плагина для работы с UML — Installing the plugin for working with UML

Создание файла формата .puml — Creating a .puml format file

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]>

Изменение цвета стрелки — Changing the arrow color

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>

Изменение текста сообщения — Changing the message text

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

Пример кастомизации — Customization example

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

Примеры кастомизации autonumber — Autonumber customization examples

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

Пример с подсказкой — Example with a 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.

Sequence Diagram