Hi all. I am Peng Xiao. I am the author of ZenUML – a textual UML tool that takes markup text (DSL) and converts it into sequence diagrams. It is an honor for me to showcase the product here. If you would like to integrate it into your applications, please see the end.
Why a new text to Sequence Diagrams tool?
The question I am often asked is: There is already PlantUML (and other tools) so why do you bother to build another one?. In fact, some guy on reddit even asked me to give up. Well, ZenUML at least is doing a better job in some cases. Read to see how they compare according to three dimensions: DSL, Feedback, Output.
The DSL to define sequence diagrams in ZenUML
I started using sequence diagrams heavily around 2006. Since then, I have tried quite a few tools, including PlantUML. I like the idea of generating diagrams from text because I hate to constantly drag-and-drop and double-click to edit names etc. One thing I am not quite happy with PlantUML is its DSL. IMHO, it quickly gets unreadable when you start nesting logic as you can see in the above video. So I had to find a better way for presenting nesting logic: ‘{}’. It is widely used in the mainstream programming languages (sorry Python).
The following sequence diagram shows how a RESTful API might be implemented. Please note the DSL at the left-side. I hope most developers find it familiar enough.
For a full language reference, please go to https://www.zenuml.com/help.html.
DSL comparison (PlantUML vs ZenUML)
For PlantUML users, I have prepared a table showing which features are implemented in ZenUML and the difference in the language. Note, ZenUML supports sequence diagram only (for now).
|
Feature |
PlantUML |
ZenUML |
Comment |
|
|
|
|
In PlantUML’s basic* syntax, occurrence (the execution bar) is not drawn. In ZenUML, the occurrence is a first class element. Every message comes with an occurrence which shows how long the execution takes. |
@startuml User->A:method @enduml |
A.method
|
||
|
|
|
|
To send a message to self, just call a method without mentioning target participant. ZenUML does not allow self message to be the outermost message. This is because, in practice, we need a message from boundary (or an Actor) to ‘start’ the interaction. |
@startuml A->A:selfMessage @enduml |
A.method() { selfMessage() } |
||
|
|
|
|
This is where ZenUML really outperformed. PlantUML’s DSL becomes hard to read quickly as we add nesting relationship. In addition, if we change the order of ‘deactivate B’ and ‘deactivate A’, the diagram would remain the same, which is flawed. The ZenUML syntax is simple and consistent. Note that, in the highlighted line, we did not mention ‘A’. It was deduced from the context. |
@startuml participant User User->A:MethodA activate A A->B:MethodB activate B deactivate B deactivate A @enduml
|
A.methodA() { B.methodB() }
|
||
|
|
|
|
The two implementations look similar. Note that, in ZenUML, in the two highlighted lines, we did not mention ‘A’. It was deduced from the context. While in PlantUML, we actually can put ‘B->Log’ there, which will produce an invalid diagram (or one that is very unlikely to be the user’s intention). ‘Loop’ is very similar to ‘Alt’ in both implementations. |
@startuml User->A:MethodA alt successful // B->Log: Success A->Log: Success else A->Log: Failure end @enduml
|
A.methodA() { if (successful) { Log.Success() } else { Log.Failure() } }
|
* PlantUML supports occurrence with ‘activate/deactivate’ keywords.
Without doubt, PlantUML is a great tool good and has features (and a huge ecosytem around) that ZenUML does not have. For ZenUML, two features are under development – ‘return’ and ‘new’ keywords; one is planned: Comments as notes.
However, what makes ZenUML unique is that it is an (opinionated) modelling tool. ZenUML enforces a valid model, while PlantUML allows you to draw anything. When there are more than two levels of nesting, PlantUML becomes hard to read, while ZenUML remains readable. For example, the following code, effectively, generates the same diagram:
@startuml participant User User -> A: MethodA activate A A -> B: MethodB activate B B -> C: MethodC activate C deactivate C deactivate B deactivate A @enduml |
A.methodA() { B.methodB() { C.methodC() } } |
Output
While PlantUML produces diagrams as pictures (png, svg) and some other tools generate ASCII or draw on Canvas, ZenUML takes a different approach. It produces pure HTML DOM elements. The benefits are:
- You can apply any styles on it – different colors, borders, fonts and even handwritten styles.
- You still can produce images from it. This is already supported in the Chrome Extension.
- It is searchable. Participant names, messages are all text on the page. If you insert the diagram into another document, it is indexable.
Feedback
PlantUML and most other tools have a ‘Submit’ (or ‘Refresh’) button. You have to click that button to get the resulting diagram. This is because they need to send the code to the backend server and get the picture back from the server. Websequencediagrams does not have the button, but it does a best-effort work to show the latest diagram. It is still far from being instant. As you can see in the GIF, ZenUML provides instant feedback to the user’s input. This is because all the conversion happens in the browser, no back-end request at all.
Js-sequence-diagram is implemented in a similar way. There is a difference though. With Js-sequence-diagram, the whole diagram is re-rendered every time you type in a letter. It is kind of distraction. ZenUML is implemented with VueJs. VueJs implements a Virtual DOM, and it only updates what you have changed (participant names, messages, etc.).
A little bit of history and more
The first version of this tool was created in 2010 as a work for the first HTML5/CSS/JS competition in ThoughtWorks China. It was first implemented with drawing diagrams on Canvas. That version is still on github.
The source code for the website and Chrome Extension is also hosted on github (site, extension). Feedback and/or pull request are welcome.
Integration and license
It is super easy to integrate it to any web-based applications. You can find a demo project on github. If you need help, please drop me a mail at eagle.xiao(at)gmail.com.
All the pseudo code and generated diagram (in its HTML format and/or image format) are owned by the author of their corresponding source code (that is, their textual description in ZenUML language).
My name is Peng Xiao. I am an (hands-on) architect. I work for Fabric Group at Melbourne.
Hi,
first of all nice job. The dsl is closer to a oo programming language that plantuml. However, by using plantuml for quite some time I went beyond the simple use case you explained here. For example the nested message where you said zenuml outperforms plantuml I cannot completely agree. I, for example, would use includes here and put the subsequent calls into these separate files. Meaning, my main class would to an !include A.iuml and the file a.iuml would include the B.iuml with all the stuff from the related component.
However, your resulting images look way cooler and the thing I miss the most with plantuml, the object oriented approach of calling a method from an object. This is way more natural for people used to programming languages but not necessarily for people who are not.
Anyhow, I think you do an amazing job and I don’t think you should give up.
Sincerely, Michael
Thanks for your feedback. `include` is on our todo list 🙂
Your arguments are convincing. Good idea to have it as HTML. Sounds like a new generation of text-based UML-tools, keep on promoting that!
All these tools suffer from bad layout. Sequence diagrams do not have a difficult layout, so this kind of UML is something I would do with a text-based UML-tool. But class-diagrams, and specifically package-, component- and deployment-diagrams have a higher requirement of layout. I want to determine where the node is, left, right, top, bottom, relative to others, absolute, I want to determine the length and angle of arrows. Achieving a good layout is really time-consuming with e.g. plantUML. The question rises whether text-based tools actually can provide a solution for such requirements.
For me the question rises: should I do sequence-diagrams with zenUML, and package-diagrams with some graphical editor? For compound work where you outline a whole application through diagrams, the look must be consistent. Never achievable that way.
Very valid and insightful observations. We are facing similar difficulties when designing for class diagrams. We may have to introduce some styling keywords for layout (borrowing ideas from CSS).
Hi Xiao,
I love your tool: the OO style DSL syntax is very natural and cleverly captures the idea of scopes; and the responsiveness of the CSS makes it very friendly to use.
I tried out a real life example and think it’s produced a drawing error where the enTrader.”create deal” request appears shifted over from the enTrader lifeline. I don’t think I’m using your syntax wrong so is this a bug?
Thanks for the tool. Very useful!
webICE METhane FIXFileStore enTrader
@Starter(Trader)
webICE.”book trade”
{
METhane.”notify trade update”
{
file = FIXFileStore.”create file”
{
}
}
FIXFileStore->METhane.”trigger file watcher”
{
METhane.”create FIX staging record”
}
METhane->METhane.”poll for FIX staging records”
{
deal = enTrader.”create deal”{
}
}
}
Hi David Regan, Thanks for reporting that. I can confirm that it IS a bug. I am working on it and should have a fix released in a few days.
Hi David Regan, this has been fixed. Please check it out. In fact, you do not have to add empty “{}”, that is implied. You should not need to clear-cache, but if it does not work, please try an incognito window first. Should you have more questions, please let me know.
Hi Xiao,
Thank you for the quick fix. I’ve tested it via the zenuml link and it works fine.
The chrome extension still has the issue but I guess this is released separately.
Thanks again,
David
Chrome extension fix (1.0.26) has also been released. https://chrome.google.com/webstore/detail/web-sequence/kcpganeflmhffnlofpdmcjklmdpbbmef . It should be dispatched to your browser within hours. Another new version with fix on the editor shifting bug is also coming (1.0.27).