Thursday 26 April 2012

Use Cases - Alternate Courses (1 of 2)

In our previous series we explain the basics of a use case and how they can be extended with more information inside and outside the use case:

Tutorial Part
Description
Shows that a use case is a dialog between a role and the system
Define actors and show what a use case diagram is
Add detail inside the use case such as screens, data entry criteria, and reports
Add detail outside the use case showing its context with the rest of the system

This information is a good first step to being able to write use cases.  However, without the notion of alternate courses the use case it is not possible to write effective use cases.

In every dialog that an actor has with the system there are choices that must be made.  These choices occur at three distinct levels:
  • Low level choices represented by a step inside the use case
  • Medium level choices represented by alternate courses of activity inside the use case
  • High level choices represented by other use cases

Let's take the ATM dialog extend it to show the different choices that the actor and ATM has and discuss how to address each choice from a documentation standpoint. Below we show the various possible interactions between the actor and the ATM as a UML state machine.

State A
The actor approaches the ATM and sees the welcome message.  The only choice is to either insert your card or walk away. 
The choice of walking away is NOT detectable by the ATM; therefore there is only one choice available at this time.  Therefore there is only one way to proceed from state A.

State B
The first few steps from our use case for Authenticate User from the Use Case Tutorial (1 of 4) was as follows:

1. ATM displays greeting to user and asks him to insert his card
2. ATM reads card and gets PIN from user
3. ATM presents a list of transactions and asks user to select one
4. User selects transaction

Clearly we assumed in use case step 1 above that we assumed that the card would be inserted, read and valid.  This choice represents a medium level choice because it changes the flow of the actor/system interaction for the rest of the use case.

We can call the interaction above the Basic Course of the use case.  The basic course is the sequence events which occur most frequently in the use case.  Exceptions to this sequence of events will be documented in an alternate course inside of the same use case. 

When the actor inserts their card into the ATM, now there are choices possible:
  • The ATM might be unable to read the card (state E)
  • The ATM is able to read the card
    • The format is not the ISO/IEC 7813 format expected by an ATM (state D)
    • The format is the ISO/IEC 7813 format expected by an ATM (state C)
The result of reading the card will lead to these 3 distinct states, each of which requires a different message to be shown to the actor.  Only the state where the card is recognized as an ATM card has any meaningful continuation. We can extend the dialog of the use case in the following way:

Basic course
1. ATM displays greeting to user and asks him to insert his card
2. ATM reads card and gets PIN from user
3. ATM presents a list of transactions and asks user to select one
4. User selects transaction

Alternate course: Card can not be read
1. ATM displays greeting to user and asks him to insert his card
2. ATM is unable to read the card
3. ATM displays that it can not read the card
4. ATM ejects card

Alternate course: Card not in ISO/IEC 7813 format
1. ATM displays greeting to user and asks him to insert his card
2. ATM is unable to read the card
3. ATM displays that the card is not an ATM card
4. ATM ejects card


Next Steps
While we have identified two alternate courses to cover state D and E, we have not identified what the next step is.  We need to extend the alternate courses with information on the next step for the developer.

Basic course
1. ATM displays greeting to user and asks him to insert his card
2. ATM reads card and gets PIN from user
3. ATM presents a list of transactions and asks user to select one
4. User selects transaction

Alternate course: Card can not be read
1. ATM displays greeting to user and asks him to insert his card
2. ATM is unable to read the card
3. ATM displays that it can not read the card
4. ATM ejects card
Next step: Return to step 1 of the basic course 

Alternate course: Card not in ISO/IEC 7813 format
1. ATM displays greeting to user and asks him to insert his card
2. ATM is unable to read the card
3. ATM displays that the card is not an ATM card
4. ATM ejects card
Next step: Return to step 1 of the basic course

In this case the developer simply restarts the main event loop of the ATM and goes back to showing the greeting.

This covers State C, D, and E

  • How to handle user input choices, state F
  • How to handle the cancel button, state G
  • How to handle user interaction choices, state H


Friday 13 April 2012

Use Case Tutorial (4 of 4)


In a previous blog we explained how the core of a use case is a textual description of the dialogue between an actor and the system.  We then covered that actors are roles in the system and that a collection of use cases indicates scope.  We then explained how we can add detail to the use case dialogue in the form of screens and input criteria.

The first 3 blog entries have identified information for the use case that allows the developers to make sure that the dialog is properly implemented.
 
