techniques for automating gathering and coding of requirements

CASE Study: The Project Scope Document

Each software development methodology has been an attempt to make the building of software a predictable and reliable process. Few people who actually build software for a living have the time to produce and document a full-blown methodology. Few people who just talk about building software for a living have a sufficient grasp of the real world. This has meant that each methodology was optimized for the types of software that it’s designer built and in the environment they built it in (if any). When used to build different types of software or in a different environment, the results have been very inconsistent. Part of this reason is that each methodology was based upon certain assumptions that its proponents did not necessarily understand or communicate well.

John Zachman [2] developed a framework for understanding the software development process. His intent is to provide a way for us to understand the different types of work that must be done, and who it must be done for.

The framework is composed of six columns and six rows. The columns represent basic questions that need to be answered. The rows represent the types of persons who want answers to the six questions. The intersection boxes represent the types of deliverables necessary to answer the question for each audience.

Take a moment to compare your current methodology to this framework. Which portions of the framework are not addressed by your methodology? Think back about the big problems that you have encountered in your projects over the years. Did they originate in the framework boxes your methodology did not address? For many people, the answer is a resounding “Yes!”

Table 1 – Zachman Framework / Business Rule-based Software Development Process [3]

	What	How	Where	Who	When	Why
Project Sponsor	Major Business Objects	Major Functional Transformations	Business Locations	Major Business Actors	Major Business Events	Business Mission, Goals and Objectives
Business Line Expert	Fact Model	Tasks	Business Communications Map	Workflow Models	Entity / Object Life Histories	Policy Charter: Risks, Tactics, Policies
Business Analyst	Data / Object Model	Behavior Allocation / Object Model	Platform & Communications Map	Use Cases with Rules	Resource Allocation	Rule Book
System Analyst	Database Design	Program Specifications	Technical Platform & Communications Design	Procedure & Interface Specifications	Work Queue & Scheduling Designs	Rule Specifications
Programmer	Database Schema	Program Source Code	Network	Procedures & Interfaces	Work Queues & Schedules	Rules
System User	Operational Database	Operational Code	Operational Network	Operational Procedures & Interfaces	Operational Work Queues & Schedules	Operational Rules, Policies, Risks

Project Scope Document

An important difference between a military operation and a surgical operation is that the patient is not tied down. But it is a common fault of generalship to assume that he is.

Captain Sir Basil Liddell Hart, 1944

Some years ago I ran across an article about a professor whose students and colleagues would approach him asking him for employment references. Often he did not want to provide a reference because, frankly, it would not be glowing. If he told the truth about the colleague or student, he might lose a friend or get sued. If he wrote a nice reference letter, he would feel wrong because, after all, he had misled someone who was counting on his judgment.

What could he do? After thinking about it for a while, he decided that he could tell the truth and make the person who asked for the referral happy, too. So, he invented what he termed a Lexicon of Inconspicuously Ambiguous Referrals, LIAR for short. Here are some examples:

· You would be lucky to get this person to work for you.

· I am glad to say that this is a former colleague of mine.

· I can assure you that no one would be better for this position.

· I cannot say enough good things about this person.

· I most heartily recommend this person with no qualifications whatsoever.

Each of the above phrases can lead to two diametrically opposed interpretations. I use this story as an icebreaker when we want to take the time to properly understand the system requirements, but the users want to brush me off with the classic line, “It’s really very simple. Just go do it.” After they have a good belly laugh at the statements, I ask them whether they really want us to interpret their business without their active participation and review. The point is always thoroughly understood. [4]

The act of preparing for this document provides the necessary focus and agreement to have a successful project. This is your chance to build a team that will work together to achieve a common purpose.

The completed scope document acts as a “to-do” list and a reference to jog memories and help prevent scope creep. It also acts as an important legal document if things go poorly.

No matter what you do, requirements cannot be completely fixed before the system is built – if the goal is to build a system that will meet the needs of the business at the time it is delivered. Heisenberg’s Uncertainty Principle applies to software system development as well as the quantum physics of electrons. The very act of building a system changes the system that needs to be built.

That said, there is no excuse for doing a sloppy job of gathering requirements! Your work in this deliverable (as initially produced) should prove to be mostly correct at the time that the system is delivered. If you update copies of it as the requirements change (a good idea, by the way), the latest copy of it will be completely correct.

Table 2 provides a “you are here” roadmap for the Project Scope Document. The shaded boxes are dealt with by producing the project scope document.

Table 2 – “You are Here.” Zachman Framework for the Project Scope Document [5]

	What	How	Where	Who	When	Why
Project Sponsor	Major Business Objects	Major Functional Transformations	Business Locations	Major Business Actors	Major Business Events	Business Mission, Goals and Objectives
Business Line Expert	Fact Model	Tasks	Business Communications Map	Workflow Models	Entity / Object Life Histories	Policy Charter: Risks, Tactics, Policies
Business Analyst	Data / Object Model	Behavior Allocation / Object Model	Platform & Communications Map	Use Cases with Rules	Resource Allocation	Rule Book
System Analyst	Database Design	Program Specifications	Technical Platform & Communications Design	Procedure & Interface Specifications	Work Queue & Scheduling Designs	Rule Specifications
Programmer	Database Schema	Program Source Code	Network	Procedures & Interfaces	Work Queues & Schedules	Rules
System User	Operational Database	Operational Code	Operational Network	Operational Procedures & Interfaces	Operational Work Queues & Schedules	Operational Rules, Policies, Risks

Entry Criteria

Entry criteria are relatively lax for this deliverable.

Table 3 – Project Scope Document Entry Criteria

Entry Requirement	Comment
“a Need”	Someone must want something. We don’t have to know what it is yet, just that the need exists.
Knowledge of how to find out who has (or knows) the need.	Without this, things can’t go downhill because they are already at the bottom!

Sample Project Scope Document

As this will be the first sample document we show you, we will have to explain our method of presentation as well as explain how the project scope document is organized. That makes both of our jobs (ours to explain and yours to learn) a bit harder, but not two hard as long as we keep in mind that there are two different lessons being learned at the same time.

We will start by explaining our presentation method. Each page of the sample document will be printed just as it would appear in a real document, except for page headers and footers. There are two exceptions to this. First, the sample document pages are lightly shaded and have a border around them to make them visually different from the rest of the book. Second, we will have footnotes and placeholders for optional sections. The footnotes are used to explain a specific point in the document to you, they would not be used in a real document. Not every section is needed in every instance of every document. This is a methodology, not a religious catechism! Our sample documents are actually real documents that we used to build the tools and architecture.[6] When we deemed a section was inappropriate, we did not do it. However, we did leave a placeholder to let you know where that section would be placed in a document that needed it. Optional placeholders look like regular headings but are surrounded by < > characters.

Project Scope:

Software Development Request Management System

Prepared by: David Wendelken,

Carrie Anderson,

Ed Campbell,

Scott Knutsen,

Betty Baker

01-January-2000

Note: Grayed out items are considered out of scope for this project.

Cover Sheet

Problem Statement

                Our department receives requests for changes to existing software and requests for new software projects. Our           current manual method is inefficient and unorganized. It is not really managed, as individual programmers are
               told of changes to make rather than the department as a whole. Requests often lack critical information which
               delays their acceptance. Once a request is received, we have no easy way for the organization to find out what
               action is being taken (or not taken). We need to log requests from many remote locations, including home offices.

Mission Statement

Manufacture and sell stuff to make a profit in such a way as to encourage our customers to buy more of it from us.

Departmental Mission Statement

We will develop, maintain, and enhance software applications for the benefit of the organization we are a part of.

Business Objectives[7]

O-0001: Make a profit.

O-0002: Minimize costs.

O-0003: Maximize revenue.

O-0004: Be a market leader.

O-0005: Provide a good work environment.

Departmental Objectives

DO-0001: Track software development requests.

DO-0002: Provide request status to the organization as needed.

DO-0003: Initiate all software development requests in a uniform manner.

DO-0004: Have software developers be able to grab an requests to work on in between other assigned tasks.

DO-0005: Group software development requests for maximum development efficiency.

