UML: Use Case Diagrams Revisited

This entry is a continuation of my series on learning the UML. This entry follows up on my recent entry on Use Case Diagrams.

---

Shortly after posting my entry on Use Case diagrams I received an email from Doug Keen saying that I might have gotten a few things wrong. I expected this. He made some interesting point and I went and read some more on Use Case Diagrams.

Doug’s criticism was primarily that I show too much “sequence” in the Use Case diagrams I wrote. After considering this and reading more I think he might be right.

I noted in my last entry that when I wrote my requirements document that I had some preconceived notions which made it into the requirements document. These preconceived notions were mostly functional in nature. For instance, I listed a number of “users” of the Search API I’m designing:

• Search User
• Queue Manager
• Content Retriever
• Content Inspector
• Index Manager

Before writing my blog entry on requirements gathering and use case diagrams, I had been reading about use case diagrams and thinking about what would appear in one for my search API. After thinking for several days I went back and wrote my requirements document. However, I don’t think I did a very good job actually defining requirements.

Consider this: Why am I placing design-related information in my requirements document?

In my entry on requirements gathering I state that the resulting document focuses on the following items:

• The business process which will be modeled by the application
• The user and systems which will use and interact the new application
• The resources which the system depends on and creates
• The functionality of the system as related to the first three items.

Considering those bullet points, where does “Queue Manager” fit it?

I thought that the Queue Manager was a user although I knew it was part of the system. In the end I think this might be wrong. By defining the Queue Manager (and other system users) during the requirements gathering phase, I boxed myself into a particular design before even beginning the design process.

This might mean that my API only has two users:

• The user which invokes the indexing process
  • I’ll call this the Index Invoker, for lack of a better name
• The user who searches for content
  • I’ll call this the Search User.

This makes since. I’m not really designing a system, I’m designing an API. The API is a small set of functionality which will be integrated into a larger system.

At the moment I don’t have time to update my requirements document. I’ll do it as soon as I can.

By changing the users, I change the structure of my Use Case diagrams. I think that my Search Index Use Case Diagram might end up being as simple as this:

This very eloquently describes the functionality the Search User will use.

The Index Content Use Case diagram might look like this:

This new version does a pretty good job of explaining the system from the user perspective.

What do you think? Do we need to revisit this again?

UML: Use Case Diagrams

This entry is a continuation of my series on learning the UML. This entry covers Use Case Diagrams. This entry builds on top of my entry on requirements gathering which was posted last week. I will be using the requirements document created for that entry to build use case diagrams. You may wish to review that entry.

---

The Use Case Diagram

Use Case diagrams areUML: Use Case Diagrams the first stop when designing an application using UML. Use Case diagrams illustrate your system requirements in terms of system users and the actions they perform. Use Case diagrams build on to your requirements document and are intended to be readable by both technical and non-technical people. In other words, you should be able to show your Use Case diagrams to your client or boss and they should be able to glean a high level understanding of how users interact with the system.

Uses Case diagrams are used to analyze and illustrate the functionality of the system. They show the process flow the steps taken by users to perform a specific function.

Use Case diagrams are also frequently used to illustrate test cases for quality assurance. Because Use Case diagrams are so effective in illustrating process flow they are also very effective in validating that a process flow works correctly.

The Scope of Use Cases

Typically there are several Use Case diagrams for a system. Each Use Case diagram focuses on one functional objective of the system. For smaller systems you may have only a few Use Case diagrams. For a complex system made up of multiple subsystems you may have a much larger number of diagrams.

Use Case diagrams illustrate how the users and a system work together, or interface, to accomplish a specific goal. As a result, a Use Case diagram tends to treat the system like a black box. You shouldn’t care about what’s going on under the hood, only what the user is doing though their interface into the system.

The Anatomy of a Use Case Diagram

Let’s jump in head’s first and take a look at a simple Use Case diagram.

This use case demonstrates the three basic components of a Use Case diagram.

• Actors
• Use Cases
• Relationships

Many UML diagrams also include a construct known as the system. Systems denote the borders of your system. These are not required and I will not be addressing them.