The identification of the basic actor and system dialog corresponds to the cyan area above.  We then showed how we can add detail to the dialog to increase the level of detail for developers by adding screens, input criteria, and reports (pink area above). Up until now we have elaborated on the details necessary for a developer to actually develop the code behind the use case.

However, before coding this use case the development team will want to know how this use case fits within the user interface and under which conditions the use case is accessible.  This larger context (green area above) is important to the development team so that they can plan the user interface and determine in which order the use cases will be developed.

This larger context will be specified by several attributes which will be useful in two ways:
  • The placement of the use case within the development of the overall application
    • Design of the user interface
    • Conditions under which the use case will execute
  • Project management information

Attributes for application context
The only use cases available to a user will be dictated by the user interface.  For example, the Withdraw Money use case is only available after someone has authenticated themselves to the ATM.  When a user first approaches an ATM they are likely to see the following screen:

Clearly, it is not possible to access the Withdraw Money use case from this screen.  After the user has entered their card and PIN, the user will be presented with the Select Transaction GUI.

It is at this point that the Withdraw Money use case is available.  The use case should be annotated with a trigger attribute that identifies how the use case is executed.  In this case, the trigger is the selection of the Withdraw button from the Select Transaction GUI. 

If you are able to determine that a user is not allowed to execute a particular use case then this condition should be included with the trigger and the user interface should not present the use case or it should be greyed out.  Suppose our ATM was able to determine that you have no funds in your account, then it makes no sense for someone to execute the Withdraw Money use case and we could have simply presented the Select Transaction GUI as follows:
  
The next annotation will be the pre-conditions under which the use case is allowed to execute.  Typically the preconditions will revolve around whether the user has the permissions to execute the use case.  The developers can make sure to test all preconditions within the code if they are following the design by contract methodology.

In our case of Withdraw Money the precondition will be that the user has been authenticated by the ATM.  Ideally the user would have to have funds to be able to execute Withdraw Money, however, most ATMs will not query the bank to see if you have funds before the actual withdrawal is attempted.

Once a use case is complete there are a set of post-conditions which should be true.  i.e. if a user withdraws $100 then the account should be reduced by $100, the user should be issued a receipt (if they wanted one), and $100 should have been dispensed to the user.  Post-conditions will make much more sense when we cover alternative courses for a use case in later blogs.

So the attributes for application context for Withdraw Money would be:
Attribute
Description
Actor
  • Customer
Trigger
  • Customer selects Withdraw Money button
  • Customer is authenticated
Pre-conditions
  • See trigger
Post-conditions
  • Customer account is updated
  • Money is dispensed
  • Receipt is dispensed

Attributes for Project Management
As we have identified in a previous blog, a set of use cases provides scope for a project.  When developers begin a project it is important to add attributes to each of the use cases so that the development effort can be structured.

Two key attributes to add to a use case would be frequency and importance.  Frequency indicates how often the use case will be executed, and importance indicates from a business perspective how important the use case is.

In the case of Withdraw Money is has an extremely high frequency and business importance.   An ATM exists only because of the Withdraw Money use case; all the other use cases are secondary.  By qualifying use cases by frequency and importance the development team can create those use cases first as they will likely have strong impacts on the architecture.

So the attributes for project management for Withdraw Money would be:
Attribute
Description
Frequency
1000 times a day
Importance
Very high

There may be use cases that have a low importance but they will be executed at a high frequency.  By coding these use cases first there should be enough time to address poor performance characteristics during development.

There may be use cases of high importance but that will have low frequency.  An example of this might be an annual report that only executes once per year.  Even though it only executes once per year, the complexity of the annual report may require quite a bid of development and may also entail performance issues.  This is another type of use case that should be addressed earlier rather than later.

By addressing high frequency and importance use cases up front, the development team has a greater chance of building an architecture that will be sufficiently robust for the application.

Summary
  • Use cases can be extended with meta information needed for developers to place the use case in the overall application context and to aid in project management
  • The meta information for overall application context would be:
    • Actor
    • Trigger
    • Pre-conditions
    • Post-conditions
  • The meta-information for project management would be:
    • Frequency
    • Importance
  • By including the project management meta-information use case development can be structured so that good architecture will be created.
Use case
The use case for Withdraw Money can be found here. 
  • This use case has all the attributes discussed in this 4 blog series.
  • While this level of detail will lead to relatively effective use cases, the addition of alternate courses must be added for the use case to become effective.
The next tutorial is on adding alternate cases to your use cases.  This enables you to handle exceptions and other alternate courses that need to be modeled.