Five Step UML, Step 2: Refine

So let’s begin refining a use case. Select a use case to start with, and attach an activity diagram to it. An activity diagram in UML is similar to old fashioned flow charts. It shows the steps that are performed in a sequence of rules, including decisions that must be made and what you do in response to those decisions. It can also show rules in depth and scoping: how one rule may itself be made up of a much smaller set of rules that play out.

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

Begin creating the activity diagram by adding an initial state: a filled dot which means, “The diagram starts here!” This initial state should tell your readers where to start reading.

Next, you need to start adding the rules that describe the use case’s normal operation. For instance, the rules for checking a book out of a library consist of:

1. Find the book in the catalog.
2. Find the book on the shelves.
3. Confirm that the book has the information you need.
4. Take the book to the librarian desk.
5. Check out the book.
6. Use the book.
7. Return the book.
8. Check the book in.
9. Re-shelve the book.

Similarly, you can break the feature down into a number of steps to be performed. Sometimes, a use case will consist of a single step, but you should always question such use cases: perhaps you just haven’t really thought about steps at the granularity of rules to be performed by actors and the system. When you have the rules, add each rule to the activity diagram as an activity: an icon that looks like a capsule or a hot dog shape, a rectangle with half-circle ends, with the name of the rule or the step inside the activity. Each activity represents one action taken by an actor or an action taken by the system.

To add an activity to an activity diagram in Tablet UML, draw an ellipse. Tablet UML will convert it to a capsule shape.

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

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

And then, in the perfect world, you could just draw transitions from activity to activity, as well as from the initial state to the first activity. But how many of us live in the ideal world? Very few, I suspect. In the real world, things can go wrong: users can provide invalid information; business rules can be violated; accounts can be overdrawn; and so on, and so on, and so on. And an important reason for activity diagram is to capture these exceptional conditions, as well as what we’ll do to handle them. So at every point where we must make a decision whether to follow the rules as written or to do something else, add to the diagram a branch: a diamond symbol that represents the point where a decision must be made. And add a transition from the activity immediately before the branch to the branch itself. In an activity diagram, a transition is an arrow leading from something that has been done to something to be done next. It indicates the flow of the process. In this case, we have an arrow from an activity to a decision which will help us decide which activity to do next. Next, draw a transition from the branch to the next activity in this scenario as we described it so far: the activity that would be next in the rules if nothing went wrong. And then label that transition with a guard condition: a brief message in square brackets which indicates what condition must be true in order for us to follow that transition. And then, to show what could go wrong and what we’ll do about it, add an activity that represents the steps to follow in the exceptional condition; and then add a transition from the branch to that activity, along with another guard condition that explains what condition must be true in order for you to follow the transition to the exception path. And then (if this makes sense within the rules for that error condition) you’re ready to merge back into the main flow of the rules. If that’s the case, you can add a transition arrow from the exception activity back to the next activity that would follow after the exception handling. Perhaps it’s just the next activity in the normal flow, or perhaps you’ll skip that activity, or perhaps there are more steps in processing the exception. It’s even possible that you can’t go on after handling the exception: that you have reached an unrecoverable error and you cannot proceed. In that case, draw a transition from the error handling activity to a final state: a filled circle inside of another circle, or what I like to think of as a target shape. That represents a point at which this diagram is done. You’ll need a final state on the diagram eventually anyway to indicate successful completion; but in this case you’ll use it to indicate an error condition and an error termination.

