Document Decisions Separately and Explicitly – A Proposed Use Case Scenario Best Practice

This article proposes a use case best practice technique: Always document decisions separately and explicitly in use case scenarios. This practice assists the business analyst in identifying where alternate and exception paths may be needed. This is similar to how decisions and resulting gateways are documented in Business Process Model and Notation (BPMN). The article provides a before and after example of a use case scenario along with a BPMN choreography diagram of the scenario. The author assumes the reader is familiar with the development of use case scenarios and BPMN.

Observation

Recently while instructing a use case course, students were having difficulty identifying where alternate and exception paths are needed to be placed in a use case scenario. The students said they had no problem understanding the various techniques of writing the alternate and exception paths; unlike use case diagrams, there is no Unified Modeling Language (UML) standard method for writing use case scenarios. The challenge for the students was where to place the

Alternate paths (options) are the result of an actor’s choice.

Exception paths (errors) are the result of the system’s choice.

Note some practitioners do not distinguish between alternate and exception paths.

alternate and exception paths in the scenario.

Developing Use Cases

Typically when writing a use case scenario, it is a best practice for the business analyst to write it in this sequence:

  1. main scenario – known as the “happy path” which is the quickest/dominant path to accomplish the use case goal

  2. add the alternate and exception paths as a second effort

  3. and as needed consider

    • Include use cases for common use case behavior

    • Extend use cases for add-on or temporary behavior

    • Generalized/Specialized use cases for enforcing standards

The effect of the order is that the main scenario is unaware of any alternates and exception paths. The emphasis is goal accomplishment via a straight flow (no alternates/exceptions) from beginning to end. No decisions are shown; however they are implied (hidden) from the resulting action steps.

Use Case Example

For illustration purposes, consider an on-line Book Club System; see Figure 1. The system may be accessed by a Guest for the purposes of establishing a member account. In establishing the account, the Guest may choose to pay the membership fee either by a credit card or a debit card. The credit card is expected to be the preferred payment method. The credit card payment is confirmed by a Credit Card Approver while the debit card payment is confirmed by a Bank. Note the Credit Card Approver and the Bank are external systems.


Figure 1. Use Case Diagram for Book Club System

Table 1 exhibits the scenario for the use case “Establish a member account.” Note that the use case scenario is written with implied (hidden) decisions. Unfortunately, these implied decisions also hide the reference points for possible alternates and exception paths.

Proposal

I do not propose changing the above best practice. I do propose making decisions visible. By visible, I mean a separate and explicit step for each decision being made. These steps help the developer identify where possible alternate and exception paths may be placed. These decision points occur when an actor’s input drives the scenario down various paths. For example, in Table 1 the Guest inputs:

  • a username and password which results in the Book Club System either validating or invalidating the username and password

  • either a credit or debit card which results in the

    • Book Club System asking for payment confirmation from the Credit Card Approver or the Bank respectively

    • Credit Card Approver or the Bank confirming or denying payment

In each case above, the system takes a different action (i.e., alternate path or exception path respectively).

Look at Table 1 again and compare it with Table 2 where decisions are separately and explicitly (visible) documented. It is much easier to determine the reference point for alternates and exceptions with separate and explicitly documented decisions. Also, note that even when decisions are explicitly documented, the main scenario remains unaware of the existence of the alternate and exception paths.

Proposed Use Case Scenario Best Practice

“Always document decisions separately and explicitly”

These decisions occur when an actor’s input drives the scenario.

Table 1. Use Case with Implied Decisions

USE CASE TITLE Establish a member account
Pre-condition Guest access to the System with a state of “non-member.”
Post-condition (Goal) Guest state is changed from “non-member” to “member” with an established member account.
Description Guest accesses Book Club System, establishes a username, password, and member account. Membership fees are charged to the Guest’s credit or debit card. Guest changes to Member with access to other use cases.
MAIN SCENARIO
  1. Use case is initiated when a Guest requests to establish an account.
  2. The Book Club System requests the Guest to choose username and password. Note Guest may abandon the use case at this point.
  3. The Guest provides username and password.
  4. The Book Club System validates the username and password per business rule catalogue (see article Post Script). There is an implied (hidden) decision made by the Book Club System between step 3 and 4 on validation. Step 4 is the positive result of that decision.
  5. The Book Club System states a membership fee.
  6. The Book Club System requests the Guest for payment method. Note Guest may abandon use case at this point.
  7. The Guest chooses a credit card. There is an implied (hidden) decision made by the Guest between step 6 and 7 on payment method. Step 7 is the dominant result of that decision.
  8. The Book Club System requests the Guest for credit card details.
  9. The Guest provides credit card details.
  10. The Book Club System requests payment confirmation from the Credit Card Approver.
  11. The Credit Card Approver confirms payment with the Book Club System. There is an implied (hidden) decision made by the Credit Card Approver between step 10 and 11 on payment method. Step 11 is the dominant result of that decision.
  12. The Book Club System establishes the member account.
  13. The Book Club System changes the state of the “non-member” to “member.”
  14. The Book Club System states the Guest is now a member.
  15. Use Case ends.
ALTERNATES and EXCEPTIONS 4e. Book Club System invalidates the username and password.
  1. The Book Club System states the username and password are invalid per business rule catalogue (see article Post Script).
  2. The main success scenario resumes at step 2.
7a. Guest chooses to pay by debit card.
  1. The Book Club System requests the Guest for the debit card details.
  2. The Guest provides the debit card details.
  3. The Book Club System requests payment confirmation from the Bank.
  4. The Bank confirms the payment with the Book Club System. There is an implied (hidden) decision made by the Bank between step 7a.3 and 7a.4 on confirmation. Step 7a.4 is the positive result of that decision.
  5. The main success scenario resumes at step 12