DO-0006: No approved requests wait for action for more than 1 month.

DO-0007: Requests are evaluated and approved or rejected within 1 month.

Project Goals

G-0001: Deploy an Internet/Intranet software request management tool that meets all objectives by 01-Mar-2000.

G-0002: Provide statistical measures of the quality of the project deliverables.

G-0003: Learn and use the Personal and Team Software Processes (PSP and TSP) for the project deliverables.

G-0004: Develop web-based technology skills.

Page 1 of 4

Major Business Objects[8]

Problem Statement

Request (Software Development)

Project

Document

Request Status History

Application

Code Unit

Action Item

Business Objective

Major Functional Transformations

Problem Felt by Organization into Problem Statement.

Business Need into Request.

List of Requests into Prioritized List of Requests.

Requests into Project Actions.

Major Business Events

Determine Business Need.[9]

Submit Request.

Evaluate Request.

Reject Request.

Approve Request.

Start Software Development Project.

Assign Requests to Project.

Major Business Locations

All Company Offices World-wide-web

Major Business Actors

Request Submitter System Analyst

Project Sponsor Programmer

Business Line Expert Application User

Business Analyst

Page 2 of 4

Goal and Objective Measurement Criteria

O-0001: Make a profit.[10]

O-0002: Minimize costs.

MC-0001: The request backlog is reduced without increasing development costs.

O-0003: Maximize revenue.

O-0004: Be a market leader.

O-0005: Provide a good work environment.

DO-0001: Track software development requests.

MC-0002: Zero complaints received concerning our having forgotten a request.

DO-0002: Provide request status to the organization as needed.

MC-0003: The status of a request can be determined by looking it up in the system.

DO-0003: Initiate all software development requests in a uniform manner.

MC-0004: All software development requests are immediately placed in the request management system.

DO-0004: Have software developers be able to grab an requests to work on in between other assigned tasks.

MC-0005: Developers evaluate and/or implement requests on their own initiative.

DO-0005: Group software development requests for maximum development efficiency.

MC-0006: The majority of enhancement or maintenance projects are composed of more than one request.

DO-0006: (MC-0007): No approved requests wait for action for more than 1 month. [11]

DO-0007: (MC-0008): Requests are evaluated and approved or rejected within 1 month.

G-0001: (MC-0009): Deploy an Internet/Intranet software request management tool that meets all objectives by 01-Mar- 2000.

G-0002: Provide statistical measures of the quality of the project deliverables.

MC-0010: The PSP and TSP statistical measurements will be collected and included in an appendix.

G-0003: Learn and use the Personal and Team Software Processes (PSP and TSP) for the project deliverables.

MC-0011: One team member will be appointed as the process manager. They will monitor whether the PSP and TSP method is followed and report weekly progress to the team.

G-0004: Develop web-based technology skills.

MC-0012: The tool is successfully built and works as designed.

Project Scope Document Sign-off[12]

I understand that development will proceed based upon the information listed in this document. Failure to include or exclude a relevant item within the project scope will adversely affect the project.

Role Name Signature Date

Project Sponsor ___________________________ ___________________________ _________

Project Manager ___________________________ ___________________________ _________

Business Line Expert ___________________________ ___________________________ _________

Page 3 of 4

Appendix: Definition of Terms[13]

Application User A person who uses an application for an authorized purpose.

Application A set of programs and their associated data that, together, act together to achieve a common purpose.

Business Analyst A person who translates business needs into business requirements.

Business Line Expert A person who knows and can articulate the business needs, and can judge the relative merit of the business needs and requirements.

Business Need An unstructured realization of something the business needs in order to perform its mission or achieve its objectives (at all or in a more capable manner).

Business Objective A situation that the business wants to consistently achieve.

Business Requirement A structured, complete and precise written explanation of a business need.

Code Unit A specific, named section of code. Example: a class, a program, a class method.

Company Office The physical location of the buildings the company uses to perform work in.

Problem Statement A description of the pain that the organization feels that would motivate it to undertake the expense and effort involved to build a software solution.

Programmer A person who translates system designs into software code.

Action Item An action that furthers the software development process, particularly in reference to a project or a request.

Project Sponsor A person who approves the project scope and is responsible for funding the project.

Personal Software Process (PSP)      Both the PSP and TSP are techniques provided under the auspices of the Software
                                                                Engineering Institute (SEI) out of Carnegie-Mellon University.   They focus on simple
                                                                techniques for managing and improving your own work (PSP) and for working with
                                                                others in a simple, yet effective manner (TSP). They stress incremental improvement
                                                          by measurement.

Project A way of grouping related work together in order to accomplish all of it more
efficiently.

Request (Software Development) A written, well-structured statement which describes a problem for which a software solution is desired.

Request Status History A record of the work started and completed in order to evaluate or implement a request.

Request Submitter A person who is to be contacted in order to clarify any information about the intent or purpose of the request.

System Analyst A person responsible for translating business requirements into a workable system
design.

System Design An explanation of what will be implemented in an application and how it will be implemented, written in terms suitable for developing software.

Team Software Process (TSP) See Personal Software Process.

Page 4 of 4

Now that you understand what is included in a Project Scope document, it is equally important that you realize what is not included in the document!

First of all (and least importantly), we did not list each and every business function. If we have a given business object called, for example, “Thing”, we can expect there will be, at a minimum, a “Maintain Thing” function and a “List Thing” function. So, we don’t waste our project sponsors valuable time listing the blatantly obvious. We do, however, make sure that our project sponsor knows that basic fact of the universe, because not all of them do!

More importantly, we did not address the issue of “how” we will achieve these goals and objectives. Our purpose in documenting the project scope is precisely so we will have a proper conceptual road-map for deciding just that!

Why don’t we put “how” we will achieve the goals and objectives into the document? Because we have nothing to gain and everything to lose. There may be different ways to get the job done and we may not have thought of the best one yet. If we have already locked ourselves in to how we will proceed, we may not be able to change direction and use the better way we discover as we delve deeper into the problem domain. If pressed to detail the “how” component, explain that they will get much better results if they tell you what they require the system to accomplish, then have you tell them how. Otherwise, they are asking you for a travel itinerary before they choose their destination! It is always best to use everyday analogies to explain why you won’t do what they have just asked you to. They may not have figured out software construction, but they do know that the travel agent can’t quote them a price until they say where they want to go.[14] Then, back that comment with a project plan for delivering the next Zachman row of deliverables in detail and the remaining rows with (inherently) less accurate estimates (or the promise to deliver such a plan by a specified date in the very near future).

Defining the Scope Document Components

Here are the major components of the project scope document. We’ll make a point of placing each component within the Zachman Framework. Table 4 presents a brief definition of each of the components. The subsections following this will provide more detail, examples, and guidelines for them. All of these components are important, but some of them are harder to do or get than others.

Table 4 – Project Scope Document Components

Component	Zachman Question	Zachman Audience	Prefix	Definition
Problem Statement	Why	Sponsor		A brief allusion to the pain that the organization is feeling that motivates it to undertake a project.
Mission Statement	Why	Sponsor	M- DM-	What the business does for its customers. Contrary to popular belief, this should not take a six month project just to discover. If we are discussing a subdivision of an organization, we might record two mission statements. One will be for the organization as a whole and the other will be for the organizational unit.
Business Objectives	Why	Sponsor	O- DO-	Each objective represents the steady, consistent condition that the business wants to be in when operating in the new, “normal” mode. It must be measurable to be meaningful. Again, we might have overall business objectives and specific departmental objectives.
Project Goals	Why	Sponsor	G-	Each project goal represents a transient condition that the business wants to achieve during the course of conducting the project. When the project is completed, the project goal disappears. It, too, must be measurable to be meaningful.
Major Business Objects	What	Sponsor		The major “things” which the business needs the application to deal with.
Major Functional Transformations	How	Sponsor		At this level, we will assume that if we have a “Thing”, we will need a “Maintain Thing” and “List Thing” business task. We are interested in recording business functions that are not so easily deduced. Calculate Payroll would qualify as a major functional transformation in a payroll application.
Major Business Events	When	Sponsor		Business events that occur and which we want the business to respond to in some (pre-scripted) manner.
Major Business Locations	Where	Sponsor		The physical locations where the project work will take place and / or any system component will be deployed. Sometimes, we put a list of “location types” rather than actual locations. For example, we might say “All Stonebridge Technology Offices” rather than list each office individually.
Major Business Actors	Who	Sponsor		An organizational unit, or a personal or organizational role that will interact with the system. Roles are usually preferable to units, and persons (by name) are never appropriate. Computer systems, however, are appropriate.
Goal & Objective Measurement Criteria	How	Sponsor	MC-	Subjective or objective criteria that are pre-defined and which actual performance can be accurately compared to.
Definition of Terms	What	Sponsor		A working definition for any term in the project scope document which will not be immediately, clearly, and consistently understood by the business staff members of the project team.
Document Sign-Off	Who	All		This is where the key parties on the project affirm that they are in agreement with the contents of this document. If they won’t agree at this point, the odds are not good that they will agree after you build the application.

