Web Sequence Diagrams
Written By Mar 8, 2012on
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:
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
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".
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.