In this month's article I continue from last month by filling out the remainder of the use-case template for the Depositing Funds use case. As was the case last month, I've not just filled in the template, but also provided extensive comments about my thought processes as I was working. This month's part of the template is in a way the real meat of the use-case description since it actually describes the flow of work as the use case progresses. This work flow is what the program will have to do at run time as a user works through the use case.

In my last column, I covered about half of our use-case template. I'll pick up where we left off.

Filling out the use-case template for the Depositing Funds use case

Dependencies

Similar to: 2.0. Kid Withdrawing funds from an account. (equivalent?) Follows: 4.0. Parent opening an account Includes: 6.1. Parent authorizing a single deposit Followed by: 6.0. Parent authorizing prior deposits

This list is tentative. For example, the "Similar to" relationship with use case 2.0 might actually be an "equivalent" relationship.

Preconditions

The account must exist.

Inputs

The kid has earned some money.

Back to top

Scenarios

1. (Happy path)
   Philip has completed his chores for the day and has decided to deposit the resulting $2.25 into the Bank of Allen. (If he did his chores every day, I'd be broke by now.) He enters the bank, asks the teller for a deposit slip, fills it out, and returns the deposit slip along with his passbook to the teller. The teller asks for some identification before she accepts the deposit slip, then sends the slip to the bank officer for approval. The bank officer (a parent) authorizes the deposit by signing the slip, and sends it back to the teller, who updates Philip's passbook to show the transaction. The teller then returns the Passbook to Philip so he can gleefully ponder his growing account balance.

   Note that I've carefully used the vocabulary of the problem statement (discussed in previous installments of this series) in this scenario description (for example, "passbook," "teller," etc.). Had I introduced new concepts here -- and that does happen -- I'd have to go back and modify the problem statement to introduce the new vocabulary. A significant (and difficult) goal of the designer is to keep all design documents "in phase" with each other. If a change in one document impacts another, then both documents must be changed immediately. For example, I have deliberately not said "The teller makes a journal entry reflecting the deposit transaction," because "journal" is not in the domain vocabulary while "passbook" is in the domain. Whether you call it a "journal" or a "passbook" makes no difference to the design.

   Also note that I have not used the phrase "the system." The system doesn't do anything; rather, all work is done by actors who take on well-defined roles. Some of those actors (the kid) are real people. Other actors (the teller) are entirely automated. Other actors (the bank officer) are partially automated and partially real (some of the responsibilities of the bank officer are executed by a parent rather than a computer). It's the role that's important; It's immaterial whether the actor performing that role is or is not automated.

2. In this scenario, the money isn't actually added to the account; rather, the deposit is entered into the passbook as "unapproved." Any parent can approve the transaction at some subsequent time. In other words, the deposit is "on hold" until it "clears." The teller returns the passbook to the kid, and the deposit will show up in the passbook, but the funds cannot be withdrawn from the account until the parent signs the deposit slip. (This scenario differs from the happy path in that no parents are around to authorize the deposit.)

3. In this scenario, the parent deposits funds for the kid (as compared to the kid initiating, and the parent authorizing, the transaction).

By this juncture, I've gotten rather tired of the word "kid," as compared to something a bit less flip. I'm deliberately continuing to use the word kid -- rather than child, customer, or some other equivalent term -- because it's important that the nomenclature of the entire set of design documents be internally consistent. I'm wishing that I had chosen my terms a bit more carefully, though.

The second scenario actually introduces a new use case, which hadn't occurred to me earlier: "Parent authorizing prior deposits." This is really a stand-alone use case, even though authorization is also an operation in the current use case (implying a subcase: Parent authorizes a single deposit.)

Workflow
This section is the critical one, so I'll deviate a bit from the format I've been using hitherto and show how the workflow evolves. I start out by modeling the happy path as a simple list.

The happy path scenario:

1. Kid requests a deposit slip from teller and fills it out.
2. Kid submits the deposit slip and passbook to the teller.
3. Teller verifies the kid's identity as valid.
4. Teller sends the deposit slip to bank officer for approval.
5. Bank officer returns the deposit slip to teller, marked as approved.
6. Teller makes an entry in kid's passbook showing the deposit.
7. Teller returns the passbook to the kid.

Though a linear list is sufficient for a simple workflow, it doesn't cut the mustard when the workflow gets complicated.

Constantine and Lockwood recommend that you represent nonlinear operations using phrases like "In any order:" followed by a list. You could also use "Simultaneously" followed by a list to represent concurrency.

Maybe I'm just a visual kind of guy, but I find these words-only representation of use cases to be confusing. I prefer UML workflow diagrams when the use case is at all complicated. The UML for the simple happy path is shown in Figure 1.

The notation is more-or-less self explanatory. Each box is an activity, flow is indicated by arrows. You start at a solid circle and end at a target. The columns, called swim lanes, identify the class of objects (or the subsystems) that are responsible for performing the activity.

Looking at the diagram, I notice that there is some scope for parallelism. That is, some activities (verifying the kid's identity and approving the deposit) could be done in parallel. (You could also say that the order in which these activities are executed is unimportant, provided that they are all executed before moving on to the next step.)

Figure 2 shows the modifications required to Figure 1 to reflect this parallelism. The heavy horizontal lines that begin (are at the top of) a set of parallel activities are called forks. The lines at the bottom, which represent the point where the activities must synchronize before further work is possible, are called joins.

Now I go back and look at the other two scenarios, and try to merge them into the happy path activity diagram. (The modified diagram is in Figure 3.) In general, if it's not possible to merge the scenarios, or if the diagram that results from the merge is too ungainly, then the additional scenarios are probably stand-alone use cases, not scenarios of the current use case. The current batch of scenarios merge quite nicely, though.

The parent-makes-deposit-for-kid scenario turns out to be a no brainer once I realize that the workflow is identical to the happy path -- provided that I permit to parent to masquerade as a kid. That is, a parent's password can be used to log on a kid. I put a comment to this effect in both the activity diagram (Figure 3) and the business rules section (below).

The second scenario (where the parent isn't present) is slightly more difficult because I have to introduce a branch (indicated in Figure 3 as a diamond with one incoming and multiple outgoing arrows). The conditions that control which outgoing path to follow (called guards) are just text labels on the lines. A merge (also indicated with a diamond, but this one with multiple incoming and one outgoing arrow) marks the end of the conditional behavior. Every branch should have an associated merge.

You could express all the complicated stuff between the fork and the join as follows: In any order, verify the identity of the kid and also mark the deposit as approved if a parent is present, or unapproved if the parent is absent. Update the passbook after both activities (verification and marking) have completed.

Note that the original scenario description specified that the teller hold unapproved deposits. It became apparent while working with the diagram that it would be a lot easier for the unapproved deposits to be held in the passbook, not by the teller, so I did that. I went back and modified the scenario description to reflect this change.

Postconditions

new account balance = old account balance + deposit amount

Note that the use case encompasses two distinct operations (deposit request and deposit authorization) that don't have to occur at the same time. Nonetheless, this is a single use case with a single outcome. The account balance is always affected, even if some days elapse between the deposit and approval activities.

Outputs

An updated passbook.

This section would be the place where you'd actually show what the output will look like (in the case of a report, for example). I'll defer that until I start work on the UI in a subsequent article.

Business rules (domain-related)

1. Deposits must be authorized by a parent before they take effect.
2. Interest starts accruing on the day the deposit is made, even if authorization occurs on some subsequent day.
3. Unauthorized deposits can remain in the unauthorized state, waiting for a parent signature, indefinitely. They do not become "stale."
4. A parent's password will authenticate a kid. That is, parents can log on as kids.

Requirements (implementation-related)

1. Deposits must be "saved" automatically. There is no "File/Save" menu. An explicit "undo" isn't necessary or desirable. Undo a deposit with a withdrawal.
2. The "held" deposits must be displayed when kids view their passbooks. Held deposits will be displayed in gray.

Had I said "highlighted in some way" rather than "displayed in gray," I would be running the risk of writing a worthless specification. By the time we're done, the specification simply can't be ambiguous. Since all decisions have to be made eventually, you may as well get them out of the way now. You can always go back and change things if you make a wrong decision (until the specification is formally approved, of course.)

It seems better to me to make a wrong decision than to make no decision at all. I've seen many so-called specifications that were so mealymouthed that several hundred distinct programs could be generated from the spec, and all of these programs would be conforming. This sort of ambiguity is worse than useless, since it encourages you to do incorrect work.

In the current case, I suppose, the issue is so trivial that a decision may well be unnecessary. It doesn't matter in the least how the entry is highlighted, as long as it is highlighted. Consequently, this decision could be deferred to the formal UI-design process. If you leave the notion of highlighting indeterminate, the various programmers who are implementing the design will each implement their own notion of highlighting, with the resulting UI being inconsistent and harder to use as a consequence.

Implementation notes

1. There's currently no notion of logging in. Looking at the scenarios, Philip is not likely to make several transactions at once. In fact, it's more likely that he'll make a single transaction, but forget to log off. (This is an observed behavior from my home testing lab -- Philip often plays a game in the morning, and I'll find the game still running 12 hours later, after he's gone to bed.) Given this behavior, it seems more secure to ask for some sort of authentication as part of accepting a deposit slip. This is essentially the way a real bank works.
2. The analog of logging in would be identifying yourself to a guard as you were admitted to the bank. (Which might be a reasonable approach, it's just not the one I chose.) Note that there's nothing in this use case to prohibit the teller from remembering who Philip is. That is, it's within the scope of the use case for the customer to be somehow labeled as "trusted" so that subsequent transactions can be performed without needing to repeat the authentication process. The "trusted" attribute could be cancelled by a log out, or it could simply time out. (For example, you would become untrusted if two minutes elapsed without any activity within the bank.)
3. (This note may not be clear to you until we start the actual object modeling, so don't worry it if it doesn't make sense, yet.) The kid is, for the most part, an external object. That is, there is no programmatic object within the system that will represent the kid; rather, the kid is a physical user of the system. On the other hand, the notion of a kid's identity will almost certainly be modeled, since some object in the system must handle authentication.

4. There's a difference between "available funds" and "current balance." (The latter doesn't reflect unauthorized transactions.) Since the kid treats a deposit as a deposit, regardless of whether or not it's authorized, the passbook should display both values. In any event, it can't hurt to teach kids how a "hold" works.

   I'm not sure how best to present holds in the UI. One solution is for the deposit slip to be shown to any kids who look at their passbooks, but the deposit won't show up in the passbook proper until the deposit slip is authorized by a parent. Another possibility would be for the deposit to show up in the passbook like an authorized deposit, but with some visual indication (gray text?) that the deposit is being held.

   The latter makes more sense, but this means that the parent-authorizing-current-deposit use case will probably be significantly different from the parent-authorizing-pending-deposits use case.

   Note that, if the teller holds deposit slips for parent authorization, the kid will have to ask the teller to see the passbook so that the teller can display the held deposit slips as well as the passbook.

5. Probably the best way to handle parent authorization is on the UI for the deposit slip itself. Maybe an "Authorized" box, which, when checked, pops up a small dialog onto which a signature can be entered. Another possibility is a "authorized signature" line on the deposit slip itself into which a parent can type a pass phrase. (Note that some indication that the transaction has been authorized -- a facsimile of a signature, for example -- should appear on an authorized deposit slip ). Don't print x's in the authorized-signature line (or at least replace the x's once the signature is verified); there's no point in giving away the number of characters in the passphrase.
6. There are some access-control issues here. Someone in the role of kid has permission to specify deposits, but not to authorize deposits. (An authorization causes the account balance and passbook to be updated.) Someone in the parent role may both specify deposits and authorize deposits. The system must be able to distinguish between actors in these two roles -- password authentication is adequate.

7. Interest accumulates on held funds, even if these funds are not accessible. Probably the best way to handle interest is to think of the passbook as a list of transactions, sorted by date. When a deposit slip is authorized, it's inserted into the transaction list in sorted order. Interest is then recomputed, starting at the point immediately above the most recently inserted transaction. This way an unauthorized transaction effectively doesn't accrue interest.

   You want to show interest accrual on a daily basis, however, so it's not sufficient to list only transactions, as would a real-world passbook or bank statement. You really want a line item for every day. That's a lot of line items, though. A reasonable compromise might be to show the previous 30 days on a per-day basis, with the rest of the passbook looking like a standard bank statement that shows regular (but not daily) interest postings, perhaps one posting per week.

So that's an entire use-case presentation. Rather than bore you by presenting the rest of the use cases in subsequent columns, I'll put the complete set up on my Web site (see Resources) so that you can inspect them at your leisure. Next month we'll continue the design process by looking at the UI design (which is essential not only because we'll have to build it, but also because the UI serves both to validate the use cases and provide a useful communication tool).

Resources

• This article continues my series on the OO-design process. The first seven parts are:

  • Getting started
  • Beginning to design software
  • Refining the problem definition
  • Verifying the analysis
  • Use cases, an introduction
  • Use case planning
  • Use cases applied, Part 1
  
  
  
• Visit Allen's Web site at www.holub.com.
  
  
• Constantine and Lockwood recommend that you represent nonlinear operations differently than we have in this article.
  
  
• The notion of an object being defined by its operations is discussed in Allen Holub, What is an Object? (JavaWorld: July, 1999). Subsequent articles in the series (all of which are indexed at http://www.holub.com/aiharticles.html) discuss how this philosophy is actually applied to real-world systems.
  
  
• Workflow diagrams (along with the rest of UML) are described nicely in Martin Fowler and Kendall Scott's UML Distilled, 2nd Ed.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Filling out the use-case template for the Depositing Funds use case
• Scenarios
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers