Yearlong Case Study Shows Role Solves Problems that Actor Cannot

This use case example is a case study of a financial Transaction Auditing Program (TAP) that was put into production. It was then changed twice before a third change request was made. Every change represents additional cost to the organization including:

Additionally, the project users were unhappy leading to low customer satisfaction ratings.

The case study finds that the way analysts originally thought about the business problem led them to write faulty requirements. That, in turn, forced developers to build a fragile system that could not handle change easily.

The root cause of the thinking that led to the faulty requirements is using use case actors in the "industry standard" way. The case study shows how and why using roles instead of actors leads to better requirements that result in applications that satisfy, or even delight, your customers.

Start of Case Study - Problems with Actors

The use case example case study began when we received the following Change Request Form to modify an existing production application called Transaction Audit Program (TAP). TAP was designed to audit financial transactions to ensure compliance to standards and to detect potential fraud.

A Change Request Form was used in the case study and will be referenced as we go through the case study. The form clearly had issues as shown in the history that led to the predicament. The case study does embellish this real-life example.

In an example case study of a financial Transaction Auditing Program (TAP), it had to be changed twice, then when a third change request was made a solution was sought to avoid the need for future changes. Every change represented additional cost to the organization.

Original View of TAP

This is the view that the original designers had of TAP using standard UML notation. The TAP system is denoted by the gray box with TAP in the upper left corner. The system contains use cases that describe its functionality. Note that the use cases come from the Change Request Form and may not be well formed. This will become clear as we go through the case study. Entities are added as we need them. The class box titled Jim::Person is underlined. This means that Jim represents a real, living, breathing person with a specific address and a specific social security number. The two stick men are the roles Field Auditor and Home Office Auditor. The {my office} is a constraint that limits a Field Auditor to viewing only lists belonging to that auditor’s local office. Each local office handles financial transactions for a defined geographic area. There are many local offices.

1st Change in Production

After this application was rolled out into production, it did not work correctly. The organization approved a new project to “enhance” functionality in the TAP system. Note: “enhance” here is a code word for “fix what we missed the last time”. A few months later, the next version of TAP was put into production. It looked like the following diagram as described in the Change Request Form:

Field Auditors, who needed to work in multiple offices, including Jim, were made into Home Office Auditors. Now Jim could work in multiple offices – a plus. However, as a Home Office Auditor, Kim could view all lists because the path to the View List use case does not have the same constraint as the path from Field Auditor. Additionally, Jim can disqualify a transaction without replacement — potentially one that Kim knows was poorly handled or even fraudulent. This clearly is not good.

With this “solution” TAP has taken one step forward and two steps backwards in production as noted by the blue plus and two red minuses.

2nd Change in Production

So the next attempt to get the right business functionality was undertaken. Months later another new enhancement was rolled out. As described on the Change Request Form it looked like:

Now Jim is an Audit Administrator! Jim can do the unspecified something and still work in multiple offices for two blue pluses. However, Jim can still view all lists and, as Audit Administrator, do anything in TAP. Being conservative, we’ll call the rollup use case Do Anything You Want as five red minuses. Now TAP has taken two steps forward and seven steps backwards in production.

There is a trend to this TAP activity and its direction is not favorable. Needless to say, the affected end users and their managers are not happy.

Imagine a financial regulator inspecting the TAP application in this condition. “Hmm, this financial auditing application has thirty-three Audit Administrators. That is a security concern. I wonder how big this fine will be.” Or worse!

Redo with Building Requirements Consensus™ Methodology

What caused TAP to head down the path of decline in the first place in this use case example? We submit that the way the analysts thought about the problem led them to write faulty use cases. That, in turn, forced the developers to build a fragile system that could not handle change easily.

Instead of continuing the slide into the pit of confusion by simply doing what the Change Request Form asked for, we decided to model what TAP would have looked like if the analyst had used the Building Requirements Consensus™ Methodology.

This use case example diagram is very different from the first one. There are three different systems documented: The World system (i.e. User) that Jim and you live in, Human Resources (HR) system (i.e. Actor) and the TAP system (i.e. Roles and Activities).

It is common for people to think that they are working on a single system. However, in our careers, we have never worked on a single standalone system. Everything has been a system of systems.

When you do not specifically document every relevant system involved during UML modeling, you will miss requirements. There are questions that should be asked every time you cross a system boundary. If you do not consciously know you are crossing a boundary you will not usually think to ask those questions!

Therefore, in Building Requirements Consensus™ Methodology we document every pertinent system boundary explicitly.

The Term Role