7a.4e The Bank denies the payment
  1. The Bank denies the payment with the Book Club System.
  2. The Book Club System states the payment is denied with Guest.
  3. The main scenario resumes at step 6.
11e. The Credit Card Approver denies payment.
  1. The Credit Card Approver denies the payment with the Book Club System.
  2. The Book Club System states the payment is denied with Guest.
  3. The main scenario resumes at step 6.

 

Table 2. Improved Use Case with Decisions Explicitly Documented

USE CASE TITLE Establish a member account
Pre-condition Guest access to the Book Club System with a state of “non-member.”
Post-condition (Goal) Guest state is changed from “non-member” to “member” with an established member account.
Description Guest accesses Book Club System, establishes a username, password, and member account. Membership fees are charged to the Guest’s credit or debit card. Guest changes to Member with access to other use cases.
MAIN SCENARIO
  1. Use case is initiated when a Guest requests to establish an account.
  2. The Book Club System requests the Guest to choose username and password. Note Guest may abandon the use case at this point.
  3. The Guest provides username and password.
  4. The Book Club System decides on the validity of the username and password per business rule catalogue (see article Post Script). This is a separate and explicit (visible) documented decision followed by the result in step 5. Note that this is an in-scope decision made by the Book Club System.
  5. The Book Club System validates the username and password.
  6. The Book Club System states a membership fee
  7. The Book Club System requests the Guest for payment method. Note Guest may abandon use case at this point.
  8. The Guest decides on a payment method. This is a separate and explicit (visible) documented decision followed by the result in step 9. Note that this is an out-of-scope decision made by the Guest – not the Book Club System.
  9. The Guest chooses a credit card.
  10. The Book Club System requests the Guest for credit card details.
  11. The Guest provides credit card details.
  12. They Book Club System requests payment confirmation from the Credit Card Approver.
  13. The Credit Card Approver decides on confirmation. This is a separate and explicit (visible) documented decision followed by the result in step 14. Note that this is an out-of-scope decision made by the Credit Card Approver – not the Book Club System.
  14. The Credit Card Approver confirms payment with the Book Club System.
  15. The Book Club System establishes the member account.
  16. The Book Club System changes the state of the “non-member” to “member.”
  17. The Book Club System states the Guest is now a member.
  18. Use Case ends.
ALTERNATES and EXCEPTIONS 5e. Book Club System invalidates the username and password.
  1. The Book Club System states the username and password are invalid per business rule catalogue (see article Post Script).
  2. The main success scenario resumes at step 2.
9a. Guest chooses a debit card.
  1. The Book Club System requests the Guest for the debit card details.
  2. The Guest provides the debit card details.
  3. The Book Club System requests payment confirmation from the Bank.
  4. The Bank decides on confirmation. This is a separate and explicit (visible) documented decision followed by the result in step 9a.5. Note that this is an out-of-scope decision made by the Bank – not the Book Club System.
  5. The Bank confirms the payment with the Book Club System.
  6. The main success scenario resumes at step 15.
9a.5e The Bank decides to deny the payment
  1. The Bank denies the payment with the Book Club System.
  2. The Book Club System states the payment is denied with Guest.
  3. The main scenario resumes at step 7.
14e. The Credit Card Approver decides to deny payment.
  1. The Credit Card Approver denies the payment with the Book Club System.
  2. The Book Club System states the payment is denied with Guest.
  3. The main scenario resumes at step 7.

BPMN Diagram of Use Case Scenario

Another method of documenting use case scenarios is via Business Process Model and Notation (BPMN); see Figure 2. Note as the proposed best practice, decisions and their resulting paths in BPMN are documented separately and explicitly. In BPMN, the diamond element (◊) is a gateway that separates process paths that result from a decision that is made in a prior task or joins them. The diamond element does not represent the decision itself as in flowcharting.

Figure 2. BPMN Diagram of Use Case Scenario (click here for larger version)
(main scenario – green, alternate – yellow, exceptions – red)

Summary

This article proposes a use case best practice technique: Always document decisions separately and explicitly in use case scenarios. This practice assists the business analyst in identifying where alternate and exception paths may be needed. Your comments are welcomed on documenting decisions separately and explicitly as a best practice.

Post Script

I want to mention that the reader may wish to follow-up on ways to document business rules – the criteria used for making decisions. As shown in step 4 of Table 2, business rules are documented separately from use cases (i.e., functional requirements). These business rules can be expressed in catalogues, tables or decision models. Also, note that only business rules for the Book Club System are cited since it is the only in-scope decision (username and password validation). The business rules used for Guest, Credit Card Approver and Bank decisions are out-of-scope of the Book Club System.

Author:  Mr. Monteleone holds a B.S. in physics and an M.S. in computing science from Texas A&M University. He is certified as a Project Management Professional (PMP®) by the Project Management Institute (PMI®), a Certified Business Analysis Professional (CBAP®) by the International Institute of Business Analysis (IIBA®), a Certified ScrumMaster (CSM) and Certified Scrum Product Owner (CSPO) by the Scrum Alliance, and certified in BPMN by BPMessentials. He holds an Advanced Master’s Certificate in Project Management (GWCPM®) and a Business Analyst Certification (GWCBA®) from George Washington University School of Business. Mark is the President of Monteleone Consulting, LLC and can be contacted via e-mail – mark.a.monteleone@sbcglobal.net.

posted @ Wednesday, November 9, 2011 11:02 PM by Transform VA