Problem Statement

We define the problem statement as a brief allusion to the pain that the organization is feeling that motivates it to undertake a project. A great amount of detail is neither needed nor desirable in this information slot. Here are some sample problem statements along with who had them:

Who: Anyone who builds custom items or needs a custom item built. Our example is for software, if it was for a car, replace the word “system” with the word “car.”

Problem Statement: Requirements gathering is a difficult enough task without having to struggle to organize and present the results back to all interested parties. It is difficult to track where (or even whether!) each requirement actually gets implemented. In addition, when business requirements change in order to stay competitive, it is hard to understand what parts of the system may now be obsolete and need to be reviewed. Furthermore, after a system is built and its project team disbanded, much of the knowledge about why the chosen system design was made is lost.

Who: Someone who needs something build for them, because they can’t do it themselves.

Problem Statement: We need a software application custom built for our company in order to support our unique blend of products and services. We cannot build it in house because our staff lacks the necessary skills and/or they are already fully booked on other projects.

Who: Anyone who manages accounts receivables.

Problem Statement: We sell on credit to our customers, but they don’t always pay on time. We could keep up with it manually when we were a small company, but now that we’re much bigger, we just can’t. We need to streamline accounts receivables handling as well as our credit line determination processes.

Here are some questions that often get the information you need:

· What are your biggest problems?

· What other problems are you facing?

· <Golly![15]> That sounds really complicated! Is making that happen a real problem?

· Is there anything that just takes too long or is just too expensive that seems appropriate to mention here?

· What would you most like to change? Why?

The answers you get back may not actually get placed in the problem statement. They may get recorded as risks, policies, rules, events, or objectives. Go ahead and record them under the appropriate category as they show up, which will speed you up later in the project.

Mission Statement

We are often lucky enough to find the mission statement framed on the wall in the lobby or in the employee handbook, assuming someone can actually find their employee handbook. Determining the “mission statement” is not intended to be a nine-month corporate-wide study involving all levels of management and hordes of high-priced Big 6 consultants who wear expensive suits and play golf with the CEO. A simple sentence or two, which explains what the company produces and what value its products and services provide, will do. In a pinch, replace the word “stuff” from the sample mission statement with the product types the company sells. Here are some questions to help get a mission statement (or the makings of one) out of others. We’ll start with my personal favorite.

· Does your company already have a mission statement defined? What is it?

· Perhaps there is one in your employee handbook?

· What value does your organization provide to its customers?

· In very general terms, what does your organization produce?

Every organization produces something. For example, the US military produces security and, on occasion, domestic tranquility. However, documenting the true output of some organizations in writing won’t always be appreciated. You are sure to encounter some organizational departments that only produce jobs for the lazy incompetents who work there.

Business Objectives and Project Goals

A lot of people use the terms goals and objectives as if they are the same thing. That’s an interesting observation, because they are equally likely to say the phrase “goals & objectives,” which would be pretty redundant if they are one and the same thing! We consider them to be two different things.

Each objective represents the steady, consistent condition that the business wants to be in when operating in the new, “normal” mode. We might have overall business objectives and specific departmental objectives.

Each project goal represents a transient condition that the business wants to achieve during the course of conducting the project. When the project is completed, the project goal disappears.

Both must be measurable to be meaningful. (We discuss how to measure in 0.) Here are some sample Objectives and Goals:

Goal: Implement the system by <date>.

Objective: Be a market leader in our line of business. (Assumes they are and want to stay that way.)

Goal: Become a market leader in our line of business. (Assumes they are not and want to become that way.)

Goal and Objective: Become a market leader in our line of business and stay that way.

How important is it to determine whether it is really a goal or an objective? Not all that much. All will be revealed in the fullness of time. If it is a project goal, it will go away shortly after the project is completed and the goal is met - and no one will care. If it is an objective, people will still care about continuing to achieve it even after they already have achieved it. So, make your best guess and don’t worry in the slightest if you are wrong.

Objectives are prefixed with O or DO, depending upon whether they are for the organization or a department within it. We prefix project goals with at “G”.

Here are some questions to find out the goals and objectives:

· What are the overall business objectives?[16]

· What are your departmental objectives?

· Does your company already have a list of business objectives prepared?

· Does your company already have a mission statement defined? (Perhaps in your employee handbook?) What is it? (Goals and objectives are often written into mission statements although they shouldn’t be.)

· What are the goals for this project?

· How would we know we have succeeded?

· How would completing this project help out the organization?

· Is this a one-time achievement, or is there an ongoing need to achieve it? (This helps to tell the difference between a goal and an objective.)

Again, these questions will often provoke answers that will provide information besides goals and objectives. Record the other data in the appropriate place and carry on!

Major Business Objects

The major “things” which the business needs the application to deal with. Some technical folks like to call them “Objects”, others prefer the term “Entities.” Personally, I prefer “Thing”.[17] However handy the term, object-oriented is all the rage, so I’ll defer to the marketing gonzos and use the term “Object.” Here are some sample Objects from other applications:

· Invoice

· Check

· Bill of Lading

· Inventory Item

In relational modeling terms, an Invoice is often described as two entities: Invoice Header and Invoice Line Item. This document is certainly not the place to do that! In business terms, it is an Invoice. This is a business deliverable, not a system design deliverable, so Invoice it is!

Here are some questions to help you quickly get a list of potential Business Objects:

· What documents do you need to send to others, either inside or outside your organization? Do we need to keep a record that we sent them or what they looked like when we did? (That last question is one of the fundamental differences between a business object and a report.)

· What documents do you receive from others, either inside or outside your organization? Do we need to keep a record that we received them or what they looked like when we did?

Not all of the information that you will get needs to go into the scope document. Go ahead and record it for later, though.

Many of the items under other headings within this document may end up as objects. Actors, locations, and events are prime candidates. However, that’s a little secret for the technicians to use later, there is no need to be redundant in the scope document.

Major Functional Transformations

At this level, we will assume that if we have a “Thing”, we will need a “Maintain Thing” and “List Thing” task. These do not need to be recorded in the project scope document, although they do need to be listed in the project plan for the next phase of development. (With the full list of tasks that need to be analyzed safely recorded in the project plan, we can still justify the amount of time it will take to complete the system.) Instead, we are interested in recording business functions that are not so easily deduced. “Calculate Payroll” would qualify as a major functional transformation in a payroll application. “Select Customers for Mailing List” would be one for a direct mail advertising system.

The name of each transformation should follow this format: Action Verb Þ Business Object. Avoid verbs like handle, process, and do, as they are usually so vague as to be meaningless.

Major Business Events

When a business event occurs, the business needs to respond to it. For many events, we want the business to respond to it in a pre-arranged manner rather than just making it up as they go along. They are often initiated by an actor from outside the organization. Events should be listed in this format: Actor Þ Action Verb Þ Business Object. Here are some sample business events:

· Customer makes a complaint.

· Customer might place an order.

· Accounting receives an invoice. (Note we don’t care about the event “Vendor sends invoice.” because we don’t know about it. We only know when we receive it.)

Here are some questions that can help you to identify business events.

· What are some of the major events your business needs to respond to?

