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

Featured
29561 Views
9 Comments
14 Likes

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 – [email protected].

Like this article:
  14 members liked this article
Featured
29561 Views
9 Comments
14 Likes

COMMENTS

mmroczek posted on Tuesday, January 17, 2012 12:37 PM
It seems that I write use case scenarios with similar approach for many years. In every step where system/actor can take different action, I put additional comment. In your example it would be as follows:

...
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).

comment: Flow goes either to step 5 (if username and password are correct) or to scenario 5a 'Username/password failed' (otherwise).

5. ...

Such comments are useful when you do not provide use case scenarios with UML activity diagrams. Diagram always decreases the ambiguity of description and extorts self-discipline from analyst.

What is important in such approach is the alignment between 'exits'' in related business/decision rule and 'exits' in given scenario step.
mmroczek
rads posted on Thursday, January 26, 2012 4:12 PM
very good article and bpmn diagram is also quite helpful
radsahana
Putcha posted on Wednesday, February 15, 2012 11:18 AM
Hai Mark Monteleone:

A very good article. Yes, nothing is gained by hiding conditional actions and responses in Use Case Description. I appreciate the comprehensiveness and precision you bring to Use Case Description (in tabular form), contrary to the popular tendency of simplifying and oversimplifying Use Case Description to the point of trivializing it. I also appreciate keeping Business Rules separate by linking them suitably.

I too have been practicing and advocating comprehensive high-precision Use Case Description but I have not published my practice. I would like you to review my proposals. Let me know if you are willing to review ([email protected]).

I have a few QUESTIONS.

The rounded rectangles you have used in BPMN diagram have three sections. Are the top and bottom sections for performer and place of action? Is that recommended in the standard or your extension? It is useful. It reminds me of Gane and Sarson’s DFD convention. You have not used swim-lanes. They take care of the performer and place of performance in some way.

I have some SUGGESTIONS.

I see that you use a single large Use Case Description. That is OK as long as the Actor is SINGLE and is the SAME for the entire Use Case Description.

If we wish to be specific and precise, a Use Case Description is a DIALOG between one ROLE and The System Under Study. It should involve only ONE Role per Use Case. The System Under Study is the default participant in all Dialogs.

Necessary Breaks in Use Case Dialog: The Use Case involving Guest ends after Guest makes a request for membership and initiates payment giving credit card details.

Completing the payment is NOT within the capability of Guest and so that Use Case must end at that point.

The Bank or CCApprover only can make payment to Book Club System. That has to be done through ANOTHER Use Case “Transfer Funds to Book Club System” in which the Bank or CCApprover is the Actor but NOT the Guest.

These are my SUGGESTIONS and I hope they will bring more clarity and precision to Use Case Descriptions.
putchavn
Leslie posted on Wednesday, February 15, 2012 6:14 PM
It's good to see some examples of well written use cases. My preference would be that described in Table 1, simply because it has less steps and appears to contain the same information as Table 2. Personally, I don't like the idea of including steps that describe the 'thinking' process (A 'decides' to do this), simply because I don't know how to validate that the step was met.

But, the important thing is clarification for the reader, so what ever works for them.

The reason we don't reference alternate flows in the basic flow is because if the alternate flow changes, I now have to make the change in 2 places. A single directional pointer (from alternate to basic flow), is adequate.

In the use case diagram, I like to indicate which of the 3 actors is the primary actor (initiating the use case). I do this by adding an arrowhead to the association. I have never understood the purpose of drawing a box around the use case though -- seems like a waste of ink to me.

Oh and thankyou for using BPMN to draw the example activity. I've been wanting to show that BPMN is a perfectly good tool for modeling use case details, just never got around it.

baldrick
John Kelly posted on Friday, February 17, 2012 7:32 AM
I like this suggested method: when a decision is called out, it is obvious that at least one alternate flow is required and that at least one business rule is required. This makes it easier to catch alternate flows and business rules while writing your use case and also while reviewing or using someone else's use case.

