A.4 Refining the Requirements

This section describes our activities after the initial work of filling out the use cases is completed. We have questions listed in our notes that we will resolve, together with some opportunities for tightening the requirements, trimming scope, and making the system a more coherent whole. The next subsections focus on the changes we make to the filled use case, and where appropriate, explain our thinking behind these changes.

A.4.1 Investment Returns Calculation

After completing this round of detail-gathering, our fundamental view that this system is divided into data collection and reporting remains fundamentally unchanged. We realize that one important part of reporting ”returns ”can benefit from being examined more closely. Briefly, returns data will describe how an investment performed.

Property managers use calculation to determine how well their investments performed, and to predict how changes to an investment (for example, increasing the lease price) could alter that performance. The IRR is a standard business calculation for this task. We define IRR as the interest rate that makes net present value of all cash flow equal zero. ^[1] In the past, the operations manager has calculated the IRR in a spreadsheet. This is a time-consuming and error-prone process, as the IRR calculation uses the entire set of cash flows over the life of the investment. For leasing a building, this includes the initial principal used to acquire the property and every anticipated lease payment. For these reasons, adding the ability to perform this calculation to our system makes sense. We consider making a small use case just for this calculation, and plan to "attach" it to the reporting requirements use cases that include this data.

^[1] http://www.investopedia.com/terms/i/irr.asp

Use Case A.23 is the first draft of this use case.

Use Case A.23 Calculate Internal Rate of Return (IRR)

Use Case Name :	Calculate Internal Rate of Return (IRR)
Description:	IRR is a standard business calculation based on regularly occurring cash flows that results in a description of the return (%) on an investment. This calculation will be used by a number of reports .
Actors:	Reporting use case
Triggers:	A report that includes IRR is being generated.
Preconditions:	For this calculation to complete, a set of cash flows, including at least one negative cash flow, must be available.
Basic Course of Events:	The system checks that the required data is available. The first cash flow in the sequence must be negative. The cash flows must form a regular sequence (that is, monthly, weekly, yearly, or similar). Note that there will be other restrictions on the data that will only become apparent when the equation is analyzed by a programmer/designer to prevent errors such as "divide by zero." The system implements the formula and returns the result.
Exceptions:	2. If the system is unable to complete the calculation, it returns the value ERROR.
Postconditions:	The system either rejected the cash flows, returned an error, or returned the IRR.
Business Rules:	Cash flows from the company to other parties are considered negative; cash flows from external parties to the company, for example, lease payments, are considered positive.
Technical Requirements:	Speed-users will not be prepared to wait more than 2 minutes for a report to be produced.

So, with our draft of this calculating use case in hand, we consider how it will fit with our understanding of the requirements. Note that at this point we have avoided making any design decision on how the system will calculate the equation; we have also only defined the equation very loosely, and have instead told the business analysts and programmers that will inherit this set of requirements that they have some research to do to understand the equation, the various refinements to it, and any algorithms or heuristics developed by others to actually perform this calculation.

We attach this use case to our existing document for the reports.

Here we are stating that the Top Ten Properties and Expected Rate of Return reports will use the Calculate Internal Rate of Return use case. We also know that there are several other reports that will need to use this use case also.

Next we consider the requirement implicit in our use case ”that the returns data must be calculated each time it is used. Our motivation here is to understand if this indeed needs to be a requirement, or if this data could be stored by the system just like the "static" data about tenants.

Figure A.5. Reporting Enhanced

A.4.2 Tightening Requirements

If the underlying data changes (for example, if we discover that the operations manager entered an incorrect lease payment last year), the calculation must be redone. This observation leads us to define a problem ”the calculation results cannot be safely stored. This impacts the reporting requirements; IRR data may have to be treated differently than the other data. This affects the technical requirements for reports that include IRR since general reporting tools (Actuate and Crystal Reports to name two) are easiest to use when pulling data, via SQL, from a database system.

We discussed, with a subject matter expert, the likelihood of how and when data changes and determined that whenever data (capitalization and cash flow) change, we will require that the IRR be recalculated. We do not want to make a design decision at this point ”we are only gathering requirements ”so we alter the use case to capture our understanding of the business users' needs, and to highlight this area to ensure that people will notice it further down the lifecycle. Here is the altered form of the use case.

Use Case A.24 Calculate Internal Rate of Return (IRR)

Use Case Name:	Calculate Internal Rate of Return (IRR)
Description:	IRR is a standard business calculation based on regularly occurring cash flows that results in a description of the return (%) on an investment. This calculation will be used by a number of reports.
Actors:	Reporting use case
Triggers:	A report that includes IRR is being generated for one or more properties. Cash flow data for a property changed, and the IRR for that property will be included on a report. Capitalization data for a property changed, and the IRR of that property will be included on a report.
Preconditions:	For this calculation to complete, a set of cash flows, including at least one negative cash flow, must be available.
Basic Course of Events:	The system checks that the required data is available. The first cash flow in the sequence must be negative. The cash flows must form a regular sequence (that is, monthly, weekly, yearly, or similar). Note that there will be other restrictions on the data that will only become apparent when the equation is analyzed by a programmer/designer to prevent errors such as divide by zero. The system implements the formula and returns the result.
Exceptions:	2. If the system is unable to complete the calculation, it returns the value ERROR.
Postconditions:	The system either rejected the cash flows, returned an error, or returned the IRR.
Business Rules:	Cash flows from the company to other parties are considered negative; cash flows from external parties to the company, for example, lease payments, are considered positive.
Technical Requirements:	Speed-users will not be prepared to wait more than 2 minutes for a report to be produced.

There are many technical options available to tackle this problem. These will be explored by the team as a design task, and the decisions made can be made primarily on cost, since the baseline requirement has been calculated.

After reviewing the current set of requirements with the stakeholders, we dig further into some of them ”for example, the technical requirement for MSA ”and we find that this database is available in comma-separated format as a subscription that is updated regularly. Since the returns indexes available use MSA, it is important to the managers that MSA is kept current; therefore a new requirement appears to be the ability to automate the import of the MSA data. Further discussion reveals that it is not anticipated that the existing MSA for a property will change; therefore we do not need sophisticated automation to deal with this possibility.

Use Case A.25 Import MSA Data

Use Case Name:	Import MSA Data
Description:	MSA data defines broad location areas in the United States; they are less specific than cities and are closer to saying the "Greater NY area." MSA is important to us as organizations predict how profitable real estate investments should be based on their location. Our system tracks MSA data for each property, and we need to keep that information up-to-date, corresponding to its release by the United States Postal Service.
Actors:	Operations manager
Triggers:	A new data set is received.
Preconditions:	None
Basic Course of Events:	The operations manager loads the media containing the csv file. The operations manager navigates to the maintenance area and selects Load MSA from the system-supplied options. The system prompts the operations manager for the location and name of the csv file. The system reads the file and verifies that its contents are as expected. The system creates a backup of the existing MSA data set. The system copies the data from the csv file to its datastore. The system verifies that all MSAs in use by the systems set of properties refer to a valid MSA.
Exceptions:	7. If a property's MSA is not available in the new data set, the system alters the actor and identifies the affected property(ies) and MSA. The operations manager will research the problem and, if necessary, enter a new MSA for the affected property.
Postconditions:	The system contains an updated set of MSA data. All existing properties in the system refer to a valid MSA.
Business Rules:
Technical Requirements:

At this point, the requirements are sufficiently close to being available for realization that it is safe to begin work in the other system-development activities.