Quick, Declarative UML Sequence Diagrams

I recently had to create a few UML sequence diagrams, and I decided that I didn't want to spend too much time manually tweaking and fixing the diagrams themselves (which is what I probably would've done, had I used OmniGraffle or something similar), but instead focus on the content — the depicted workflow itself. This is when I remembered the bookmark I had in my browser for the Web Sequence Diagrams online service.

Benefits of Declarative Diagramming

Web Sequence Diagrams is great. It uses a simple, readable syntax you can use to type in descriptions of sequential workflows and based on that it will generate the corresponding UML sequence diagrams for you.

Working with these diagrams in this way has a couple of nice benefits over more intricate/professional methods:

• They're quick to create and quick to modify
• The syntax is pretty easy to read as-is
• The source is plain text, so all the benefits of using plain text apply (e.g. can put under source control, can use simple diff tools, file sizes are small etc.)

Helper Script and Syntax Highlighting

When I was sure I wanted to use this method again in the future, I hacked up a few quick and simple tools for this:

Script for generating the diagram images from source files

At the time of this writing, there’s a suggestion called “Create a command-line version of this application” on the service’s UserVoice site that’s labeled “started”, so hopefully in the future we’ll have a command-line sequence diagram generator from the author of the online service. In the meantime, though, here’s my solution. This is a Python script that can be used for generating the diagram images (using this service) from “source files” that contain the declarative workflow syntax. You just need to:

1. type up your diagram description in a text editor and save it into a file
2. begin the first line in the file with #wsd (so that the script knows this is a websequencediagrams.com syntax file)
3. (optional:) specify the diagram style you'd like to use on the first line with the syntax #wsd:style=modern-blue
4. call the script with the path to this file as an argument to generate the diagram image

The script uses a temporary SQLite database to save hashes of file contents so that even if you call it repeatedly for the same file, it'll notice if the file contents haven't changed and decide not to send a request over to the server. I did this in order to reduce unnecessary load on the server. I tested the script on Mac OS 10.5.7, Windows XP SP3 and Ubuntu 9.04 and it seems to work just fine on all of those (of course, on Windows you'll first have to install Python manually).

Download the script here: wsd.py

Here's an example on how to use it (to see the script's usage info, run it without any arguments):

Save this into a file called ax-diagram:

#wsd

participant "Component A" as A
participant "Component X" as X

X -> A: what up
A -> A: processWhatUp()
note over A: A is confused
A -> X: go away
destroy X

Then run the script:

wsd.py ax-diagram

...and the file ax-diagram.png is created:

jEdit syntax highlighting mode

This is a simple jEdit syntax highlighting mode for the Web Sequence Diagrams syntax. You can download the file here: this other blog post of mine for instructions on how to install modes for jEdit.

Here's a screenshot of the highlighted syntax on my machine: