Monday, 7 May 2012

Basic UML – UML Diagrams – Include use cases

The Universal Modeling Language (UML) is not the only way to produce diagrams for a software project, but it is the most accepted methodology.  The list of tools for UML is quite large and can be found here.  Please use the Internet to learn more about the history of UML and what it can do for you.

Recap of the Tutorials
Recently, we have focused on creating practical use cases.  Our tutorial on use cases showed that a use case is a dialog between an actor (role) and the system (tutorial 1 of 4).  We then explained what an actor was and introduced basic use case diagrams (tutorial 2 of 4).  The subsequent tutorials showed how to add screen information, data entry criteria, and reports to use cases to add detail (tutorial 3 of 4); and how to add context information to use cases so that it could be positioned within a project (tutorial 4 of 4).
The use case diagram shows a relationship between an actor and a use case.  A user is concrete but a role is abstract.  Just as any woman might have the role of a mother, daughter, girl friend, PTA member, etc in different contexts, a user may have one or more roles within a system.

Use cases are behavioral because they describe an interaction between a role and the system that will cause the system to change state.  So use case diagrams are functional. 

Use Case Diagram for a Retail Point of Sale System
Let's design software for a retail merchant.  The most basic thing that a merchant does is to sell goods to a customer.  The merchant sells those goods by using a sales representative and the Sell goods to customer use case might be as follows[1]:
Use Case Diagram
The simplest use case diagram is as follows:

This indicates that there is a role within the system called Sales Representative and that they have access to the Sell goods to customer use case.  The details of dialog between the sales representative and the system will be outlined in a text use case as shown above (MS Word).

Include Use Cases
An include use case includes a dialog sequence that is common to multiple use cases. An include use case can reduce the amount of writing in our use cases if two or more use cases must use the same dialog.  Ideally you write out both use cases completely and then make sure that a single section is identical. 

By combining common sequences into an included use case you not only reduce the amount of documentation but also reduce the chance of inconsistent requirements stemming from changes in one document that are not copied uniformly.

Include use cases can also be used if a sequence of dialog in a single use case requires so much documentation that it would obscure the essential purpose of the use case that it is part of.

To Include, or Not to Include
Creating an include use case when you really don't need it will increase your documentation and the chances of confusion during development.  Let's look at the sell goods to customer use case and see if there are any sequences that might be factored out into an include use case.

To sell goods to a customer the sales representative will enter one or more bar codes manually or via a scanner.  It seems possible that scanning a bar code might be a possible include use case.  If so it would change the diagram as follows:
We add a new use case to the diagram Scan bar code using scanner and designate Sell goods to customer as including it.  What this means is that the only way to invoke the dialog for Scan bar code using scanner is from the Sell goods to customer use case.  The use of the word include indicates that the functionality is necessary and will be invoked 100% of the time somewhere from the dialog for Sell goods to customer.

When we look closely at how bar code scanners work, they typically return the scanned bar code as a keyboard.  In other words, you can't really tell if the sales representative typed in the bar code or whether they scanned the bar code.  Since the behavior of the scanner does not create any alternate courses this would be an example of when NOT to use an include use case.
However, if you are developing the code to work with the scanner or the 3rd party software returns multiple exceptions then each exception will probably trigger an alternate course.  The primary goal of Sell goods to customer might be obfuscated if the bulk of the use case turns out to be alternate courses dealing with the scanner.  In that case, it makes sense for Scan barcode using scanner to be a separate use case.

Only create separate use cases for inclusion under the following circumstances:
  • The alternate courses created by one part of the dialog would obfuscate the primary goal of the use case
  • Non-trivial development needs to be done on part of a dialog and you need to track that functionality separately in your bug tracking system
Print Receipt
Looking through the rest of the use case we see that the dialog required for step 6. System prints out a sales receipt could actually be quite complicated[2].

Clearly there will be variation of the receipt depending on whether the customer paid with cash or credit.  You will need to get the information about the sales representative and other details on the bill.

During development, there will probably be a developer assigned to handle all the coding for the receipt (and all the nit-picking changes that product management will make J).

The printing of the receipt is definitely going to involve more work than that involved in collecting the bar codes.  But before you create an include use case for Print out a sales receipt you should start by writing the dialog into the main use case Sell goods to customer.  If the use case turns out to be large and obscure the purpose of Sell goods to customer than it will deserve to have its own use case.

In general, most use cases that involve printing receipts and reports can be split out into separate use cases.

  • Include use cases can be used to capture common dialogs that occur across multiple use cases
  • Exceptionally use them when the alternate courses in a subset of a use case would cause the purpose of the entire use case to be obfuscated
    • Try to create a single use case first, then split it up if it is too large
  • Typically reports and receipts will get split out from the main use case
Next Steps
  • In the next blog we consider extend use cases

[1] Note, we don’t show any alternate courses right now otherwise the use case would be quite long J
[2] Best Practices for Credit Card Transaction Receipts on