· Who starts the ball rolling? Why?

· What happens that requires you to respond? Who initiates it?

Major Business Locations

The physical locations where the project work will take place and / or any system component will be deployed. Sometimes, we put a list of “location types” rather than actual locations. For example, we might say “All Company Offices” rather than list each office individually.

Here are some questions to help you find out the locations you need to worry about:

· Where will the users of the application be located?

· Will people use the system from their homes or from portable devices?

· Is Internet access required? Are the users known ahead of time, or is the system for use by just anyone?

· Where will development occur?

· Where will the computing equipment be located?

· Is there an emergency backup site? Where is it?

Major Business Actors

An organizational unit, or a personal or organizational role that will interact with the system. Roles are usually preferable to units, and persons (by name) are never appropriate. Computer systems, however, are appropriate.

Why use roles instead of people? Because a person may perform many roles and their replacement, when the person moves to another job, may not have the skills to perform the same roles. Here are some sample roles:

Table 5 – Sample Business Actors

Type	Name
Personal	Accounts Payable Clerk
Personal	Accounts Payable Supervisor
Personal	Accountant
Personal	Chief Financial Officer
Organizational	Accounts Payable
Organizational	Accounting

In a project covering the entire accounting infrastructure, the organizational roles are probably the only ones that need to be mentioned in the scope document. That keeps the size of the document to a minimum. However, you should record the relevant personal roles when you learn about them.

Here are some questions that can help you find the business actors quickly:

· Who does that?

· Who might do that?

· Who should do that?

· Who provides this?

· Who do we send this to?

· Who needs to know about this?

· Who should not know about this?

Goal & Objective Measurement Criteria

Why have agreed measurement criteria before the project is built? What if we have a project goal that the system will have a fast response time? How fast is fast, exactly? Do we mean a three second response time for a data record to be queried and displayed on the screen, or do we want sub-second speed? This simple goal could have far-reaching effects upon how the system is implemented. It’s cheap to agree up front on what is meant by “fast.” It could be very expensive to discover sub-second response was needed at implementation time when a three second response time was planned for.

Measurements may be precise and they may be accurate. There may be a “causative association” or just a “correlation”. In addition, they may be subjective or objective. All these terms are important to understand when choosing measurements.

First, we will cover precision and accuracy. If I estimate I will finish a task tomorrow morning at 8:15 AM, that is a very precise estimate. If, however, I do not complete it until 11:00 AM, then it would not have been very accurate estimate. If I had estimated that I would complete the task “sometime tomorrow morning”, that would not have been very precise, but it would have been accurate. Thus, precision deals with the granularity of the measurement and accuracy deals with the correctness of it.

Stabbing someone in the arm with a knife will make them bleed. That is an example of a “causative association.” The action causes the result to occur. The result does not need to be certain, as in the example above, to have a causative association. By contrast, a correlation means that two unrelated items seem to act in a similar manner. For years it has been observed that the US stock market rises when women’s hemlines are rising, and falls while they are lowered. Neither situation “causes” the other[18], but they have tended to “co-relate” to some other phenomena. That doesn’t mean that correlations are automatically bad measurements, it just means that they are less reliable unless the reasons for their correlation are properly understood.

That leaves subjective and objective measurement to explain. First of all, we are using the term “objective” in a totally different context from that of “goals and objectives”. [19] An objective measurement criterion is something that is easily counted and therefore requires little or no “judgment”. Example: If we decide that a student learned the course material if they received a grade of “A” or “B”, we would be an objective measure. They either did, or did not, receive that grade. A subjective measure might be needed when wanting to know whether someone is “a good programmer.” Our measurement becomes objective if we measure their productivity and error rate; it remains subjective if we make a judgment based upon a “gut feel.” Objective measurements aren’t necessarily better. If, like some schools, the student is given an “A” just for breathing through the duration of the course, our objective measure might not accurately measure what the student knows. (In other words, there is a correlation between grades and knowledge, but not a causative association.)

Here are some questions to ask:

· How would we know we have achieved this?

· How could we measure this?

· Are there any weak points in using that measurement?

· Is the suggested measurement so well defined that 9 out of 10 people asked to provide their judgment would agree? (Use this for subjective measures, ask for 100% agreement on objective criterion.)

· How could we automate the measurement?

· How much effort or cost will it take to use this particular measurement?

· Is there a somewhat less reliable, but more affordable way to measure this?

Definition of Terms

Note that the project scope document does not contain any “excessive verbiage.” That is intentional. Project sponsors rarely have an excess of time to spend on any one topic. They need their information “short and sweet” and they appreciate those who deliver it that way.

However, just because those items aren’t defined in the project scope document doesn’t mean that you shouldn’t record them. Each of these items must have a brief definition recorded for it, similar to the definitions found in the project scope document appendix: definition of terms.

That said, it is just as important to have the definition provide meaning. Consider the following term and its definition: “Thing Type: A Type of Thing.” Entering in a definition like that is worse than useless, because it adds no value and just consumes time to write it. The definition must explain what is meant and why someone would care to know that information. Here’s another example: “Application User: A person who uses an application for an authorized purpose.” What does the definition add? First, we know a user must be a person, not a program. Second, the person is expected to have an authorized purpose for using the system. That adds quite a bit more than “Application User: A user of the application.”

Here are some questions to help you determine if your definitions are useful:

· What purpose does knowing this information serve?

· Why would anyone need to know this?

· Does it represent a “real thing” or a “definition about a real thing” or a “definition about a definition?”

· Does it use another term that hasn’t been defined?

· Is the definition just a sentence which rearranges the words in the term?

Why did we say that brief definitions are required for all the items on the project scope document? Wouldn’t that just be extra work? Wouldn’t that just slow down the process? Actually, the brief definitions speed up the process considerably and add extra value to the project as a free side effect of recording them. Let’s consider how that could be!

First of all, if you really understand the terms, writing a brief, one or two sentence definition shouldn’t take very long. With a bit of practice, you can really zip through them in a minute or two apiece. I spent about an hour defining all the terms used in the project scope document (the appendix and those terms defined in “Table 4 – Project Scope Document Components.” Then again, I’ve got lots of practice at this. Expect to spend about three hours for a similar amount of work until you’ve done it for a while. Tip: You can always look it up in the dictionary or thesaurus!

Of course, if you don’t really understand a particular term, you will know right away that you do not – because you will not be able to define it. This is your first quality assurance check. A single misunderstanding between team members here could easily consume three hours to fix later in the project. Given that there were 20 definitions for this document, what are the odds that all of the project team would have the exact same understanding of what the term entails? Failing to mutually understand just one term out of 20 is just a 5% failure to communicate. That’s quite a fine job of communicating, and not likely to be achieved often. With truly excellent (if not unattainable) team communication assumed, we have broken even on the time it takes to define the terms.

Now, what if we all agree as to the meaning, but we didn’t properly understand the term at all? Often, when we try to define an object, we discover the existence of other objects hidden in our partial understanding of it. (Not hidden in the object, mind you, but hidden in our failure to immediately understand its true nature.) Again, just one mistake here could easily consume three hours to correct later in the project. We are now at least 3 hours ahead in our actual project delivery timeline by taking the time to properly define the terms. We could be a month ahead if the mistake we just caught was a big one.

Note the very careful choice of words we made when we referred to our “actual project delivery timeline.” Note that we didn’t say we would be ahead in our “project schedule.” That’s because project schedules are usually based upon wishful thinking and subconscious appeals to a merciful God, not the likelihood of things going wrong and planning for mistakes to be made (and then corrected). We know we are human and that we will make mistakes. The more complex the application we have to build, the more mistakes we will make. It is foolish to pretend to make progress when all we are really doing is compounding errors upon errors until we discover (once again!) that nothing works very well when we perform a system test.

Getting back to projected time savings, how many technicians will be added to the project through implementation? Does each of them have the requisite business knowledge to understand each of the terms in the scope document? If not, how will they find out? Will you give them a verbal explanation? That might be more time-effective if only one person is to join the project or all new project staff join at the same time. If you have to explain things more than once, you will find it is faster to just hand them a copy of the project deliverables and tell them to read the appropriate portions.

And, of course, as things get hectic and you get worn out and inundated with subject area details, it becomes harder and harder to maintain the proper focus. What, exactly, are we supposed to be accomplishing? Is what we are doing at this level of detail consistent with what we scoped out? What did that term mean again? I understood it at the time… All of these common situations will take much less time with a properly done project scope document, complete with supporting definitions.

About the time things get hectic and you get worn out, you may be given a technical writer to prepare the documentation. Of course, they will know absolutely nothing about the business or your application. If documentation has to be delivered with the product, how will they write it? They will be too ignorant! Every term you define up front is another term that they won’t pester you about later, when you least have time to talk to them. More time savings!

Of course, if you don’t deliver documentation and you are going to remain on staff, you will never be free of the application. Every maintenance analyst and programmer that wanders through the application will have to interrupt you for information. If you want to work on new challenges, you will do better on them if you don’t leave an undocumented ball and chain attached to your work schedule.

And, of course, if you do get into a project scope dispute, it’s incredibly handy to have those definitions already written down. You may still have to include the new functionality, but your ability to negotiate additional time, budget, and resources will be much better than it otherwise would be. If your goal is to deliver the needed functionality on time and within budget, this one investment could easily save you a 25% overrun of the total project budget. Think about it!

In short, defining the terms used in the document improves your understanding of the problem domain. It is a fast and effective quality check that removes potentially costly errors while they are still very cheap to fix. It saves you time and effort every time a new person joins the project team, you get confused, or someone tries to change the scope on you (but keep the time, budget and resources the same). Not bad for a three hour investment!

The example we gave to illustrate the mathematics of compounding errors was a simple one. What would happen if we had a larger application? First of all, in our simple example, we were always optimistic about our ability to do things right and the likelihood of anything really going wrong. For a simple application with an experienced team, that might be a reasonable assumption. The larger and more complex the application, the less likely it is that an overly optimistic scenario will unfold. Instead, mistakes will happen with greater frequency and they will be bigger mistakes. However, the estimates for time to define a term remain largely the same. Thus, the larger or harder the project, the better the time savings you will get!

Document Sign-Off

Many years ago, long before I had learned the full range of requirements gathering techniques we present here, I was instructed to sit in on a meeting to scope out a new application that would bridge the operational gap between the departments of two senior vice-presidents. Both VPs were in the meeting and took an active part in the proceedings. At the conclusion of the meeting, I returned to my cubicle where my own boss asked me about what it would take to build the application that they wanted. My response surprised him: “Throw them into a room with a knife apiece, lock the door, and only open the door when one is left alive. Build what the one who survives instructs you to build. Either that, or assign me to sit in meetings with them for the next 6 months until I wear them down and they come to agreement to escape the meetings. At that time, we will start making progress on the application.” Personally, I thought my answer was clear and succinct. (It was also subjective and precise. As to accuracy, well, it might have taken 3-8 months to wear them down.) It was also, apparently, unsatisfactory, as my manager went to the next meeting instead of me. When he returned from the meeting, I asked him for his assessment of the situation. He smiled and said that he couldn’t spare me just to sit in meetings for the next six months. We focused on different projects for the next year.

It’s very important, if you are responsible for building an application, that all the key parties agree on what needs to be done or at least on what will be done (which isn’t always the same thing.) If that agreement isn’t in place between the key parties, the project will almost certainly fail. If you are an important technician on the project, rest assured that you would be blamed for it rather than the VPs! The trick is to make their disagreements visible early in the process so that they must either cancel it before many resources are wasted or come to agreement with one another. If it is obvious that the key business leaders are unsure of what business direction to take, then it is much easier to get them to recognize they need to come to agreement first.

Back to the story! A year later, my manager shrugged and sent me off to a meeting with the same VPs to discuss the same application. Nothing had changed except my ability to deal with the situation better. I realized that not only did the VPs involved have different organizational interests (which caused many of their differences), they did not trust one another. Each one of them was afraid to take a position because the other might use it against them. After all, good business practice requires the management of risk, and risk means that something could go wrong. Once I understood this was the true problem, I could manage the process better.

What did I do differently? Instead of asking each VP to sign off on the project documents, which would put them at risk, I went to each one of them privately and asked them if they would approve the document if no one else had any objections to the document. Each one of them agreed that they would. No objections were raised by anyone, so I went back and told them that no one had any objections. They could then sign off in equal safety and did so. (The project was a success.)

Defining Project Scope Components to Facilitate Automation

Placing the components in a requirements gathering tool such as we provide with this book is the first step in automating some of your work later in the project. To be effective for this purpose, the tool must either provide the necessary, built-in automation capability or it must allow you to programmatically access and manipulate the requirements data.

Note the careful choice of the word “data.” Once you store your requirements in a database rather than in word-processing documents, it becomes data, not just words on paper.

The first step is to make sure that all names and definitions are grammatically correct. If this is done, they can be directly copied and pasted into the relevant user help text and documentation. Depending upon your documentation requirements, you may even be able to programmatically extract them and place them in draft user reference manuals and user help text.

In our Oracle Designer environment, we store the Project Scope document as (surprise!) a “Document.” The non-boilerplate items that appear on the document are stored as document associations. We extended the document association within our Designer Repository to add two flags: one covers whether the object is “in scope” (the default is yes), and the other flag covers whether that item should be listed in the appendix covering the definition of terms.

Check out our paper on our document generator in the conference proceedings (Generating User Understandable Documents from Designer) where we cover the particulars of how we extract this information directly out of Designer and turn it into a Project Scope Document. There are several advantages to this approach. They are:

· The information is only entered once in the CASE tool where it can be directly used to build the application.

· The CASE tool and the Project Scope Document work off of the same definitions, so when one changes, it changes everywhere.

· By copying the document (and its associations) inside the Repository, you can get a new version of the Project Scope Document by just adding additional document associations or changing the in scope flag on existing ones.

· All Project Scope Documents have the same format, so staff only have to be trained once to learn how to read them.

· The document format is clear, crisp, and concise. Anything longer will not be read and is unlikely to be understood.

· As more projects are completed over a period of time, you will build up a database of components that are placed on scope documents. Since they are stored in a database, they can be shared with other projects very easily.

Exit Criteria

Table 6 – Project Scope Document Exit Criteria

Exit Requirement	Comment
Grammar has been checked.	The names of all the items in the document are properly spelled. The definitions are syntactically correct.
Definitions exist for all items.	Each and every item mentioned has a proper definition written down.
Definitions are useful in business terms.	A total stranger reading the term and its definition will understand what the term means and can provide a real business example to demonstrate the meaning.
Items are crosschecked with one another.	For example, no functional transformation refers to a business object which has not been defined. Business events are not performed by actors who have not been defined.
Scope document is believed to be complete and correct by all parties.	All notes have been cross-checked against the scope document. Standard data or business models, if available, have been used for comparison. Actual working document samples have been cross-checked for missing items.
Signatures	The key players agree that the document accurately reflects the high-level requirements of the system.

CASE Study: Business Rules: Analysis to Code

Setting up a Business Rules Playbook

What is a Play Book?

In sports, the play book is tactically action-oriented and contains a short-hand version of the cooperative knowledge of the team. That statement was very precisely stated, and we must very carefully analyze it.

First, it is tactically action-oriented. It does not discuss strategic theory or the greater social context of the game. Its focus is on short-term tactical operations.

Second, it is short-hand version. It enables coach, captain and team members to communicate a complicated set of pre-planned actions quickly and unambiguously. There is little leisure for long explanations while in the midst of a game, even less so for planning. Time is of the essence. So, too, is accuracy, for the game will be lost if the players have different understandings of what each is about to do.

Third, it is cooperative knowledge. It does not incorporate the rules of the game, nor does it include the intricacies of how an individual can best kick, throw, or catch a ball. It does not cover how the rules of the game will be enforced. It covers what the team does together, so that their actions are coordinated and thus more powerful than they would be in isolation.

Fourth, it is a book of plays. As a book, it can be opened and referred to at need. It is a repository of information. It contains plays. Plays have a plot, a story to tell, and depend upon actors to fulfill appropriate roles in order to reach a denouement. In a crunch, a new play can be improvised out of the building blocks of other plays, with each role having a reasonably certain and accurate expectation of its part in the new drama.

What is a Business Rule?

The term “business rule” is now beginning to be fashionable and thus subject to all the abuses of techno-babble and buzzword compliance. To avoid this, let’s go back to basics and start our definition from there. What is a rule? There are two divergent meanings to the root word that are of interest to us.

First, “to rule” meaning “to govern.” Rulers constrain our behavior, forbid or command courses of action.

Second, “a rule” as in “a measure, a ruler.” Rules provide consistency in how we measure for all the benefits that can give us in communication and reliability.

Thus, a business rule is a rule about business, in particular, about how a business must or should operate, or how it takes measure of its situation.

Just as a law does not have to include why it was promulgated, or for what purpose, so it is with business rules. Even as a law without proper context invites abuse when it is interpreted, so can a business rule foster inefficiency when it is enforced in inappropriate situations. But, that particular issue is outside of the scope of this article. (Remember, a play book is tactically oriented and does not cover the greater social context or the strategy of the game! We invite you to check out our website www.casetech.net for papers covering those aspects of using business rules, and others.)

What is a Business Rule Play Book?

Well, one obvious answer is that it is a book full of business rules. That’s a darn good guess, but not quite right! If this were a business-oriented audience, we would focus on just that. As you are, by and large, an audience composed of technicians, our focus is somewhat different. A sports book does not contain actual plays where an actual person performs an actual task at an actual point in time; it contains the pattern of a play, its definition, if you will. Thus, by analogy, the business rule play book we are discussing is a book of rule patterns. Each rule pattern describes a standardized snippet of behavior, typically in the context of a standardized business or technical situation.

Rule Patterns

Sample Rule Pattern Definitions (with Sample Rules)

I’ve always found that using examples from personal life works better than more academic or business examples. The examples seem to stick in student’s minds better. Perhaps that is because real life is so much more amusing than business or academia could ever be! Of course, real life can be much more scandalous, too! The sample rules have been chosen to amuse or annoy, as the case may be, on the premise that any adrenaline surge from a technical article is a welcome relief!

Our rule pattern book has nearly a hundred patterns in it, and I expect to reach one hundred and fifty by the time rule patterns dealing with user interface issues are defined and added in. You are welcome to visit our web site, www.casetech.net, to get the current list of business rule patterns that we use.

Pattern Mnemonic	Description and Example
A and B	If one of the data items in this set is filled in with a non-blank value, all of them must be filled in with a non-blank value. “If the name of the significant other is supplied, the gender of that person must also be supplied, and vice-versa.”
A or B	Only one of the set of data items may have a non-blank value. “Men may record a wife’s name or a girlfriend’s name, but not both.”
B if A	A data item cannot have a non-blank value if another data item is blank. “Address Line 2 must be blank unless Address Line 1 is filled in.”
MinMax LE	One data item must be less than, or equal to, another data item, if both are filled in. “Divorce Date must be on or after Marriage Date.”
No Overlap	The data record has starting and ending range values, which must not overlap with another set of rule-specified data records. “A wife may not have more than one husband at a time.”
No Cousin	Two or more different relational paths back to the same "ancestor" entity exist. None of the specified relational paths may be traced back to the same data record in the specified "ancestor" entity. “A person may not marry someone who has the same mother.” (The reverse of this pattern is the Cousin pattern, where the paths must trace back to the same record.)
Data Subset Definition	The data for the entity is subdivided into "business sets" which correspond to a subset of the data records based upon an algorithm specified in the rule. This is used as a way to filter out unwanted data records. A specific rule poses the question: “Is this record a member of the set?” and provides the information necessary to answer it correctly. “A person is a marriage prospect if they are currently single, have a steady job, and have no debilitating diseases.” Other Data Subset Definition rules may be needed, such as “Is this disease debilitating?” and “Is this a steady job?” The sample rule could (and should) invoke them as part of getting its answer. That way, the sample rule automatically stays up-to-date when how we determine if a disease is debilitating changes

The rule patterns mentioned above are primarily “data validation” oriented. However, the last pattern mentioned is definitional in nature. It defines a question of interest and how to answer it. Rules that answer questions (which may be for data subset definitions or formula calculations) are a very useful way to organize code, because any program that needs to know the answer can just ask the rule. This provides a single point of change for application creation and maintenance purposes. In fact, properly done, many programs become fairly small control frameworks that just ask a series of rules for guidance and action. This is structured design and programming on steroids, but without the health risks!

Sample Rule Play Book

Here is a sample. In order to be successful, the rule patterns must be expressed generically. They are implemented in actual rules specifically (tied to specific data elements), but the patterns themselves must be generically defined. This presents a training problem, because until someone is exposed to this type of thinking and practices it for themselves as a matter of routine behavior, a generic definition will often not be understood. If it is not understood, or understood quickly, the method will not be adopted in the real world. Our solution is simple and straightforward. Every time we describe something generically, follow it up with a specific example. The constant switching back and forth from generic and specific instances of the rule pattern helps to learn the generic pattern quickly and exercises the very analytic skills we want to foster.

Rules do not exist in a vacuum. They must be associated with an event or with specific data elements. Thus, each sample rule will be provided with a sample data model to illustrate where the rule is attached. Each sample data model is simplistic and minimalistic. It contains nothing more than needed to illustrate the pattern.

Our actual rule patterns are a bit more complex than the ones shown here. We provide for the use of pre-defined keywords that represent “standard architectural plumbing code.” This allows our code generators to insert the correct boilerplate code (and to update that boilerplate code) without having to go back and change all of our rule patterns. For example, we have keywords that represent a standard exception handler, standard variables for rule identification, standard code to check to see if the rule has been disabled at runtime, and other standard architectural behavior.

Generic Rule Pattern Expression

If one of the data items in this set is filled in with a non-blank value, all of them must be filled in with a non-blank value.

Sample Rule Expression

If any of these fields is filled in, then all of them must be filled in: home address, home city, home state, and home postal code.

Generic Functional Specification For Rule Code

FUNCTION is_<rule_mnemonic>_ok

(pi_<a_value> IN <a_value_datatype>

,pi_<b_value> IN <b_value_datatype>

)

RETURN <rule_result_integer>

;

-- returns '0' if complies with the rule,

-- returns error message '9' otherwise;

Sample Functional Specification For Rule Code

FUNCTION is_home_addr_ok

(pi_home_addr IN person.home_addr%TYPE

,pi_home_city IN person.home_city%TYPE

,pi_home_state IN person.home_state%TYPE

,pi_home_postal_code IN person.home_postal_code%TYPE

)

RETURN INTEGER

;

Generic Functional Code

CREATE OR REPLACE FUNCTION Is_<Rule_Mnemonic>_Ok

(pi_<a_value> IN <a_value_datatype>

,pi_<b_value> IN <b_value_datatype>

)

RETURN <rule_result_integer> -- 0 = success

i_return INTEGER := 0;

BEGIN

IF pi_<a_value> IS NOT NULL

OR pi_<b_value> IS NOT NULL

THEN

IF pi_<a_value> IS NULL

OR pi_<b_value> IS NULL

THEN

i_return := <error_integer>;

END IF;

RETURN i_return;

END;

Sample Functional Code

CREATE OR REPLACE FUNCTION is_home_addr_ok

(pi_home_addr IN person.home_addr%TYPE

,pi_home_city IN person.home_city%TYPE

,pi_home_state IN person.home_state%TYPE

,pi_home_postal_code IN person.home_postal_code%TYPE

)

RETURN INTEGER

i_return INTEGER := 0;

BEGIN

IF pi_home_addr IS NOT NULL

OR pi_home_city IS NOT NULL

OR pi_home_state IS NOT NULL

OR pi_home_postal_code IS NOT NULL

THEN

IF pi_home_addr IS NULL

OR pi_home_city IS NULL

OR pi_home_state IS NULL

OR pi_home_postal_code IS NULL

THEN

i_return := 9;

END IF;

RETURN i_return;

END;

Now, you might be saying to yourself about this time, “Hey, if they’re so big into generic code, how come they aren’t using a generic piece of code to handle this? Perhaps a generic rule package?” The answer is that we do! Remember, however, that this is a general purpose explanation of the technique to an audience of widely varying skillsets. After teaching this technique for several years, I’ve found that it’s best to introduce it as simply as possible at first. After the programmers get the hang of it, they start clamoring to “improve it with generic routines”. That’s when I know that they have bought in to the concept!

Generic Code To Test The Rule for a Rule Approval and a Rule Violation

When we code a rule, we are writing code to handle a number of possible situations. We need to test as many possible situations as we can affordably do so, because catching errors when we code the rule is cheaper and faster than catching them in other programs that depend upon the rule.

This is a bit of a brain teaser, but if we have coded a rule to handle a “failure situation”, and we get the failure result when we should, we have a successful test. Conversely, if we get a success result from the rule when we should not, we have a test failure. Communicating in double negatives is fraught with peril, so I avoid it. To do so, I speak of Rule Violations and Rule Approvals. Thus, we check to see if our behavior is approved by the rule or if our behavior violates the rule. If we get what we are testing for, we have a Test Success, and if we do not, we have a Test Failure.

Because we cannot expect that every developer who joins our team comes pre-trained knowing how to test their own code correctly and efficiently, we provide sample test scripts that cover basic situations that would let us know the rule has been coded correctly or not. These sample scripts provide an excellent, pragmatic way to train new staff in professional techniques. In addition, many (but not all) of these sample scripts can be called from a master script to use for regression testing. (Some rules require data dependencies which makes including them in such a script several orders of magnitude harder to achieve.)

We start with a generic script, then provide a sample of its use.

Generic Test 1: Rule Success where all input is not null.

SELECT

is_<rule_mnemonic>_ok

(pi_<a_value> -- non-null value

,pi_<b_value> -- non-null value

) rule_result

,0 desired_value

,DECODE(is_<rule_mnemonic>_ok

(pi_<a_value>

,pi_<b_value>

)

,0,’successful test’

,'TEST FAILURE'

) result

FROM DUAL;

Sample Test Script 1: Rule Success where all input is not null.

SELECT

is_home_addr_ok

(‘611 Pennsylvania Ave, SE’ -- home addr , non-null value

,‘Washington’ -- home city , non-null value

,‘DC’ -- home state , non-null value

,‘20003’ -- home postal, non-null value

) rule_result

,0 desired_value

,DECODE(is_home_addr_ok

(‘611 Pennsylvania Ave, SE’

,‘Washington’

,‘DC’

,‘20003’

)

,0,’successful test’

,'TEST FAILURE'

) result

FROM DUAL;

Sample Test Script 1: Output if Code is Correct

RULE_RESULT DESIRED_VALUE RESULT

------------ ------------- ---------------

0 0 successful test

Sample Test Script 1: Output if Code is Wrong

RULE_RESULT DESIRED_VALUE RESULT

------------ ------------- ---------------

9 0 TEST FAILURE

Generic Test 2: Rule Success where all input is null.

SELECT

is_<rule_mnemonic>_ok

(pi_<a_value> -- null value

,pi_<b_value> -- null value

) rule_result

,0 desired_value

,DECODE(is_<rule_mnemonic>_ok

(pi_<a_value>

,pi_<b_value>

)

,0,’successful test’

,'TEST FAILURE'

) result

FROM DUAL;

In the interests of brevity, the sample code to implement this test (and the following ones) has been omitted from this article, as has the sample output of those tests.

Generic Test 3: Rule Violation where first input is not null, remaining input is null.

SELECT

is_<rule_mnemonic>_ok

(pi_<a_value> -- non-null value

,pi_<b_value> -- null value

) rule_result er

,9 desired_value

,DECODE(is_<rule_mnemonic>_ok

(pi_<a_value>

,pi_<b_value>

)

,9,’successful test’

,'TEST FAILURE'

) result

FROM DUAL;

Generic Test 4: Rule Violation where last input is not null, remaining input is null.

SELECT

is_<rule_mnemonic>_ok

(pi_<a_value> -- null value

,pi_<b_value> -- non-null value

) rule_result

,9 desired_value

,DECODE(is_<rule_mnemonic>_ok

(pi_<a_value>

,pi_<b_value>

)

,9,’successful test’

,'TEST FAILURE'

) result

FROM DUAL;

Automating the Finding of Actual Rules

The most amazing thing about parsing a data model for business rules is that it can be so very easy to find a lot of them! (We wish we could say it’s easy to find all of them.) Theoretically, the key is to know what to look for. Pragmatically speaking, the key is to be consistent in what you will find. Puzzled by that cryptic turn of phrase? Good! I’ll explain.

What is the essence of our job as software application developers? It’s not designing data models or even programming. We assert that it is something far more fundamental:

1. We find the inherent, repetitive patterns in what our users need to accomplish.

2. We ascertain the rules that underlie those patterns.

3. Then we apply computer power to automate those patterns.

This is incredibly important, for if there are no repetitive patterns, and hence no rules, we cannot automate the user’s task(s). Period. Since, for this purpose, we are the user, our attempt to automate will be successful only to the extent in which we have consistent, repetitive patterns to discover! This explains our cryptic conundrum earlier. If our data models are consistent in how we model similar situations, we can easily automate based upon that consistency. If they are not, we must code for each and every variation on a theme. Although that is theoretically possible, it is not cost effective compared to a more patterned, disciplined approach.

How can we reconcile that concept with the fact that every application is different? First of all, although different, each application has similarities with all other applications. Our approach is a mixture of two techniques:

· Consistent naming conventions

· Data tables to store the naming conventions.

For example, I use a simple database to store patterns of domains or column name fragments that indicate the likely presence of a business rule in a particular pattern. For example, let’s say that I find two attributes in the same entity with the same datatype, “date_effective” and “date_expired.”. One of them has a name (or domain) whose name contains one of these words: “begin”, “start” or “effective.” The second attribute has the same name, except that a different “key word” is found in it: “end”, “expiration”, “expired” or “termination.” What are the odds that we have found the presence of an actual rule in the MinMax LE rule pattern? Remember, that is the pattern which states that one of two data items must be less than, or equal to, the other.

This approach lets us adapt our rule-parsing utilities to the specific vocabulary of an application while rewarding us for
re-using the same names for the same purpose. It also lets us adapt the utilities to a data model produced by someone else (although consistent naming conventions by others is a rare treat...). For example, any attribute or column named “Active_Indicator” or in a domain of the same name will retain the value gained from our utilities. However, if we inherit an application where the column name was “Active_Flag”, we can alter the rule data tables to accommodate the new rule pattern.

Automating the Coding of Actual Rules

Let’s assume that we want to enforce many of the rules in the database. (Actually, it doesn’t matter where we want to enforce them, the principle and the techniques I describe still apply!)

If we enforce the rules in the database, we might choose to create a business rules package per data table along with a set of database triggers for those tables. If you are not familiar with the Oracle Designer generated TAPI (Table Application Programmatic Interface), it does just that, but only enforces “business rules” on the table that are built into the Designer Repository (such as upper case, the use of a sequence to generate a value, checking domain values, etc.).

We chose to create an additional business rules package for each table that piggybacks upon the Designer TAPI. We did this because several of our clients used the TAPI and this would be the easiest way for them to keep their current code investment and transition to our techniques.

Much of the code in each business rule package is very similar to the code in every other business rule package. Basically, the names of the tables and columns change, but the basic code is the same. Each business rule is typically implemented as a function or procedure in the appropriate business rule package. Each business rule package has a “rule_check” procedure that the database triggers invoke. Rule_check is responsible for invoking the rules at their proper time.

We built a business rule package and database trigger code generator. Each business rule that we record in Designer is transformed into a “stub” business rule function in its corresponding table’s business rule package. Since each business rule is attached to a business rule pattern, the stub includes the sample code from the business rule playbook. (At some point in the future, we will make it smart enough to substitute the correct object names for their corresponding keywords in the playbook sample code.)

Because the sample pattern code is not compilable (due to the presence of keywords), the code generator comments it out and adds a bit of dummy code to return a success value. That allows us to start testing the coding of our first rule without having to code all of them first, which is a little refinement that is always greatly appreciated by the developers when it is pointed out!

How do we store Business Rule Patterns and Business Rules in Designer?

Both rules and rule patterns are stored as documents. Rule patterns have names that start with two exclamation points (!!). Rules have names that start with a dollar sign ($). This makes them sort together in a useful way, allows us to write programs looking for them, and gets the patterns to show up at the top of a list of values for documents.

We have used a number of user extensions to the documents and to the document attachments. For rule patterns, we have added text extensions that allow us to store the sample rule code.

For business rules, we added indicators to determine whether the rule should be enforced in the client, the middle tier, or the database, and whether the rule should raise an error, a warning, or just produce information. Relationships, attributes, domains, events and rule patterns can be attached (associated) to the rule via a document attachment.

Relationships, attributes and domains are associated as parameters to the rule. We added user extensions to the document attachments to let us know whether the parameters are input/output, need the new and/or old values for the record, and the order in which they should be listed.

Events tell the rule check routine when the rule should be enforced. We set up some standard rules for the twelve database triggers attached to each table, plus the database commit triggers and one to just record that the rule is enforced “on demand”.

The business rule package generator makes use of the above information as it constructs a business rule package. Each iteration of the code generators removes yet another set of standard grunt work from the software development process.

One colleague, Brian West, has just completed a first draft of a script to automate part of the creation of database test scripts for the rules as a training exercise on how to use the Designer API. As you can imagine, we are pretty excited to get that into use!

Conclusion

The potential to re-engineer and automate large portions of the software development process is tremendous. I have focused on portions of our methodology that illustrate how quickly and easily much of the repetitive aspects of our work can be automated - once the output of many of our development tasks is treated as data instead of documents or as code. This is the true lesson to learn from our paper, that we as a profession need to treat our work products as data just as we do those of our customers, the users of the applications that we build.

As for the business rules portion of our work, note that we identified patterns to our own work, the rules governing those patterns, then changed our work habits to facilitate automating our work and then applied computing power to do so. I invite you to check out our website, www.casetech.net, for additional papers detailing other aspects of our work.

About the Authors and CASEtech

I. Michael Snyder is the vice-president of CASEtech, Incorporated, an Oracle Designer solutions provider since 1994. His 20+ years of systems development experience includes Oracle Designer, Oracle Forms, Reports, Web Server, WebDB/Portal, PL/SQL, and database administration. Michael taught Database Concepts at George Washington University. He is proud to serve as a Bronze Pelican award-winning Scoutmaster for Troop 772 in Wheaton, Maryland.

Michael is currently serving as vice president of the Mid Atlantic Association of Oracle Professionals. He has presented dozens of papers at local, regional, and national conferences including MAOP, MAOP/CASE-SIG, ECO, SEOUG, ODTUG, IOUG-A, Open-World, and NPUG. He recently earned an award for the best Designer presentation at ECO/SEOUC 2000. His talks have been well received by attendees and are generally directed towards Oracle Designer and Forms technicians. Michael's techniques have been used on small and large projects alike. He values his ability to work well with developers of all levels of experience whether in a mentoring capacity, or simply in providing new insights to peers and colleagues.

David Wendelken is a Principal Consultant with CASEtech, Inc. He is the co-author of a book about Oracle Designer and the author of over fifty publications dealing with software development methods and techniques. He served on the ODTUG Board of Directors and as its journal editor for many years. David is an eclectic reader, a poet/philosopher, and a wood-worker who especially enjoys working with the lathe.

Lee Hirz is a Consultant with CASEtech, Inc, a technical editor for the magazine M Computing and an adjunct faculty member at the University of Maryland University College. He has over 20 years of experience doing application development for CACI, Inc (Accounting and Project Management), Compucare and the Department of Veterans Affairs (medical information systems and electronic mail). Lee runs long distance and coaches youth baseball.

CASEtech, Inc. is a consulting firm that specializes in custom software development and Oracle technology training. CASEtech staff routinely present at technical conferences and publish articles about software development issues, techniques and practices.

Authors’ note: Although there are three of us who authored this paper, in the text we decided to use the more personal first person singular, “I,” as opposed to the more formal first person plural, “we.”

[1] This section, and the following two sections on the project scope document and information flow modeling are an extract from a book in progress by David Wendelken, Betty Hilbrant Baker, Ed Campbell, and Carrie Anderson. They are included with their permission. They retain the copyright.

[3] You might want to check out the website www.brsolutions.com. Ron Ross is a major contributor to business rules theory, and his company’s web site always has interesting business rules material on it. We’ve modified the Zachman Framework that is presented by his company. You might also want to check out the courses that they offer on business rules definition as well as their books. Both are excellent.

[4] Wendelken, David and Anderson, Carrie The Oracle Designer/2000 Handbook, Addison-Wesley, 1996, pg 14.

[5] Yellow boxes are detailed in the deliverable.

[6] That means we are using the method to build tools to support using the method and to teach the method. Do you think we might be serious that this method actually works?

[7] Almost all business objectives trace back to these statements but are typically “customized” to the organization.

[8] Note that we do not define the business objects here. They should already be understood by the parties involved, as you use their own terms wherever possible (and accurate). However, if the terms are new to the business, not well understood by the business, or different groups within the business use different names for the same concept, define your terms in an appendix. We have included an appendix defining almost terms because you and I didn’t actually sit down together to figure out what needs to be done, so I can’t assume much prior knowledge on your part.

[9] Note that this item, while listed, is grayed out and is therefore out of scope. Marking out of scope items in this manner is a useful technique. That way, no one can come back later and say, “Of course it is in scope! Everyone but you knows that a system to help us auto-magically determine what we want is part of a Request Management System!” Well, actually, they can come back and say it, but you can easily prove that it was not in scope.

[10] By shading this objective, we are noting that measuring it is out of scope of this project.

[11] Enough said. It is measurable as stated.

[12] The sooner you get a written, formal buy-in, the better. If they won’t agree to the project scope at this point, it’s better to find out now rather than later!

[13] Note that, since we have already defined many of the terms earlier in this paper, they do not have definitions here. That is because they are now considered “terms commonly understood by the business staff.”

[14] The same situation is true when interviewing for a job. Never answer the question: “How much did you make in your last job” or “How much do you expect to make here?” You have nothing to gain and everything to lose. They already know what salary range they can offer. If you quote a number that is too low, their offer will be lower than you could have gotten from them. If you quote a number that is too high (but would happily accept a lower offer), they won’t hire you because they think you will be unhappy with their offer and jump ship at the first opportunity. The proper answer, no matter how hard they press, is “I want a fair wage for the valuable services I will provide to your company. Make me an offer based upon what I am worth to your company. If the only reason I will not accept the offer is based upon the salary amount, I will tell you that and we can negotiate further if you wish to.”

The above example is not a digression; it is another example of a good negotiating technique. Anyone who is involved in determining or maintaining the project scope knows that, given no constraints on time or resources, the system should “do everything auto-magically.” This is because constraints require prioritization of scarce resources. In the example above, the recruiter must prioritize minimizing salary expense with filling the position quickly. Your answer lets them know that you understand their dilemma and will work with them to avoid a catastrophic mistake on their part (which would be losing out on hiring a highly qualified candidate like yourself over a few thousand dollars). They know they can’t make an offer that is too low or it would insult you (particularly since you handled them so professionally), so they are unlikely to name the lowest figure in the salary range to start with.

[15] Use the culturally appropriate exclamation of dismay and commiseration upon hearing about some horribly convoluted situation.

[16] Always start off with the easiest and most obvious questions first! Sometimes you get lucky!

[17] To be fully accurate in all contexts, I prefer Morticia Addams to “Thing”.

[18] More accurately, it has not been proven or disproven to cause the correlated effect.

[19] Hey! Don’t complain to us. We didn’t invent these terms and the confusion that they cause! We’re just telling you about them.