Actors

Actors represent something which interacts with the system. Actors can represent people or other systems.

Actors do not represent individual people. Actors represent a role a person or system fills. For instance, Stock Clerk, Teacher and Cache Manager are all reasonably good Actor names. Imagine how hard it would be to identify each individual who would ever use the system! You can’t, so don’t bother! Just remember to identify actors based on their role.

In Use Case diagrams Actors are depicted as a stick figure. The Actor’s name is shown below the actor. Sometimes actors are depicted using the classifier notation from Class Diagrams.

The illustration above shows the two actors from our example Use Case Diagram. The Search User Actor is shown as the typical stick figure. The Index Searcher Actor is being depicted using the classifier notation. When shown this way the text “<<actor>>” is shown above the Actor’s name. (The “<<” and “>>” marks are called guillemets.)

Use Cases

A Use Case diagram would be pretty useless without having Use Cases. (No pun intended.) A Use Case is an action an Actor takes on the system. Usually, Use Cases are composed of a verb and a noun. The Actor performs the verb on the noun. For instance, your actor might perform the Use Case “Run down street” or “Jump over shark”.

Use Cases can be created with any level of granularity. They can be extremely specific to the point where one Use Case is one step. Use Cases can also be more general and require multiple steps to complete.

A Use Case is displayed as text inside an oval. Sometimes Use Cases are shown as ovals with text below them.

The three Use Cases above are from the example Use Case diagram. As you can see, they all specify an action an Actor can take on the system.

Relationships

Relationships are the simplest element to draw. Despite their simplicity, relationships are what tie the diagram together. Relationships indicate associations between actors and Use Cases.

In the example diagram above we see that a Search User provides search criteria. Additionally, the Search User is involved in the Return Search Results use case. Based on the diagram, we can tell that the Search User does not identify matching content.

The Index Searcher is involved with the provided search criteria. The Index Searcher identifies matching content and returns the search results.

Relationships are simply drawn as lines between Actors and Use Cases.

In this example the relationship is the line drawn between the Driver actor and the Drive Car Use Case. By reading this we know the Driver can drive the car.

Advanced Relationships

Use Case diagrams have another set of relationships which add detail to your diagrams by explaining more specific types of relationships.

• Generalizations
• Includes
• Extends

Generalizations

A Generalization is a type of relationship where one Actor or Use Case is a more generalized version of other Actors or Use Cases. If you were to think of a Generalization relationship in terms of classes or ColdFusion components, Generalization would represent an “extends” relationship where a set of classes extend a super class. Each of the extending classes inherits all of the methods and properties of the super class. The super class is a generalization of the extending classes.

The example above shows a Doctor, Lawyer, and Programmer. All of these actors are Professionals. The Professional actor is a generalization of the other three actors. I tend to think of Generalization as an “Is a…” relationship.

The next example shows that generalizations can also be used with Use Cases.

This diagram states that the Index Word Doc, Index HTML and Index PDF Use Cases all extend the Index Text use case. They all perform the same function as Index Text, but with their own specific extensions.

Generalizations are drawn as a solid line with a hollow triangular arrow. The arrow is drawn pointing towards the Generalization.

Includes

An Includes relationship is used to indicate that a particular Use Case must include another use case to perform its function. The following example illustrates an Includes relationship.

This example illustrates a bank’s Account Holder withdrawing cash. The Withdraw Cash Use Case can not be preformed without debiting the Account Holder’s account. Potentially, the Debit Account Use Case could be reused elsewhere.

An Includes relationship is drawn as a dashed line with an open arrow head. The arrowhead points at the Use Case being included. Along the line somewhere is placed the text “<<include>>”, surrounded in guillemets.

Extends

When getting started with Use Cases I had a really hard time understanding the difference between a Generalization relationship and an Extends relationship. This was especially hard for me because the Generalization relationship illustrates what would programmatically be one class extending another. In a Use Case Diagram an Extends relationship is a different concept!

An Extends relationship is exactly like an Includes relationship with one important difference: An Extends relationship is a conditional include. For example consider the following diagram.