Regarding the comment by putchavn that the use case should end after the guest completes his last step: if you believe the purpose of a use case is to define a process that ends with a business goal (e.g., establish a member account), you would not split up this use case. One suggestion is to combine steps 12 through 14 in the improved use case into one step -- "The Book Club System confirms payment" -- with a reference to a separate "Confirm Payment" use case or batch specification that handles that particular process.
jwk30043
Mark Monteleone posted on Friday, February 17, 2012 8:36 AM
@putchavn – Thank you for your comment.

Concerning the BPMN model, the rounded boxes are standard per BPMN 2.0 choreography. Yes, the top and bottom sections denote actors in the dialogue. When a section is colored gray, it is that actor conducting the action stated in the center of the box.

Your suggestion to terminate the use case once the Guest submits the credit / debit card information would be premature. The use case post-condition for successful execution is a Guest state change from “non-member” to “member.” The system can only change the state after the Credit Card Approver / Bank confirms the payment. The system then notifies the Guest of ”member” status. There is also this aspect: actors on the use case diagram are interactive. If the system sends the credit / debit card information to the Credit Card Approver / Bank and terminates without waiting for a confirmation, the transaction is not interactive – it is a “batch” transaction, like sending an e-mail or printing a report. In this case, the business analyst only cites the Credit Card Approver / Bank involvement in the use case description (scenarios), not on the use case diagram.

Regarding activity model swim-lanes, I do not use them for use case dialogue since the result is often just a back and forth conversation between lanes. I do use activity models with swim-lanes to depict the process flows behind use case dialogues.

@baldrick – Thank you for your comment.

I agree with your comment on references. Although I used the references in the main scenario only for instructional purposes, your point is well taken.

I do not use association arrows to identify the actor that is initiating the use case since it is not a UML standard. Although some software products use association arrows, to me, it gives the impression of a process flow, which the use case diagram is not.

Concerning the surrounding box, I prefer context use case diagrams since it depicts the boundaries of the subject (system under development). It makes it clear what is in the project scope and what is not. For example, system actors outside the box provide interactive functions that are not within the scope of the project. Those system actors either exist or are under development by another project.
mmonteleone
Putcha posted on Friday, February 17, 2012 12:28 PM
Mark:

I will work on your the first response. I need to clarify on the second response and add to the third: I have added my comments inline after PVN<<<…..>>>:


Your Second Response:

Your suggestion to terminate the use case once the Guest submits the credit / debit card information would be premature.

PVN<<< When a Use Case is terminated the GOAL itself will be redefined so it is NOT premature. It is done to avoid showing large TREE Structure of conditional dialogs and alternatives in a single use case.>>>

The use case post-condition for successful execution is a Guest state change from “non-member” to “member.” The system can only change the state after the Credit Card Approver / Bank confirms the payment. The system then notifies the Guest of ”member” status.

PVN<<< One cannot predetermine the post condition if there are number of possibilities like “membership given” or “membership denied” or “membership pending” which will be known only after the dialog with other “decision making Actor”. So, the state will be “membership request accepted for processing”>>>

There is also this aspect: actors on the use case diagram are interactive. If the system sends the credit / debit card information to the Credit Card Approver / Bank and terminates without waiting for a confirmation, the transaction is not interactive – it is a “batch” transaction, like sending an e-mail or printing a report. In this case, the business analyst only cites the Credit Card Approver / Bank involvement in the use case description (scenarios), not on the use case diagram.

PVN<<>>

Your third response:

Regarding activity model swim-lanes, I do not use them for use case dialogue since the result is often just a back and forth conversation between lanes. I do use activity models with swim-lanes to depict the process flows behind use case dialogues.

PVN<<>>

Regards,

[email protected]
putchavn
Putcha posted on Wednesday, April 25, 2012 7:51 PM
I am not sure if the message is addressed to me. I do not know the language...sorry.

If it relates to me, I would like some one to translate it for me. Thanks. PVN.
putchavn
Only registered users may post comments.

 



 




Copyright 2006-2024 by Modern Analyst Media LLC