In my last major entry on the UML I covered the Use Case diagram. The Use Case diagram is a diagram used to gather requirements and help with analysis. Once you have gathered your Use Case diagrams you can continue on with the analysis phase by using Activity Diagrams.

Activity Diagrams are used to illustrate the activities implicit in a use case. For example, consider this Use Case diagram:

This Use Case diagram clearly states that Search Users will Search Content. However, it doesn’t make any attempt to say anything about the steps involved. This is where Activity Diagrams come in.

Activity Diagrams are very similar to standard flow charts. The major difference is that activity diagrams allow for parallel processing of tasks. (In the ColdFusion world you really don’t need to worry about this difference.)

Here is an example Activity Diagram illustrating the Get Out of Bed use case:

This diagram is made up of the following notational elements:

Activities

Activities are used to indicate actions which are preformed in your diagram. In the previous example the activities were: Alarm Goes Off, Hit Snooze, Shut off Alarm and Get Out of Bed. Activities are shaped like pills and have a description inside.

Transitions

The lines with open arrow heads are called Transitions. Transitions are used to indicate the process flow between elements in your diagram. In the Get Out of Bed example above, you can see that the Alarm Goes Off activity transitions to the Sleepy state. There are nine transoms total in the example.

Decision Points

There are two ways to draw logical branching in activity diagrams. The Get Out of Bed example uses a decision point “Still Tired?” If Still Tired? is Yes then the flow transitions to the Hit Snooze activity and then back to the Asleep state. If Still Tired? is No then the flow transitions on to the Shut off Alarm and Get Out of Bed activities.

The text shown in square brackets on transitions out of the decision points is called Guards. For flow to progress through a guarded transition the guard must evaluate to true in the context of the decision point. For example:

This rather simplified diagram illustrates the decisions involved in buying a car. We can see that if we’ve got less than a $100 we’re going to be stuck in a used Yugo. However, as long as we don’t have too much money we’re going to be able to drive a Sensible Car. And, if we happen to have too much money we’re going to end up with a nice sports car.

Guards need to be mutually exclusive. For instance, it wouldn’t make since in the diagram above to show that if we have more than $100 that we’ll buy a sensible car, because that could overlap with Too Much Money guard and we wouldn’t know what to do.

You don’t need to use decision points to show decisions. You can also simply draw multiple guarded transitions out of an activity. Here’s the car buying diagram again, this time without the transition point:

In general, the decision to use Decision Points is up to you. (Frankly, no one seems to use the same conventions in UML diagrams anyhow, so you could probably use pink elephants to indicate decision points, so long as you’re consistent!)

States

States are represented by rounded rectangles. (Sometimes they are segmented like in the examples above, sometimes they’re not. As far as I can tell, there’s no difference.) States are used to indicate milestones in processing of your activity diagrams.

In the example above there are three states, Asleep, Sleepy and Awake. These indicate the “state” of the person being woken up.

Starting State

Start States are a special type of state indicating the starting point for your activity diagram. There can be only one start state on your diagram. Starting States are always drawn as a filled circle. Sometimes people draw a descriptive caption underneath the Starting State. In the Get Out of Bed example we could probably have gotten rid of the Asleep state and called the starting state Asleep instead.

Ending State

Ending States are similar to Starting States; accept that they indicate ending points for processing. The other big difference is that there can be multiple Ending States on your diagram. Ending States are drawn as a filled circle with a ring around it. (It makes me think of Saturn, for some reason.) As with Starting States, sometimes people draw a descriptive caption underneath the Ending State. In the Get Out of Bed example we could probably have gotten rid of the Awake state at the end and called the Ending State Awake instead.

Forks and Joins

Seeing as my audience is primarily ColdFusion programmers, forks and joins probably won’t make much of a difference to you (unless you use ColdFusion MX 7 Enterprise, which now has an asynchronous event gateway). However, for the sake of completeness I will do a brief overview of them.

Forks and Joins are shown as black bars and are used to indicate parallel processing. For an example, look at this diagram:

This diagram illustrates the process of getting in the shower. The diagram starts with the Turn on Shower event. However, the shower always comes on cold and takes a while to warm up, so, for the sake of efficiency, we will fork out and do more than one thing at a time. In our example, while we Brush our Teeth and Shave we are also busily waiting for the water to get warm and happily wasting precious natural resources. When we’re done with all of that, we will join our processes back together and Get in Shower and proceed to play with the Rubber Ducky.

Forks are always shown as a solid bar with one entry transition and multiple exit transitions.

Joins are always shown as a solid bar with multiple entry transitions and a single exit transition.

Swim Lanes

There is one other big notational element to activity diagrams, Swim Lanes. Swim Lanes are used to illustrate which portions of a system are responsible for particular elements of your diagram. Here’s an example:

This diagram illustrates a User and a Website. The user is attempting to log on to the website. As you can see, the User is responsible for providing login credentials, while the Website is responsible for authenticating the user.

One thing about swim lanes which confuses me is where elements like Show Error Message or Show Intranet should be placed. I put them in the User column because the User sees it. However, it’s really the website which performs the action of showing, isn’t it? My opinion is that it doesn’t really matter where these are placed. The purpose is to show that the User and the Website work together to Authenticate the User and Show the Intranet.

Note: The diagram above is interesting too because it shows multiple Ending States, one for success and one for failure.

How to Draw Activity Diagrams

The process for creating activity diagrams is pretty simple. You can accomplish it by following these steps:

1. Identify a Use Case you want to create an Activity Diagram for.
2. Draw a simple Activity Diagram which shows the primary success scenario from beginning to end. Don’t worry too much about details yet.
3. Go back and add in alternative paths through the use case, including those which will result in errors.
4. Add detail to the diagram.

As a note, you might end up with portions of your diagram which are so complex that they warrant an activity diagram. This is part of the point of these diagrams. This level of discovery helps you understand the scope of your software.

Let’s Draw Some Diagrams

In previous entries on UML, I created a requirements document and Use Case diagrams for a searching and indexing API for ColdFusion based on Lucene. I will now use the Use Case Diagrams to create a set of Activity Diagrams.

Search Content

The Search Content Use Case diagram was pretty simple:

I started diagramming by creating a simple Activity diagram which illustrated the primary success scenario.

Now that I have the primary success scenario I need to go back and add some detail. For instance, what happens if I don’t provide any criteria or what happens if the index I’m searching doesn’t exist?

Now that I’ve got a pretty good idea of the flow through the process, I would like to get a better idea of what we’re interacting with. I know I’ve got a Search User and a Search API. I think we could add some swim lanes to help clear this up a bit.

Index Content

The Index Content Use Case will necessitate a bit more complexity in our next Activity Diagram. Here’s the Use Case diagram:

I started by modeling the primary success scenario like this:

This activity diagram does a pretty good job of illustrating the primary success scenario but it does need some more detail. For instance, what happens when the index does not exist? How does the system know where the index is located? What if there are no items in the queue? What if you can’t retrieve the document?

I went ahead and added some detail and some swim lanes to this diagram and this is what I came up with:

By now, you should be able to read this diagram (and I’m tired of typing) so I’ll leave its interpretation to you.

One thing I’ve decided not to cover in this diagram is exactly what information is being indexed and how the information is being extracted from the document. This could easily warrant another activity diagram. However, I have some complex plans for these so I think I’ll leave the implementation details to another type diagram, perhaps a sequence diagram.

Do you have any comments, criticisms or questions on thisentry? If so, please leave feel free to comment below.

Search Engine API Requirements Version 2