Note that the Building Requirements Consensus™ Methodology states that there is a one-to-one mapping from a use case to a role. This variation from industry standard use case documentation practice is fully supported by the UML specification which states that an actor plays a different role with every use case with which it interacts. The industry standard use case practice allowing a one-to-many relationship between actors and use cases leads to serious ambiguity as evidenced by this case study.

Use case roles are described in class notation and are intentionally on the system boundary in this diagram. We define role names by inverting the use case name and adding “er” or “or” as appropriate. Sometimes we abbreviate to make the diagram more readable like the Trans. Disqualifier Role for Transaction Disqualifier Role.

For a common real-life example, consider the microwave in your kitchen. Typically, when you press the 1 button it will cook on high for one minute. The microwave does not know or care if anything is in it. Likewise, it does not care who or what pushes the 1 button. It behaves the same if you push it or if someone else pushes. It even behaves the same if a broom falls and hits the 1 button just right. In other words, you or the broom handle can play the “1 Button Pusher” role. Just about anyone or anything else can play the role also.

What happens in practice is that instead of use case roles, use cases are documented with actors that are either job titles or more or less well-defined sets of people. Job titles were used throughout the TAP use case example — even though they were improperly called roles.

Points of view matters! Roles are not defined by whomever or whatever plays them. Let’s test this out with a few examples.

• Who defines what playing the role Taxpayer for the Pay Tax use case within the US Tax system means? Do you? We don’t get to either!
• Who defines what playing the role Vehicle Driver for the Drive Vehicle use case on US roadways means? Do you? Or do legislators, the police and the courts?
• Who defines what playing the role Employee for the Employ Person use case at your place of employment means?

We trust you get the point by now. Roles are defined in relation to specific functionality, i.e., use cases, within a given system. For example, while legislators, the police and the courts define what driver means, in the US we drive on the right side of the road and in United Kingdom and Australia they drive on the left side of the road.

The system also matters. While this case study emphasizes role, it is intertwined with the concept of system. System and role are two of the three fundamental concepts of the Building Requirements Consensus™ Methodology. There is a price to be paid in using roles improperly with use cases. Let’s see how this plays out.

1st Change in Production Using Roles

If TAP were built using this description, the changes that happened as a result of feedback after the initial rollout can be implemented easily and without any negative side effects. We simply create a mapping from the Field Auditor to the Multiple Office Worker Role and the Something Doer Role. Field Auditors get the new functionality, two blue pluses, and there are no unexpected side effects.

In other words, the mappings from HR’s job titles to TAP’s roles are visual security requirements! TAP security simply needs to handle the mappings. We could, and I admit this is getting a bit radical, abstract out a security SOA service to do the mappings that is reused by new applications.

After we completed this use case example diagram, the very first person we showed it to controlled the security for people using TAP. He said “I agree with everything you’ve said so far. However, this will not solve the business problem.”

“What do you mean?” we asked in surprise. “After all, this diagram addresses all the issues described in the Change Request Form, doesn't it?”

An Unexpected Discovery!

“The problem isn’t that all Field Auditors need this functionality,” he said, “it’s that some individuals need this functionality.”

Immediately we redrew the diagram to look like the following one (you get extra credit if you figure it out before looking ahead! Here’s a clue: look at how the word role is used in the diagram above.) :

After looking at the redrawn use case example diagram, the TAP security manager snapped his fingers and said “I got it!” It clicked for him that even when the requirement changes from all Field Auditors to a set of individuals, represented by Jim, the Building Requirements Consensus™ Methodology handles it easily without code changes.

Applying the Building Requirements Consensus™ Methodology uncovered this new disconnect early in this third change to production software — before this round of coding started.

It cannot be emphasized enough that no new information was added to this use case example. The facts were present from the very beginning of the case study. However, the right connections were not made because of faulty analysis caused by using actors instead of roles.

What Is the Underlying Cause of These Problems?

During the TAP use case example, the underlying architectural principle of encapsulation was violated in the original way of thinking about the TAP use case example in Part 1.

Wikipedia.org describes encapsulation this way:
"In computer science, the principle of information hiding is the hiding of design decisions in a computer program that are most likely to change, thus protecting other parts of the program from change if the design decision is changed. The protection involves providing a stable interface which shields the remainder of the program from the implementation (the details that are most likely to change) … The term encapsulation is often used interchangeably with information hiding."

What exactly was not encapsulated that should have been in TAP? In the diagrams that apply the methodology, it is clear that the job titles belong to the HR system (actors) and not the TAP system (roles). The Human Resources department is responsible for defining job titles organization-wide. In the original requirements TAP knew about the job titles and the developers wrote code with that knowledge.

