Geeks With Blogs
Ulterior Motive Lounge UML Comics and more from Martin L. Shoemaker (The UML Guy),
Offering UML Instruction and Consulting for your projects and teams.

In our last Episode, we saw how Forks and Joins let us model parallel behavior within Activity Diagrams. But we're not quite done with Activity Diagrams. (Click pictures for larger images.)

Episode 16a

Episode 16b

No, the dolphins in panel 3 aren't my work. Anyone who thinks I can draw that well hasn't been paying attention. They were drawn by my lovely wife Sandy for our wedding invitation. I merely traced them. (The scuba gear and the singing crab... Now those you can blame on me.)

To discuss Swimlanes, I needed water; and this was the best water-themed film I could think of; plus it's a film I really enjoy. Still, after the title of this Episode, I'm going to have a much harder time objecting to Editor Bill's puns. (In my defense: in Michigan, we always have a Wet October...)

I stretched standard Activity Diagram notation just a little in this diagram: when an Activity was the responsibility of two entities, I drew it straddling the boundary between their Swimlanes. That's a common stretch, but don't overuse it. A good rule of thumb is that each Activity or Branch should be assigned to one Swimlane.

And no, I have no idea how The UML Guy and The Reader talk with scuba mouthpieces in. It's a comic strip. These things happen.

Swimlanes give us a powerful tool to discuss who or what is responsible for each Activity. They're also the point where we stand on the requirements analysis shore and dip a toe -- just a toe -- into system architecture. We can start with an Activity Diagram that accurately describes the customer's business process; and then as we add Swimlanes and assign responsibilities to them, we slowly start to identify pieces of the system that we'll have to build. I start with business rules that make sense to the customer, and iteratively revise them into a hint of an architecture.

@curtisgray is going to kick me for this; but to demonstrate how we can move from requirements to architecture via Swimlanes, we need to abandon the funny for a moment and look at a more serious business system. We'll build on the example from panel 5. And to make it more legible (and easier for me to draw), I'm going to draw it with Enterprise Architect from Sparx Systems, a powerful UML tool at a great price.

We start with a simple description of business rules:

Episode 16d

Figure 1: Payment Processing (Business Rules Version)

The Supervisor logs in, if authorized, and issues zero or more payments for outstanding payables. When the Supervisor is done, the system shows a summary of payments issued. We use an Object with Data Flow Dependences to represent the summary information as it's generated.