This diagram shows that an Employee does work. A Manager, which is a type of employee, also does work. Conditionally, the manager can give the Employee a raise.

One problem with this diagram is that we can’t easily tell why the manager might give the Employee a raise. To clarify this, Use Cases have an additional type of nation known as extension points. Here is the same diagram with an extension point drawn in.

This extension point indicates the circumstances when the Extending Use Case will be performed. In this example the manager will give the employee a raise when they do good work.

An Extends relationship is drawn as a dashed line with an open arrow head. Unlike an Includes relationships which point at the Use Case being included, an Extends relationship points at the Use Case which conditionally includes the other Use Case. Along the line somewhere is placed “<<extend>>”, surrounded in guillemets. In the diagram above, the open arrow head is shown pointing at the Do Work Use Case which conditionally includes the Give Employee Raise Use Case.

Extension points are draw by bisecting the extending Use Case oval with a horizontal line. The Use Case name goes on the top segment of the oval. The Extension points are listed in the bottom half under the phrase “Extension Points” which is shown in bold.

As a note, while researching this entry I saw a number of different styles of notation for Extends relationships. Many of the examples I saw blurred the line between Generalizations and Extends. Both styles are perfectly valid. I am blogging on how I do mine. You’re welcome to apply any style you want, so long as your diagrams communicate your purpose effectively.

Let’s Create Our Use Case Diagrams

One of the purposes of this series on UML is to apply UML in the real world. As a part of this, I am using the lessons learned to design a search engine API for ColdFusion around the Lucene search engine libraries. In a previous blog entry I created a requirements document which I will now use to create a set of Use Case Diagrams. Follow this link to read the requirements document in PDF format.

Note: I am creating all of my UML diagrams using the Community Edition of Gentleware’s Poseidon for UML software.

Skipping to the Business Requirements section of my requirements document, I see that there are two business processes identified, Index Content and Search Content.

The Index Content Use Case Diagram

The requirements document describes the business process of indexing content. The description states that the system will use a queue to identify what content to index. The system will then get the content and extract important data from it. The extracted data is then passed to the indexer which indexes it.

For my first attempt I’m going to draw out what this sounds like.

I may have been getting ahead of myself when I wrote the requirements document. It identifies a few other system users, meaning users which are part of the system. These system users are Content Queue, Content Retriever, Content Inspector, and Indexer. I had actors in mind when I identified them, which might be right and might be wrong.

The Content Queue is supposed to be responsible for identifying what content to index. Let’s add this actor to our diagram and see what happens. I think the results should end up looking like this:

The Content Retriever is supposed to be responsible for getting the content to index. As a note, the Search API should be able to get files on the web as well as files on disk.

I just realized that this isn’t covered in my requirements document! I found an omission! I’ll update my requirements document and then update my use case diagram.

I also see a Content Inspector object which is responsible for interpreting the content and extracting portions of the content to be indexed. For instance, in a HTML document it would extract the plain text of the document and links to other documents.

Because content can be retrieved from the web or from disk I added two use cases which extended the Retrieve the Content use case. Retrieving the content from the web or from disk are both types of content retrieval.

The Content Inspector extracts data from the content. It has to extract the title, plain text, links and summary of the content. Because it can’t perform its function without the support of other Use Cases, I’ve added four includes relationships.

After one more review of the requirements document I found some more information. The next diagram is my first completed version of the Indexing Content Use Case Diagram.

I changed the name of the Content Queue and the Indexer to the Queue Manager and Index Manager, respectively. As I was working on the Use Case diagram I realized that these two actors had more responsibilities than I initially thought. The Queue Manager is responsible for adding addresses into the queue and working with the queue data. The Index Manager doesn’t really do the indexing, Luncene does. The Index Manager is responsible for adding, inserting, updating and deleting content using Lucene.

I also added a number of extension points to the Index Content use case which take care of situations where the Index does not exist, updating content in the index, and adding content into the index. I also added an extension to the Index Manager which deletes content in the case that it’s deemed permanently inaccessible.

