Five Step UML, Step 3: Assign

In an activity diagram, we can show parts of the system responsible for particular work by adding swimlanes. A swimlane is simply a column in the activity diagram, with a name at the top designating what part of the system the lane represents. So we can show swimlanes that represent different parts of the system as well as different actors that participate in a given activity diagram. So choose one of your activity diagrams, and add swimlanes to it. You should start with a swimlane for each actor participating in the activity diagram (and therefore in the use case that the activity diagram represents). In addition, you’ll want a swimlane for each user interface that each actor interacts with. So for instance, if the use case is create new user account, then you would have a swimlane for some sort of new user account “form”, whether that’s a web form a desktop form or even a voice input system. And then, when you have some swimlanes defined, you need to start assigning the different steps in the activity diagram to particular swimlanes. So you simply redraw the activities in the corresponding swimlanes; or, if your tool allows it, drag each activity into the appropriate swimlane. When you do this, sometimes you can be confused about where to put a particular activity. For instance, if an activity is something that a user does, but the user does it through a user interface form, does that activity belong to the user or to the form? The simplest answer is: when in doubt, it belongs to the form. Why? Because we’re trying to design the behavior of the system. If there is any way in which the system can be taking part in the activity, than we want activity to be in the system’s swimlane. Putting activities in the user’s swimlane doesn’t help us much in terms of designing the system. So if it seems to be a shared activity, then put it in a swimlane for the system. Only if it’s entirely a user activity should you put it into the swimelane for the actor or user. So for instance, if you have a activity which consists of “Decide which type of account to set up,” the system would not have any part in that decision. That would be a good activity to put into the user swim line. It’s also a good idea to put the initial state of the activity diagram in the user swimlane because the user initiates the activity diagram.

You may want to preserve your original activity diagram (since it's a good, simple description of your business rules) and dd your swimlanes to a copy. The easiest way to do this in Tablet UML is via the clipboard. Switch to selection mode and select all of the diagram elements, then selecy Copy from the Edit menu. Then create a new activity diagram and select Paste from the Edit menu. And now you're ready to add swimlanes.

To add a swimlane to an activity diagram in Tablet UML, draw a long vertical line. Tablet UML will convert it to a swimlane.

To name the swimlane, tap on the name, and a naming window will appear, including a pen input panel. This will allow you write or type the swimlane name.

(You may also select another content editing mode to edit the name directly within the diagram.)

As you move activities into the swimlanes, you may discover implied swimlanes. So far, we have only discussed swimlanes that represent the actors or the user interfaces. But some decisions and some activities will take place deeper in the system then at the user interface level. In other words, unless you want to build a monolithic application which encompasses user interface and business logic and data persistence and perhaps other services, you will want to separate responsibility. Presentation of information to the user should be separate from implementation of business rules, which should be separate from the persistence of data that supports those rules. So as you work through the business rules, you’ll find activities that do not belong either to an actor or to a user interface. When you do, it’s time to add new swimlanes. These swimlanes will represent these deeper parts of the system, these layers or tiers. So add swimlanes for these, and then name them. Now the question becomes: what do you name them? My practice is to name them as interfaces: sets of related services that will be provided by some code within the system, although we may not have yet decided what code. My goal is to identify related services, but not to identify pieces of the system– at least, not quite yet. So for instance, if I am diagramming various activities with a customer account, then I’ll probably end up with a swimlane for the IAccount interface. If I am doing work involving credit card authorization, I might have an ICredit interface. If I am sending out e-mail messages, I might have an IMail interface. And so on. My goal is to identify useful groups of services within the architecture that will have to be provided by some part of the system.

I may also find that as I assign activities to swimlanes and start getting a little closer to a system implementation of the business rules, there are activities that were implied by the business rules but that were never actually stated there. Why are these implied activities missing? Is this because of an incomplete or improper analysis? Not at all! Rather, it’s that a description of rules from a user’s perspective will not always indicate necessary steps from an implementation perspective. But as we start to assign to parts to the system, we start getting closer to implementation; and thus the lack of these activities starts to become clear.

And so, you may want to revise the activity diagrams to reflect these additional activities and the swimlanes where they take place. For instance, you might have an activity which says, “Customer submits payment information.” And then you might have a branch with two transitions coming out: one with the guard condition, “[Sufficient funds]”; and one with the guard condition, “[Insufficient funds]”. But nowhere in that description of the business rules have we actually checked whether sufficient funds were available. That step was implied in the business rules in order to answer the question we had to ask that question. Well, when you write code, nothing can be implied. It must be specified. So I would add a new activity, “Check for available funds”. And after that activity would come the branch depending on whether sufficient funds were available are not. So looking at your activity diagram, look for these implied activities. And if we found before that some of our business rules needed to live in not user interface swimlanes, well, most of the implied activities will be part of non-user interface swimlanes.

Some of the implied activities will represent "calls" from one swimlane to another. Usually, when the diagram transitions from activity A to activity B, control cannot "return" to A along the same transition. A transition is one-way. But sometimes I want to show that one activity calls another to do some work, and then continues working based on the result. This is one example where I like to use a UML stereotype, which is a mechanism for extending UML to cover new concepts. You can decorate an existing UML element with a stereotype (shown in <<double angle brackets>>) to carry some extra meaning that you define. In this particular instance, I use the <<call>> stereotype to indicate a transition that leads from one activity to another, waits for that activity to complete, and then returns to complete the initial activity.

And then, when we have identified implied activities and added them to the corresponding swimlanes and perhaps even added new swimlanes to support them, we need to check the new diagram against the old diagram, and ensure that all of the transitions and basic flow from the old diagram are still represented within the new diagram. (This is this is another advantage of a good modeling tool: a modeling tool should let you just move the activities, and it will be responsible for keeping the transitions connected properly.) Once you have all of the activities in swimlanes and all the transitions still reflect the business rules as originally specified, you have assigned all of the steps of this activity to parts of the system. And once you do this with every activity diagram for every use case, you should know – to go to a very close degree – all of the user interfaces and all of the interfaces that will comprise the system.

Now let’s talk about sequence diagrams. A sequence diagram is one of the oldest diagrams in UML. It consists of objects that participate in some sequence of steps that take place over time. The objects are arranged horizontally across the page, and time of flows down the page. An object has an existence within the diagram. It might exist before the diagram even began, and it might continue to exist after the diagram is complete; but it’s also true that a particular object might get created within the diagram or destroyed within the diagram. So to show the existence of the objects within the diagram over time (which again flows down the page), we add a lifeline: a dashed line that descends down the page from the object, either for the duration of the lifetime of the object or all the way to the bottom if the object exists beyond the end of the diagram. If an object is created within the diagram at a particular point in time, we indicate that by placing the object’s icon at that point vertically within the page. If an object is destroyed within the diagram, we indicate that by stopping its lifeline at the point where the object is destroyed and placing an X at the end of the lifeline.

To add a sequence diagram to a use case in Tablet UML, select the use case in the model tree, and then click the Sequence Diagram button: .

To add an object to a sequence diagram, draw a rectangle. Tablet UML will convert it to an object, and will automatically attach a lifeline to it.

To name the object, tap on the name, and a naming window will appear, including a pen input panel. This will allow you write or type the object name.

(You may also select another content editing mode to edit the name directly within the diagram.)

So now, we have a notation for indicating the existence of objects within the span of time represented by a sequence diagram. The next thing we need in our sequence diagrams is a notation for indicating that an object is active for a particular length of time: either it is doing some work, or it has requested some work and is waiting for the response. We indicate that an object is active for a period of time by drawing a box on its lifeline corresponding to that period of time. We call this box an activation (sometimes also called a focus of control). And usually, messages from one object to another actually are from one focus of control on one object to another focus of control on another object (or sometimes on the same object, when an object calls its own operations).

To add an activation to a sequence diagram in Tablet UML, draw a line that overlaps a lifeline. For very short activations, you may need to draw an up-down or down-up gesture.

If your Tablet PC pen has a barrel button, there's an even easier way to ensure that Tablet UML recognizes what you draw: hold down the barrel button as you draw. When you lift the Tablet PC pen, the recognition menu will appear, and will let you decide how to recognize what you drew.

To name the message, tap the shaded box near the message arrow, and a naming window will appear, including a pen input panel. This will allow you write or type the message name.

(You may also select another content editing mode to edit the name directly within the diagram.)

And so, we now have all of the pieces necessary to show the collaboration of a number of objects in carrying out a set of steps for some business rules. Now you may find that it’s difficult to show any sort of logic and loops within this diagram as you might in an activity diagram with swimlanes. In fact, you may quickly suspect that this shows you very much the same information as in an activity diagram, just with a different notation. This is very true. The activity diagram notation and especially the swimlanes within the activity diagram are fairly recent addition to UML, and are somewhat redundant with the preexisting sequence diagram notation. Each diagram has strengths and weaknesses. Each diagram conveys certain things very well and others not so well. And most important, each diagram makes more sense to certain kinds of readers and less sense to others. And no, I can’t tell you which kinds of readers comprehend a given diagram type more easily, because I haven’t been able to categorize them. But I know it’s true: some readers can really understand activity diagrams with swimlanes, but are completely confused by sequence diagrams; while other readers see sequence diagrams as a very clear picture of cooperation between parts of the system, but find that the activity diagrams with swimlanes are cluttered and make it less easy to read the same information. So I encourage you to try both and see what works best for you.

 There’s yet another route to show this sort of collaboration of parts to carry out a set of business rules. In fact, it’s called the collaboration diagram. And the interesting thing is, a collaboration diagram is virtually identical in contents to a sequence diagram, but once again, some readers find it more readable than a sequence diagram and others find it less so.

To create a collaboration diagram, you add objects to the page. And then, wherever two objects have to send messages and responses back and forth, you draw a collaboration: a line that connects them. If there’s no line, no messages can pass between those two objects. So, you need to add objects to the diagram. One fairly simple approach assumes you have already drawn a sequence diagram. In that case, simply look at the sequence diagram and add all of the objects from the sequence diagram to the collaboration diagram. Then, looking at the sequence diagram, find each message from one object to another as; and where a message exists, add a collaboration between those two objects. And finally, we need the missing piece of our collaboration diagram notation: the messages. These are simply arrows that run parallel to the collaborations and point from the requester to the requested object. You can look at the messages in a sequence diagram and create them in a collaboration diagram just as originally written; but you may also want to number the messages so that you can more easily see the order in which the operations take place.

To add a collaboration diagram to a use case in Tablet UML, select the use case in the model tree, and then click the Collaboration Diagram button: .

To add an object to a collaboration diagram, draw a rectangle. Tablet UML will convert it to an object.

To name the object, tap on the name, and a naming window will appear, including a pen input panel. This will allow you write or type the object name.

(You may also select another content editing mode to edit the name directly within the diagram.)

To add a collaboration to a collaboration diagram, draw a line connecting two objects. If Tablet UML has difficulty recognizing your collaborations, it may be because the Tablet PC API doesn't recognize diagonal lines, only horizontal or vertical. You should try to draw connectors in Tablet UML as close to horizontal or vertical as possible. But if a collaboration - or anything in a diagram - isn't recognized, you can manually recognize it. Switch to selection mode; select the item; and select the right element type from the manual recognition dropdown list.

You can also perform a manual recognition without switching modes. You can do this via the context menu. Right-click the stroke that you want to recognize, and a menu of possible element types will appear. If your Tablet PC pen does not have a barrel button, you can "right-click" via the press-and-hold gesture. If your Tablet PC pen does have a barrel button, you can "right-click" by holding down the barrel button as you tap the screen. (See your Tablet PC help for details on how to "right-click" with a pen.)

If your Tablet PC pen has a barrel button, there's an even easier way to ensure that Tablet UML recognizes what you draw: hold down the barrel button as you draw. When you lift the Tablet PC pen, the recognition menu will appear, and will let you decide how to recognize what you drew.

To add a message to a collaboration diagram in Tablet UML, draw an arrow. Unlike arrows in other UML diagrams, these arrows are not connectors. They run parallell to collaborations, but they don't directly connect objects.

Well, that’s the easy way to draw collaboration diagrams; but of course, it requires that you have already drawn a sequence diagram. What if you don’t have a sequence diagram? How then you know which objects and messages to show in your collaboration diagram? In fact we never really address the question: how do you know what objects and messages to show in a sequence diagram? Well, I think that for both diagram types, the process is very much the same as we talked about with activity diagrams: add objects that represent actors that use the system, add objects that represent the user interfaces that users interact with, and as you go along add objects that represent back and services that are required by the user interface to carry out its work. And what messages to add? Messages that represent the business rules that are being performed through the user interface, and messages that represent things which are not necessarily performed by the user interface directly, and messages that represent tasks that are implied by the business rules from an implementation perspective but never stated directly in the rules. In essence, I think the same basic design fought and architecture thought is required for each of the three diagram types.

So now, we have three different approaches for how you show assignment of the business rules to parts of the system, along with elaborations of those rules to get closer to implementation requirements. Which one should you choose? That’s largely a matter of preference. I will pretty much always choose the activity diagrams with the swimlanes. Others who are very familiar with sequence diagrams will gravitate towards those. And still others find the collaboration diagrams are much clearer for them to comprehend. So I think it’s worthwhile for you to know all three types and how to create them and how to read them, so that you can always create one from another if that helps your audience to understand what you’re saying.

Now there’s one other kind of information which we gathered in Step 2, Refine. That was the information about what states different domain objects can pass through. So now, we want to reflect how those states are assigned two parts of the system. A very simple way to do this is to assign in each state to some user interface or interface. Now perhaps you can assign an entire object to a user interface or interface. That’s quite fine when you can do it. But you may also find that some states of a given object reside within different interfaces. How do you indicate a given state is contained within a given interface or user interface? Well, the simplest way is to document this in the model, in the documentation for each particular state.