Now our requirements say that this is supposed to be a Web-based system. (You didn't read that memo? I know I sent it to you. Must be lost in the system. What was your email address again?) So let's add Swimlanes for the Supervisor and the Web pages:

Episode 16e

Figure 2: Payment Processing (Initial Architectural Assignments)

In case it's not obvious, the Payment Page is a page that shows Supervisor the payment for final approval before payment. I could complicate the diagram by showing how Supervisor can approve or cancel the payment. But that way, madness lies! Trust me, Cancel is a hard problem to model, and to code correctly! At some later date, maybe we'll look at The Cancel Problem. For now, let's pretend Supervisor always approves selected payments.

Sometimes people ask me why I include Swimlanes for users. This diagram gives a pretty good answer to that question. The Branch in Figure 1 (Done or Process Another Payment) made sense in the context of the business rules: Process payments until we're done. But when we start thinking about architectural assignments, we have to ask for each Branch: What decides this? And what's the code for this decision? Well, in this case, only Supervisor can decide, and there's no code. Some Branches can be decided by program logic; but when a Branch can only be decided by user input, then I like to put that Branch in the user's Swimlane.

Note that Summary Results is in the Payment Summary Page Swimlane. That's really only for convenient layout right now. As we elaborate the assignments further, there may be a more proper place for it; but sometimes, there's just no convenient place to put an Object. In cases like that, I put the Object wherever it "fits" graphically, but as close as I can get to where it's used. Good layout isn't subject to hard and fast rules; it's a matter of esthetics, and there's no foolproof esthetics algorithm. (I also usually put Final States -- i.e., the "targets" that mark end points of the diagram -- wherever they happen to fit.)

I left some parts of the diagram outside of Swimlanes: two Activities (Authorize Log In and Make Electronic Payment) and one Branch (Authorized or Not Authorized). That's because my first pass was simply to identify user interface Swimlanes; and we all know that business rules and data access shouldn't be in the user interface, right? (Right? Right? Please tell me we all know that by now...) So let's add Swimlanes for the business processing:

Episode 16f

Figure 3: Payment Processing (Architectural Assignments, Revision 1)

OK, all you who doubted me when I said I'd find the right place for Summary Results, raise your hand. Let's see... 1, 2, 3... For the record, I'm typing one-handed right now, because my hand is raised. I hoped I would find a place, but I wasn't sure. Now that I've thought about it, though, it makes sense that the Payment System should allow a log of the latest payments.

If The Reader isn't asleep by this point, he may have noticed that I slipped an extra Activity into this diagram, one that was never discussed in the original business rules version: Confirm Payment. As we discussed the implementation, I realized this was an implicit rule in Figure 1: Issue Payment implies Confirm Payment; but Issue Payment belongs in Payment System, while Confirm Payment is part of the UI. Those needed to be separated.

And in fact, this is a common occurrence as you turn business rules into an architectural plan: you discover implicit rules, and also missing rules. For instance, in order to List Payables, it's necessary to find the outstanding payables. Nobody mentioned that in the business rules, because it was so obvious, everyone assumed it. Yet a literal reading of Figure 3 says that the UI just magically "knows" what to list.

Another problem with Figure 3 is that Electronic Payment System -- which is a third-party service (what, you didn't get that memo, either?) -- appears directly in our evolving program logic. For that matter, why do Payment System and Security System appear in the direct path of the diagram? Shouldn't these just be services that our main program just calls?

If you can't tell, my answer's "Yes"; but this will require more radical restructuring of the diagram:

Episode 16g

Figure 4: Payment Processing (Architectural Assignments, Revision 2)

Yes, I changed my mind: for layout reasons, I decided it was cleaner to move the Branch out of the Supervisor Swimlane and into the Payables List Page Swimlane. I just have to trust that no one expects the code to decide when we're done. (If there really were some confusion, I could add a note to the diagram.)

And suddenly, all of the "flow" logic is in the user interface elements, and all of the "do" logic is in the components and systems behind the UI. In fact, the four UI Swimlanes reflect the original business logic almost exactly. This is common as you evolve toward an architecture: you find that the UI elements -- the only elements the user can see, and the elements that they understand -- embody the business flow. (If you prefer a more UI-independent architecture, such as Model-View-Controller, you still find most of the business flow residing in one area: the Swimlanes that represent the Controller. But that's too complex for today's example.)

Note that the Transitions from the UI to the business Swimlanes are marked <<call>>. This is a UML stereotype. Stereotypes are too large of a topic for this Episode. For now, think of <<call>> as a tag that says, "Go ahead and follow this path; but when you're done, come back here and move on." Rather than create a whole new kind of arrow and have to remember what yet another arrow means, we put the <<call>> tag on the standard Transition arrow. Every programmer knows what a call is, after all, and we're moving into the Land of the Programmers.

Readers who know UML Sequence Diagrams -- or even just those who've read Episode 10 -- may be asking, "Isn't an Activity Diagram with Swimlanes a lot like a Sequence Diagram?" And my only answer is "Yes." In fact, it's easy to envision how we might turn The Hunt for Wet October into a Sequence Diagram, simply by drawing on top of the diagram we already have:

Episode 16c

Now it would take more than that to make a good Sequence Diagram; but you can see the possibility, I hope.

So if the diagrams can show the same information, at least in theory, why should we pick Activity Diagrams with Swimlanes over Sequence Diagrams? Or vice versa?

There's no absolute answer. In fact, some UML practitioners dislike Swimlanes for exactly this reason: "We already have a notation for that. Two notations only confuse The Reader." And I'm sympathetic to that view. But I see some reasons for preferring Activity Diagrams with Swimlanes:

  • Because these diagrams are essentially just flowcharts, most customers can read them without explanation. (On the other hand, I find business people learn to read Sequence Diagrams without too much effort.)
  • Because an Activity Diagram with Swimlanes can be created from the original business rules diagram (as I demonstrated above), users may more easily understand how the one led to the other. (On the other hand, you can certainly draw exactly the same thing with a Sequence Diagram. It just won't be so visually obvious.)
  • With a good UML tool, it's really easy to copy an Activity Diagram to the clipboard, paste it into another diagram, and start adding Swimlanes and rearranging. I have yet to find a UML tool that lets me go from an Activity Diagram to a Sequence Diagram so easily.
  • It's easier to show conditional logic and looping in an Activity Diagram than in a Sequence Diagram. (UML 2.0 improves Sequence Diagrams in this regard significantly; but it's still easier with Activity Diagrams.)

And I see some reasons for preferring Sequence Diagrams:

  • For simple cases, the Sequence Diagram notation is cleaner. This is just my esthetic judgement, of course, but I just find them more readable.
  • A lot of developers are already comfortable with Sequence Diagrams, and less so with Swimlanes.
  • Some good UML tools will let you create new Classes and methods of those Classes directly in the Sequence Diagram. I have yet to find a UML tool that supports Class definition in Activity Diagrams nearly as cleanly.
  • Sequence Diagrams were the first UML diagram where I got the point: "So these things call these other things to do this work. Got it." Yes, this is a very personal reason to prefer them; but I find a lot of developers have the same reaction: Sequence Diagrams just make sense to them.

Which should you choose? That's up to you. My job is to show you techniques, not to tell you what techniques you "must" use. I lean heavily toward Swimlanes these days, but still decide on a case-by-case basis.

Posted on Saturday, November 15, 2008 5:02 PM Ulterior Motive Lounge | Back to top

Comments on this post: Ulterior Motive Lounge Episode 16: The Hunt for Wet October

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © Martin L. Shoemaker | Powered by: