Web Sequence Diagrams

One of the most powerful elements in your UML tool belt is the sequence diagram. There are several different tools that allow you to build sequence diagrams, from drawing tools like Visio and OmniGraffle to modeling tools like MagicDraw and ArgoUML. But one of the tools that I have found to be the most valuable is provided as a web application: Web Sequence Diagrams.

WebSequenceDiagrams.com is a web-based application that allows you to use a proprietary language to define your sequence diagram and then it renders your sequence diagram as an image. The reasons I have found it to be so valuable are the following:

  • Resource non-intensive: it requires very little resources to run because it is just a web page
  • It is very easy to modify sequence diagrams: have you ever built a very good sequence diagram and then had to change the order of operations? It is usually a painful process to move calls between components around and then to fix the drawing. With Web Sequence Diagrams all you need to do is cut-and-paste sections you want to move
  • Ease-of-use: when you finish reading this article you should be 90% on your way to effectively using Web Sequence Diagrams, but even if you are not technical, I have found business analysts becoming very adept at using Web Sequence Diagrams in a short period of time, not just developers and architects
  • UML 2.x support: it supports most of the UML 2.x functionality
  • Web platform: because it runs exclusively in a web browser, I now have a sequence diagram tool that runs on my iPad!
  • Cost: most of the functionality is available available for free. You can buy a basic version for $99, as of this writing, which includes support for states and parallel signals as well as offline or standalone use.

To get started, navigate over to WebSequenceDiagrams.com. You should see a page similar to figure 1.

Figure 1. Web Sequence Diagrams Homepage

As figure 1 shows, you enter the text describing your sequence diagram on the left and the sequence diagram is rendered on the right. If you do not know how to accomplish a specific task, then the toolbar on the left will generate code for you that corresponds to its drawing. For example, the top image shows component A sending a signal to component B, such as to invoke a method or service, and the second image shows component A responding to component B. If you click on either of these images then you will see the text that generates this interact. As an example, enter the following:

A -> B: Sort List
B --> A: Sorted List

These simple two lines define participants A and B and show that A tells B to sort a list and B returns the sorted list back to A.

Web Sequence Diagram Syntax

The basic process for using Web Sequence Diagrams is to define your participants (which represent your life lines) and then define the interactions between participants. When you want to use more advanced features, such as defining conditional actions using the ALT construct or defining iterative actions using the LOOP construct, then there is additional syntax to support these actions.

Let's start by defining participants. You can allow your participants to be implicitly created when they are used, such as in the earlier example, or you can explicitly define them at the beginning of your sequence diagram. The benefits to explicitly defining them are that (1) you can control the order in which they appear in their sequence diagram and (2) you are able to alias them with something that is easier to type. With respect to the second point, if you had a "User Authorization Service" participant then you would have to type that every time you referenced it in your sequence diagram, but instead you can define "User Authorization Service" as userAuthService, which is easier to reference in code, but it allows you to retain the more user-friendly description in the participant itself.

You can define participants explicitly as follows:

participant Client as client
participant "User Authorization Service" as userAuthService

And then you can use the participant as follows:

client -> userAuthService: Authorize User
userAuthService --> client: Authorization Response

Putting these code snippets together yields the screenshot shown in figure 2.

Figure 2. Explicitly Defining Participants

Once you have your participants defined, it is time to send signals between them. In Web Sequence Diagrams, signals come in two forms:

  • Sender
  • Response

Signals are sent using an arrow: "->" and responses are sent using an arrow with two dashes: "-->". In the sequence diagram, signals are represented using a solid arrow while responses are represented using a dashed-line arrow, refer to figure 2 for an example.

Something that you might notice is missing from these life lines is activation bars (the bars that show when a particular participant is actively doing something versus when they are not involved in any interaction. Unfortunately with Web Sequence Diagrams, activation bars need to be manually defined, but doing so is not challenging. Activation bars are controlled by the activate and deactivate keywords, for example:

title Authorization Sequence

participant Client as client
participant "User Authorization Service" as userAuthService

client -> userAuthService: Authorize User
activate client
activate userAuthService

userAuthService --> client: Authorization Response
deactivate userAuthService
deactivate client

Manually writing the activate and deactivate keywords is not ideal, but not too cumbersome - just you need to remember to do it.

If you need to illustrate a participant communicating with itself, you can do so by sending a signal (->) from the participant to itself. For example:

title Authorization Sequence

participant Client as client
participant "User Authorization Service" as userAuthService

client -> userAuthService: Authorize User
activate client
activate userAuthService

userAuthService -> userAuthService: Check cache

userAuthService --> client: Authorization Response
deactivate userAuthService
deactivate client

This code yields the sequence diagram shown in figure 3.

Figure 3. Activation Bars and Self Signals

Conditional Segments

You often want to denote in a sequence diagram that certain actions should only take place if a condition is true. In sequence diagrams we represent conditional segments by drawing a box around the segment, putting the ALT keyword in the upper left corner, and then defining the condition for when this segment should be executed. Furthermore, we can draw multiple else boxes below it with different conditions as well as an else without a condition as a default catch-all. Web Sequence Diagrams supports this using the "alt" keyword to start the conditional segment, the "else" keyword for alternate cases, and the "end" keyword to terminate the conditional segment. The following is an example that shows both a condition as well as an else case.

title Authorization Sequence

participant Client as client
participant "User Authorization Service" as userAuthService
participant Database as db

client -> userAuthService: Authorize User
activate client
activate userAuthService

userAuthService -> userAuthService: Check cache

alt User not in cache
  userAuthService -> db: Get User
  userAuthService -> userAuthService: Put user in cache
else
  userAuthService -> userAuthService: Add a hit count to the cache
end

userAuthService --> client: Authorization Response
deactivate userAuthService
deactivate client

This yields the sequence diagram shown in figure 4.

Figure 4. Conditional Segments

Additionally, you can define additional else conditions with a series of statements like "else Another Condition".

Summary

This article introduced you to Web Sequence Diagrams and demonstrated how to create a diagram with participants, how to send signals to and from participants, how to allow a participant to send signals to itself, how to use activation bars, and how to use the alt keyword to define conditional segments in your sequence diagram. In the next section we'll build on this foundation and see how to use optional segments, loops, and notes as well as what features Web Sequence Diagrams provides for paying customers.