Actually it was worse than that. The original requirements in this use case example forced the developers to deliver code that was fragile to be compliant with those requirements. This is demonstrated in the case study when code had to be rewritten simply because a new functionality (role) was required by a person (user) in a job title (actor) in Part 1.

Contrast this with the ability of quickly documenting functionality applying the Building Requirements Consensus™ Methodology — without undesired side effects — when the TAP security person made his observation above in Part 2.

The Building Requirements Consensus™ Methodology explicitly identifies the systems involved and explicitly defines the use case roles.

A role is the relationship a user plays when interacting with a specific use case. It is an interface to the use case functionality from the perspective of the system the use case belongs to.

Any other entity that has access to a role (remember the role is an interface) can play the role. Now we have visual reminders to ask the right questions.

Frustrating Real Life Example with the Same Problem

If you have a web-enabled phone, you most likely have already experienced, or will likely soon experience, one these frustrating scenarios:

1. You call an organization to talk with a person whose extension you do not know. The automated answering system presents a directory option that you take. The directory service asks you to enter in the person’s last name. You type in the letters on your keypad only to be told that no one matches your entry.
2. You call your credit card company. The automated answering system asks the security question you answered previously “Enter the first four letters of the city of your birth.” You enter the four letters and are told your answer is incorrect.

In both cases, you know the answer and you know you entered it correctly. You may even try it again with the same result. What is going on?

Encapsulation Is Broken!

The answer is that encapsulation is being broken!

Automated answering systems were designed to respond to tone signals associated to specific keys on phones. After all, the phone keypad had remained stable for decades and it had three letters assigned to the numbers 2-9.

However, web-enabled phones do not use the "standard" keypad. For example, on the "standard" keypad the letter C is on the 2 key but on a BlackBerry the letter C is on the 7 key. Automated answering systems were built having direct knowledge of the "standard" keypad layout instead of defining an interface. This broke encapsulation.

There was no problem apparent until companies decided to sell phones with a different keypad layout. That exposed the design flaw in telephones that was being exploited by automated answering systems caused by broken encapsulation as the two scenarios above demonstrate. In a well-encapsulated solution, automated answering systems should not have direct knowledge of which letters are associated with specific keys.

Note that the problem of broken encapsulation in telephones was there throughout the decades. It just wasn’t exposed until a new keypad came along.

TAP Use Case Example Case Study Conclusion

In the TAP use case example, analysts high-jacked the term role and used to apply to job titles (actors) that do not belong to TAP the system they were documenting requirements for. Security was compromised and data was corrupted.

Even the title of the Change Request Form, TAP Role Upgrade, uses the term role inaccurately. As a result, business users could not do their jobs properly, these "solutions" tied up BA and IT resources and the benefit streams from TAP and other projects were pushed back.

When you use roles properly, you write requirements that enable systems to be designed and built that can respond to changes rapidly. If TAP had been built this way in the first place, even when the missed requirements were identified, the change would have been isolated to the security mapping instead of code modifications.

The original "roles" were not related to use case functionality. They are not roles as defined by the UML definition and the Building Requirements Consensus™ Methodology. They definitely are not roles of any part of the TAP system.

Instead, they belonged to an entirely different system. Therefore, those "roles" should never have been used in the first place when documenting requirements for the TAP system.

The Building Requirements Consensus™ Methodology strongly recommends that you only use the term role to refer to interfaces to use cases, with a one-to-one mapping, that belong to the system you are writing requirements for.

Requirements written this way add clarity because they explicit identify system boundaries to encourage asking the right questions and build consensus because the interfaces are visible to everyone involved.

As we have seen, this use case example applies the Building Requirements Consensus™ Methodology to enable the discovery of missed requirements — unlike traditional use case practice.

Summary

The solution was the better understanding and use of "user" and "actor" and "role". Ensure that their definitions are well understood:

Users:

• Represent the real people or entities who interact with the system.
• Can be individuals, organizations, or other systems.
• A single user can play multiple roles within the system.

Actors:

• Represent the roles or types of entities that interact with the system, rather than specific individuals.
• Actors are abstractions that represent the different ways a user can interact with the system.
• Actors are external to the system, meaning they are not part of the system's internal workings.
• Examples of actors include a customer, a bank employee, or a database system.

Roles:

• Represent specific responsibilities or capabilities that an actor can perform within the system.
• A single actor can have multiple roles.
• Roles help to define the different ways an actor can interact with the system.
• For example, a customer actor might have roles such as "viewer," "buyer," or "returner".