UML seems like a tried and true candidate for building artifacts that can transition between teams and provide standard understanding with little interpretation. Being mindful that UML is built into the Visual Studio Ultimate IDE, and can integrate with Team Foundation Server (TFS), it becomes a very compelling candidate for system modeling (including requirements modeling). Especially for people using the Microsoft development stack.
When building out UML documentation, Use Cases document and model the requirements of the project. Use Cases are composed of three components:
- Actors: Who (or what) is doing the use case.
- Sub Systems: Where the use case happens.
- Use Case: What is being done by the actors within a subsystem.
An example project: Use Case GeneratorImagine we have a development process where the Business Analyst writes the Use Case descriptions. Use Case descriptions define the above components as narratives. A core component of the imagined development process is TFS. So I want to have traceability for use cases to the project's requirements. Visual Studio Ultimate can build UML Use Case documents but as a small IT shop, I don't have the money to buy every BA the most expensive Visual Studio. Instead, we will build a Use Case Generator web app that will produce Use Case descriptions to be consumed by Visual Studio.
So we are going to build a little web app that will allow a BA to write a use case following a template (see below). To learn about Use Cases, let's build the Use Cases for our Use Case Generator web app. Let's get started:
Step 1: Listing the ActorsStart by listing out the Actors. The critical question her is who or what is interacting with the use cases. I usually start with people as they are easiest to determine for me:
- Business Analyst: this actor is the main user of the Use Case generator system.
- Architect: this actor will receive the Use Case from the generator to import into Visual Studio
Now, list out the "what" actors, those that are not people but that the system will interact with. For this system we will have only one:
- Data Store: I will need somewhere to save data. This actor is a system component that I'll use to save data.
Notice, we do not define "how" we are saving data just that we need to have some actor that saves data. Use Cases don't necessarily deal with the details of the how. Build out your list of actors and re-examine - are you missing anything? Did you identify everything or too much? How do you know? We'll come back to this in a moment. For now, give yourself a time limit of 10 minutes to define all the actors. Don't get bogged down into paralysis through analysis.
If you are starting with requirements or user stories, they review those for nouns. Nouns are a sure give away of an Actor. For instance in the following user story: "As an Architect I must be able to export a PNG image from the UML diagram so that I can embed the diagrams in a web page." In this high level and fairly ambiguous user story we have a clear Actor, the Architect. Use Cases can easily be distilled from User Stories due to the format of User Stories. Try it out for yourself. Review your product backlog and build a list of all the Actors from your User Stories.
Step 2: Use Case ListingWith Actors listed, now create a list of what you want your system to be able to do. Try to keep your Use Cases to Verb-Noun pairs that are clear to you. For our system, here is our list:
- Add Actor
- Edit Actor
- Delete Actor
- List Actors
- View Actor
- Add Use Case
- Edit Use Case
- Delete Use Case
- List Use Cases
- View Use Case
- Export Model (export the Actors and Use Cases)
- Save Model
- Clear Model
- Load Model
Step 3: Use Case DescriptionsNow for each Use Case we listed we need to build out a description for it (this is where the use case becomes clear to others and not just "you"). Russ Miles & Kim Hamilton's Learning UML 2.0 provides a great template for Use Case descriptions (as a side note, this book is excellent to learning UML). The template is great for capturing what a use case actually means.
Fill out the following items for each use case listed.
- Use case description: why is this use case useful for the Actor(s) engaged
- Related Use Cases: what other use cases are used in this use case? Perhaps there is a common use case shared among many uses cases (also known as an "included" use case. List out all the related use cases here.
- Goal in Context: what is the goal of this use case? Where do you want the Actor to end up?
- Pre-Conditions: what needs to happen before this use case can happen? For example, for "load model" use case to work, we need to first "Save Model" so that we have a model to load.
- Successful End Condition: what happens when everything works as expected? This is a great data point for QA as they can use it to identify what the expected end result is.
- Failed End Conditions: what are some expected failure conditions. As an example, what happens when load model is called but there are not any models saved? List out as many failure scenarios that you can think of.
- Primary Actor(s): who is the key players in this use case? Normally this is an initial mover for the use case.
- Secondary Actor(s): who are the supporting cast in the use case. This could be a database or web service call.
- Trigger: what is the action(s) that start the use case? Normally an Actor triggers the trigger. List here what happens that starts the next item (main flow).
- Main Flow: if everything works as expected, how does the use case flow from start to end? This shows the steps of execution for the use case.
- Extensions: when things don't follow the Main Flow, what happens? Extensions show alternative routes that the use case could take and how to handle them. Use Extensions for things like error handling and recovery.
Use Case Name: Add Actor
Use Case Description: this use case allows users to create a new actor for the model.
Related Use Case: no related use cases
Goal in Context: After adding an actor, the actor will appear in the Actor list and viewable from the model.
Preconditions: Business Analyst must have "Add Actor" permission
Successful End Condition: the Actor is added to the Actor List, a success message is displayed to the end user and the Actor details form is cleared.
Failure End Condition: Actor is not added to the Actor list. Success message does not display. Actor details form shows actor's details after clicking Save.
Primary Actors: Business Analyst
Secondary Actors: None
- Business Analyst clicks on the "Add New Actor" button.
- A new Actor is added to the Actor list showing the Actor name: "New Actor"
- The Actor Details form appears with the new Actor loaded
- Name: New Actor
- Description: Blank
- Location: Blank
- Business Analyst updates the Actor's details with the following fields:
- Name (Required)
- Description (Required)
- Business Analyst clicks the Save button
- The Actor is updated in the Actor list
- A success message is displayed saying: "The Actor was saved successfully"
- The Actor Details form clears it's values
4.1 If the Business Analyst does not provide data in the fields, a validation message will appear letting the Business Analyst know what fields need to be populated.
5.1 If the Business Analyst tries to save without providing the necessary fields a validation error displays.
5.2 Save is aborted
This is a simple example but illustrates how to use each element. Give it a try for another Use Case listed above. Leave your attempt in the comments section. Community review is a great way to refine your Use Case descriptions and all readers please remember, this is a place of learning not of ideal perfection :) .
Wait! Where were subsystems? Well, good question but for now, we'll wait on that. Remember, the BA is writing this for the Architect. When the diagrams are built by the Architect - the subsystems will be identified. If the BA knows them that is great but subsystems in our example process are the realm of the Architect.
Step 4: Use Case DiagramYou have your use cases described, you have your actors listed, now you need to put the big picture together. We will do this later in a future posting. For now work on your narratives.
Step 5: Enjoy a drink for your good work!Go enjoy a drink now and try to write up some of your own use case descriptions. Next we will build out a small web app that puts all these use cases together.
Was this a helpful introduction to Use Cases? Let me know your thoughts below.