I made some changes to how the Queue Manager works too. The Queue Manager is responsible for creating the Queue if it doesn’t exist. This process also needs to identify the first item to index. The requirements document also indicated that the Queue Manager could be told what to get from the queue. Because of this I changed the name of the use case to Identify content. It has an extension which creates the queue when it doesn’t exist. This extension includes the Identify default item use case so that the Queue Manager always has something to work with.

I also added a use case where the Queue Manager adds links extracted from the content to the index. I’m not sure if I’m happy with this, but it will do for now. I can revise this if it’s not correct.

One thing which is not yet addressed in this use case is what happens if the content is temporarily inaccessible. For now, I think this is fine. I should catch this in future updates. Furthermore, the Use Case document should be focused on the main success scenario.

The Search Content Use Case Diagram

The Searching Content Use Case diagram should be a lot simpler than the Index Content Use Case Diagram. The requirements document specifies that the user provides search criteria, the system identifies matches in the index and returns them to the search user. One import note is that this is an API.

The Search User is not really a person, but is a system implementing the API. The implementing system could be ferrying requests to the search system from a web form, Flash, web services, SMS or anything. Given that, I think my two actors will be Search Implementer and Index Manager. The Index Manager is the same actor from the Index Content Use Case.

The resulting Use Case indicates that the Search Implementer provides search criteria to the Index Manager. The Index Manager identifies matching content, presumably by querying Lucene. The resulting matches are return by the Index Manager to the Search Implementer.

There are a few scenarios listed in the requirements document which describe possible negative outcomes. I’m not going to address these now. I’m most interested in the main success scenario. These other outcomes will be addressed in future documents.

Conclusion

Now that we’ve completed this exercise we have a pretty good idea of who the users of the system are and the functionality provided by the system. The Use Cases are clear enough that non technical users can read them with a little coaching.

In all honesty, the Index Content use case might make a few too many assumptions. When writing the requirements document I had some preconceived notions which I was working towards. This might have shaped my approach more than I would like. Time will tell if I got this right.

Our design probably still has some problems. We should expect that. As we move into the next phases of architecture we should be able to uncover some of these. Remember that design is iterative. As you move forward in your design you will learn new things which should then be integrated into previous documents.

One key way in which our Use Case diagram was a success is that the system has remained a black box. We don’t know what the system does behind the scenes. All we know is who the actors are and what they expect from the system. We will figure out how the system will meet these expectations before long.

While working though this process I discovered a number of errors, typos, and omissions in my requirements document. I have now updated the requirements document and created a new version. The new version can be downloaded below. If nothing else, the process of creating the Use Case Diagrams helped us clean up the project requirements.

Alagad Captcha Component 1.1 Released

An update to the Alagad Captcha Component has been released with several new and frequently requested enhancements. The update adds the following methods:

setAllowedFontList() – This method was added to create a white list of allowed fonts. It is intended to replace setIgnoredFontList() which has been deprecated.

getAllowedFontList() – Returns the list of allowed fonts.

setContrast() – This can be used to adjust the amount of contrast between background and foreground colors. This can be used to make the Captcha images easier to read.

getContrast() – This returns the contrast setting.

setSpotsEnabled() – This method can be used to control whether spots are shown in the Captcha image.

getSpotsEnabled() – This method returns the spots setting.

setInvert() – This method can be used to invert the image so that dark text is drawn on a light background.

getInvert() – This method returns the invert setting.

Also of note is that support for Blue Dragon has been removed.

To download the latest version, please visit http://www.alagad.com/index.cfm/name-captcha.

Alagad Image Component – Auf Deutsch

A kindly Austrian by the name of Rainer from Telezentrum Mostviertel & Kaufmann KEG has created a page which lists all of the Alagad Image Component 2.0 methods and their description in German.

Those of you who think in German might find this of use.

If anyone other there wants to create wrapper classes for the Image Component in their native languages I’ll give you a license or two for doing so. Contact me for more information.

Powered By Dougtroit