To add a branch to an activity diagram in Tablet UML, draw a triangle. Tablet UML will convert it to a diamond shape. (You can also try drawing a diamond shape. Sometimes the Tablet PC will recognize it, and sometimes it won't.)

To add a transition, draw an arrow. If Tablet UML has difficulty recognizing your transitions, 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 transition - 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 guard condition to a transition, tap the shaded box near the transition, and a naming window will appear, including a pen input panel. This will allow you write or type the guard condition.

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

To add a final state to an activity diagram, draw a double circle as a single stroke. Tablet UML will convert this to the target shape.

So once you have the rules of your use case, look at every single activity in the diagram and ask, “What could go wrong?” Sometimes the answer will be, “Nothing.” And sometimes, the answer will be, “Well, this could happen…” But very often, the answer will be, “Nothing,” when that’s really not the right answer at all. Often your users are thinking too much about the big picture, and are thinking about the day today details. So part of your job as an analyst will be to probe and question each activity to be sure that you really understand what could go wrong and what to do about it.

And so, once you’ve analyzed each activity for what could go wrong and what you should do in response, you’ll end up with a much more complete activity diagram. You can end up with a diagram which covers many, many steps of a business rule including alternatives and how each one is handled. In fact, you may find that you have too much rich detail on the diagram. You might find that it makes more sense to group some of the activities into larger activities or perhaps even more easily, you may find it easier to take one activity with rich detail, and break it into smaller activities. UML allows these simplifications by allowing an activity to itself contain an activity diagram. So consider ways in which drawing nested activity diagrams or some activity diagrams can help simplify the picture of what the system is supposed to do.

And that is one example of how you can implement Step 2 of the tutorial, Refine. There are other techniques that also work very well with UML: you could use a sequence diagram to capture the requirements instead; or you could use a collaboration diagram; or you could break a use case down into a series of more detailed use cases and use case diagrams; or you could use state diagrams to capture how some part of the system or some part of the problem domain changes as different rules are applied. We already understand from step one how to use case diagrams, so creating use case diagrams at finer granularity will not be particularly different. Sequence diagrams and collaboration diagrams are really better suited to Step 3, Assign, so we won’t investigate those further at this point. But it’s worth discussing state diagrams to see how they can be used to show how the rules change the status of some part of the system. So we’ll look at those as another part of Step 2, Refine.

A state diagram is all about states: a description of the system, or some part of the system, or some object within the domain. A state is a description of the thing that’s being modeled, a description at some point in time of the operation of the system. So for instance an order can have states: it can be new; the customer can adding items the order; the customer can complete the order; it can be in process as workers select the order items and put them in the shipping box; it can be ready to ship; it can be in shipping; it can be delivered; it can be invoiced; it can be due; it can be overdue; it can be in collections; and it can be paid. Each of these states describes what we know about the order of one particular point. We can also have states that describe what some part of the system is doing at a particular point in time. So for instance, we can have the states of a reporting engine: preparing; printing; summarizing, and done. You can see how states describe things and that there are rules that tell how an item changes from one state to another. And those rules are marked by transitions and events. A transition in a state diagram is much like a transition in an activity diagram: it takes the thing from one state to another state. In a state diagram, however, a transition usually only happens in response to some event. In other words, if an order is in the state of “ready to ship”, and then we ship it, a “ship” event has occurred, and the order moves into the shipped state. When the delivery event happens, the order moves into the delivered state. And so on. A state diagram shows how states change from one to another in response to events. And it turns out that a wide range of business rules may be described as transitions of an object from one state to another state.

So another way that we can refine our understanding of the system is to look at the states of some part of the system or of some information maintained within the system. For the most part, it’s easiest to look at the states of individual domain objects. So for this part of refinement of the requirements, select one domain class. For the purposes of this tutorial, you’ll want to look at the states of at least two domain classes so that you can get practice. In a full system, of course, you would want to look at states of all of them. Think about your selected object, and consider the states that it can be in. Consider the different conditions that can be used to describe it. If nothing else, you should be able to come up with at least a small number of states that occur for many different objects: created, in use, and destroyed. Now that is too simple of a state model to be worth drawing as a state diagram. But if you put just those states in a state diagram, then you can start asking your end user about other possible conditions of that object. What are other things that might change about it? What are other things it might do at a given point in time? By asking these questions, you can come up with a richer state model for the object.

So select your class, and attach a state diagram to it. Add to the diagram an initial state, which is a filled circle, just as in an activity diagram. Also add a final state, which is a filled circle inside of the circle, a target shape as in an activity diagram. Then add the states that you know of, such as created, in use, destroyed, etc. A state is drawn as a rounded rectangle with the state name inside. And then draw the transitions from the initial state to the first state, from the last state to the final state, and so on. You can add an event to a transition by writing the name of the event near the transition. And then ask questions to dig out other possible changes, other possible states and conditions, and other possible events. Ask about each of these, find new states where you can, and add them to the diagram. When it seems like there’s nothing more to add, ask about inputs to the diagram. Ask about other events. Ask about things that can happen during the lifetime of this object, along with what the system should do with the object in response. How should the system change? Add in these states and transitions and events as well.

To add a state diagram to a class in Tablet UML, select the class in the model tree, and then click the State Diagram button: .

To add an initial state to a state diagram, draw a circle. Tablet UML will fill the circle.

To add state to a state diagram, draw a rectangle. Tablet UML will convert it to a rounded rectangle.

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

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

To add a transition, draw an arrow. If Tablet UML has difficulty recognizing your transitions, 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 transition - 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 an event to a transition, tap the shaded box near the transition, and a naming window will appear, including a pen input panel. This will allow you write or type the event name.

To add a final state to a state diagram, draw a double circle as a single stroke. Tablet UML will convert this to the target shape.

And then when it seems like you’ve exhausted that avenue of investigation, consider one more style of analysis: build a table with rows representing the states, and with columns representing the events. Then in each state table cell, write the name of the new state that occurs in response to that state and that event, where you know the answer. And then look at each blank cell (where you don’t know the answer), and ask your user, “Can this event ever happened while we’re in this state? If so, what do we do? Do we ignore it? Do we defer it and handle it later? Do we go to some new state, perhaps some error state? Or are we convinced that that event cannot happen while in that state?” This questioning can be tedious, so you’ll have to be patient with your end users. But it’s a very productive way to handle those anomalous combinations that no one ever expects to have happen, but that can cause the worst system breakdowns if they somehow happen anyway and aren’t handled properly. By trying to complete this table and trying to understand much more clearly what events can’t happen when and what events must be processed when they do happen, you end up with a much better model of how each individual domain object behaves.