Add a sequence diagram to Notion

Update

I created a MacOS app that uploads PlantUML code to Notion.

Check it out

In order to express their ideas about a project’s architecture, developers can utilise the UML sequence diagrams.

There are different ways to create and publish these diagrams, ranging from paid apps(8$/month, 100$) to free Confluence apps.

It can be a formidable task to choose from all of these options. As a programmer, a good solution could be to write the diagram in text, and later commit or convert it to an image.

PlantUML ☘️

With PlantUML, sequence diagrams can be defined in a text format, and output to .svg or other image formats via a command line tool.

Consider the diagram:

This can be defined in a very human-readable format inside a diagram.puml file:

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

And then converted into .svg using the command line tool:

java -jar plantuml.jar -tsvg diagram.puml

There are different extensions for PlantUML. In Atlassian, one can write the definition and it will be output as an image into the document.

For the Notion workspace, there is no official integration. Instead, we can write a script and use their API.

Notion table 📝

First, the diagram should be described using either the PlantUML text format, or as a relational table.

If we want to use relations between UML objects, we need to use the latter.

Services table

In the first table, a single column with our services Alice and Bob needs to be described.

Alice and Bob services

Diagram table

In the second table, the actual diagram will be described with actors from the related services👆🏽table.

Alice and Bob diagram

Note field will be used as the action name.

Output from the tables ⚙️

To convert the tables into UML, we can use a Python script to download the Notion table, convert it to PlantUML, and output the UML image.

notion.py, “Unofficial Python 3 client for Notion API v3”, can be used to:

request the tables from our Notion workspace

client = NotionClient(token_v2=token)
cv = client.get_collection_view(sequence_diagram_table_url)

translate the tables into PlantUML

for row in cv.collection.get_rows():
    service_origin_block = row.origin[0]
    service_end_block = row.end[0]
    pum+=("\"{}\" -> \"{}\": {}\n".format(
        service_origin_block.name,
        service_end_block.name,
        row.label))

output the final image using plantuml.jar

subprocess.Popen(["java", "-jar", "plantuml.jar", "-tsvg", "out.puml"])

Result

After calling our script:

python notion-diagram.py https://www.notion.so/952a65008448439b9f0d82c9755a525d\?v\=0de421bd4e2b485fb624ff4edc527e0d Alice

we get our sequence diagram result

Optionally, the output could be uploaded to Notion or other services.

The script is available in tonisives repo. It is based on the official Notion blog post.

Conclusion 🖋

It is possible to create sequence diagrams in a text format, and convert them to images later.

What are the positives? 👍🏽

Can edit diagrams in a text format.
Don’t have to load a web page or a different app.
Can generate UML from command line, then transfer the image anywhere.

What are the negatives? 👎🏽

Cannot use a GUI program
Requires scripting and shell usage knowledge
More difficult diagrams can be hard to write

Related tweet:

How to add a sequence diagram to @NotionHQ https://t.co/9Cto6kb8rH
— Tõnis Tiganik (@tonisives) December 1, 2020