I will be presenting at Powered By Detroit! I’m excited to say that this is the first conference I’ve been asked to speak at. I’ve presented at ColdFusion and Macromedia User Groups, but never at a full fledged conference. I feel so… important! Either that, or the PBD guys had a 9:00 am slot to fill on the first day.

My presentation is entitled “CFC Crash Course” and it is a head-first introduction to ColdFusion Components. It covers everything from how to write and use a CFC, to variable scooping, tips, tricks, and more. I never really realized how much there is to know about CFCs till I started writing this. I even took lengths to avoid getting into object oriented techniques at all. I touch on the idea of encapsulation and show how to extend CFCs but I never even mention polymorphism.

Any how, I’m quite excited to be going to this and to be presenting too! I was hoping that I would sponsor it too. I was planning on getting a booth and bisecting it with a strip of tape. One half of my booth would have been Doug Hughes and doughughes.net. The other half would have been Alagad specific. The PBD sponsor rates were very affordable. Unfortunately I just didn’t have enough time to get everything prepared and the printing costs would have added up quickly. I’ll probably do this next year.

I’m not sure if there will be a raffle on the last day like at CFUN. However, if I remember, I’ll see that there are a few free licenses for the Image Component and Captcha in the mix.

Another thing that’s got me geeked about this is that I used to live up in Michigan (in East Lansing). My wife’s family lives in the Ann Arbor area. We’ve been considering moving back up to Michigan for a while now. I’m hoping to meet some native Michigan ColdFusion coders and business owners. Who knows what will happen. If nothing else, it will be good to get a feel for the industry up there.

I hope to see you there!

Alagad Image Component 2.13 Released

This release of the Alagad Image Component addresses a bug in Image Compression. The Image Component now produces smaller files when using JPEG compression.

This update is free to all licensed users if the Alagad Image Component 2.0.

The latest version of the Alagad Image Component can be downloaded at http://www.alagad.com/index.cfm/name-aic

Also, all versions of the Image Component support the newly released ColdFusion MX 7.

Acquire Your Requirements

Before one can begin building an application one has to know what it is that the application needs to do. This sounds like a simple idea, but it’s really not. Take a look at my old entry on why software projects fail and you will see that the first reason listed is &quot;Project Requirements are Poorly Defined&quot;.

Many failed projects start out with great intentions. Perhaps a developer, manager, business analyst or executive comes up with a brilliant idea. Immediately, a developer, or a whole team of developers, is called into an emergency meeting and a brain storm session ensues. In this session ideas fly widely! Proposals are proposed! Considerations are considered! Ideas are thought out, planned, sliced, diced and dissected. A new application, website, component or whatnot is conceived. Then, when the orgy is completed, everyone stumbles out of the conference room, feeling a little dazed, strung out and worse for wear.

But the ideas! Oh, the ideas!

Three weeks later the team is reassembled for a demonstration of the new application, website, component or whatnot. But, the afterglow is gone. The orgy of ideas has turned into a nettlesome collection of preconceived notions. The product which is demonstrated does not do what anyone expected it to! How can that be? Everyone agreed on what the project would be, didn’t they? Well, let’s check the requirements document&hellip;

Wait a second; we don’t have a requirements document!

Oh yes we do! The developers took notes!

Notes?! Did someone sign off on the notes?

It turns out that, no, no one signed off on the notes. And even if they did, the notes were composed entirely of these words:

Build a new application, website, component or whatnot with a bunch of wiz-bang features.

Has this ever happened to you? I expect so. The question then beckons, what can you do about this?

The answer lies in requirements gathering. I have a simple forms application I wrote which I work though when gathering requirements. The form focuses on the following items:

• The business process which will be modeled by the application
• The user and systems which will use and interact the new application
• The resources which the system depends on and creates
• The functionality of the system as related to the first three items.

At some unspecified point in the future I will release this application for free. I can’t do that at the moment. As a substitute I will provide the questions on this form.

Before we get to that point, consider that a requirements document is fluid and should feed the design and architecture phase of development. I prefer an iterative technique where each iteration builds on top of work completed in previous iterations. On each iteration you should revisit the requirements document. You will want to adjust it to incorporate new requirements and update it for the next iteration’s requirements.

You may also want to consider keeping versioned numbers of the document. The version number might correspond to the latest change requirements. You can also refer your clients to specific versions of the document when they have questions. Lastly, your clients should sign off on the requirements for each version of the document.

The requirements document also feeds right into the first phases of architecture. The first steps into a UML diagramming tend to be though Use Case and Class diagrams. Your requirements document will help you better identify your use cases and actors which lead into modeling classes and then into other portions of UML.

Without further ado, here are the questions I use when creating my requirements documents:

General What is the project name? Provide a document version number. Quickly describe the business process which will be modeled or replaced. Business Process Identify major portions of the business process. For each, answer the following questions. Name this major portion of the business process. Describe this major portion of the current existing business process. What are the goals of this process? System Users Identify the system users and roles. These may be people, systems, devices, etc. These are classifications of people and not individuals. For each user or role answer the following questions. General System User Info Identify the user or role. Identify the type of user or role (person, system, device, etc). Description Describe the user or role. Responsibilities Describe the user or role’s responsibilities. What are the user or role’s responsibilities? Do may people share the same set of responsibilities with this user or role? How do this user or role’s responsibilities different from others? Constraints Describe any unchangeable constraints which affect how this user or role performs their responsibilities. For example: Are there any legal, contractual or regulatory restrictions on how this user or role does their job? What authority or access rights are required to do this job? Rules Describe any existing rules, policies or procedures which determine how the user or role does their job. Resources What information or resources is this user or role dependant upon? For example: What resources does the user or role acquire and dispose of? What information does the user or role rely on to do their job? What information is the user or role responsible for (approving, acquiring, requisitioning) Performance Describe any system performance related considerations for the user/role. For example: How many of this user or role will need to use the system? How many of this user or role will concurrently access the system? How slow can the system be before affecting the user or role’s ability to perform their responsibilities? Resources Identify resources, information, or data which the system will rely on. Refer to the resources section under system users for examples to draw from. For each resource answer the following questions. General Resource Info Identify the resource. Describe the resource. Constraints Describe any unchangeable constraints on this resource. For example, legal, contractual, or regulatory constraints. What restrictions influence the acquisition of the resource? Are there any legal or contractual constraints on how the resource is used? Rules Describe any existing rules, policies or procedures which affect this resource. What level of authority is required or who is allowed to use the resource? What policies govern the use of this resource? Performance Describe any performance related considerations with this resource. How much time is allowed for transactions using this resource? Does the quantity of the resource affect the system’s ability to process it? Functionality Identify the functional portions of the system. Review the user section for inspiration. For each piece of functionality answer the following questions. General Identify the functionality Description Describe the business process requirements for this element of functionality. Describe why a user needs the system to have this functionality. What do users expect to happen when this functionality is used? What happens if this functionality does not work? What are the possible outcomes for this functionality? Which users/roles use this functionality? If different users/roles use this functionality, do they do it for the same reasons? Constraints Describe any unchangeable constraints on this functionality. For example, legal, contractual, or regulatory constraints. What restrictions influence the use of the functionality? Are there any legal or contractual constraints on how the functionality is used? Rules Describe any existing rules, policies or procedures which affect this functionality. What level of authority is required or who is allowed to use the functionality? What policies govern the use of this functionality? Performance Describe any performance related considerations with this functionality. How much time is allowed for transactions using this functionality? Does the quantity of the functionality affect the system’s ability to process it? Signoffs

To clarify the difference between constraints and rules, think of constraints as unchangeable while rules are agreed upon ways of working. For example a tightrope walker can agree to use a net but can not change the law of gravity. The law of gravity is an unchangeable constraint. The use of a net is an agreed upon way of working and is changeable.

I have an example requirements document I wrote for the ongoing UML entries I’ve been adding. The requirements document is for a Search System API based around the Lucene search engine. The document can be downloaded in the attachments section below. Because this is merely for internal development I have not added a version number or a signoff.

I will be following this entry with another entry on UML use case diagrams.

What’s your strategy for requirements gathering?