8.2 Report Requirement Pattern

8.2 Report Requirement Pattern

Basic Details

Related patterns:	Inquiry
Anticipated frequency:	2–15% of requirements
Pattern classifications:	Functional: Yes

Applicability

Use the report requirement pattern to define a report that shows specified information to the user. The information being displayed is not modified by the report-although it might involve some background generation of data.

Discussion

A report is a way of presenting information-it's very much like an inquiry, in fact, so we must begin by explaining the distinction. Back in the old days, it was clear: an inquiry was something you looked at on the screen, and a report, something you printed on paper. But no longer. Scrolling lets us manipulate large quantities of information onscreen, and reports are viewed increasingly onscreen rather than printed out. This is a trend we should encourage, to reduce use of paper, wear and tear on printers, time waiting for printing, and the security risks of papers falling into the wrong hands.

When you need to show some information to a user, decide whether to specify it as an inquiry or as a report. Make that decision on a sound, rational basis, rather than arbitrarily just because someone had one or the other in mind. Factors to consider are:

• Factor 1: How much information is to be shown? If it's a single item (such as details for one customer), an inquiry is more suitable; if it's an open-ended amount of information, a report is preferable. Also, if you need to show many columns of information, a report might be better.

• Factor 2: How interactive do we want it to be? Reports are passive (using current technology, at least). If we want to be able to change what we're looking at or to navigate elsewhere (such as by clicking on things), we should use an inquiry. And if we need the information to automatically refresh itself on screen, an inquiry is the way to go.

• Factor 3: How often do you need a hard copy? If printing frequently, make it a report.

• Factor 4: How many people need to see it? You can run a report, send it to other people, and be confident that they'll be looking at what you are; instructing them to run an inquiry is less dependable. You can also send a report to someone who doesn't have online access to your system.

• Factor 5: Do you need to be able to save the results? A report is more amenable to being stored than an inquiry is-though it depends partly on the nature of the underlying user interface infrastructure. (For example, an HTML page can be saved.)

• Factor 6: Where does the information come from? If it's not from a database, a reporting product might be unable to read it.

• Factor 7: How volatile is the information? If data changes frequently, a copy of a report will quickly become out-of-date.

• Factor 8: Is an inquiry or a report cheaper to implement? You should also be aware of the answer to this question, so that if all other considerations balance out, you can specify a requirement for whichever option is cheaper. Ordinarily, one might expect a report to be cheaper, because a reporting product usually comes with a report design tool to make creating a new report easier.

If you get conflicting answers to these questions, consider specifying both an inquiry and a report for the same information.

The reporting needed for a serious business system is often-and perhaps nearly always-inadequately specified up front. It's hard enough to figure out the transactions that drive the system, so it's not surprising that there's little enthusiasm for working through lots of secondary and less frequent activities. With new views of the business wanted regularly, reporting for management, sales and marketing, and other areas remote from day-to-day operations is frequently the most volatile part of a system. So don't expect the requirements to be able capture them all. But the clearer the picture you can paint, the better: give it your best shot. At least eke out all the sorts of reporting that are needed, and get a reasonable idea of the number of reports. Ways to go about this are to examine the following:

1. The people who might be interested in receiving reports: this could be a significantly broader group that those who actually use the system: finance people, auditors, management at all levels, system administrators, project managers (for error and system performance statistics and such), and human resources people. It might include people outside the organization, such as government and industry bodies, customers, agents, suppliers, and other business partners. Ask yourself who could conceivably have a legitimate interest in some aspect of what goes on in your system.

2. The activities needed to keep the business running: for the purposes of reporting, don't worry about the every-hour, mainstream activities, because they'll never be neglected. Pay special attention to operational activities that involve decision-making, because all such decisions are based on information-so try to identify what information is needed and what form would be most effective for it.

3. The strategic stratosphere: what sorts of-predominantly statistical-information would help those involved in directing the business (chiefly senior management and sales and marketing)? It's important to gain a good grasp of the expectations of the people at this level, because the scale and complexity of reports for them could have a significant impact on the overall size of the system. Also, the processing needed to generate such reports could be so intensive that it will have a noticeable impact on overall system performance; if a separate reporting system is needed to avoid this, we need to identify this as early as possible and cover the implications in the requirements.

It's not acceptable to write a sweeping requirement that covers multiple reports, especially if it's open-ended. Something like "a full set of finance reports" or "all reports required by the government regulator" are at best a hint that a lot is missing and are useless as requirements. If the specific reports cannot be pinned down, say so in informal text, not in a requirement.

Pay attention to special occasions on which reporting is especially important (especially ends of month, quarter, calendar year, or financial year). Don't make the mistake of getting the day-to-day reporting right and neglecting infrequent reporting tasks. Specifying "obvious" needs in a cursory manner could lead to reports that are unwieldy in practice and impose too great a workload on users during these busy times. Also, attempting to add these reports just before they are needed could unearth other omissions in the underlying system that cannot be fixed in time.

When investigating what reports are needed, you will gather much valuable information about who should receive them, how often, how many copies, how long they should be retained, and so on. These details don't belong in requirements because they are liable to change-and you should demand a system in which they can be changed at any time. But retain all the reporting information that is gathered, and use it when configuring the initial system. Concrete decisions on report production and distribution should be made in the lead-up to the system being installed, probably while it's being tested. If possible, let users experiment with a test system, to familiarize themselves with it. They can refine the reporting set-up and decide operational matters at that time.

Some organizations regularly print reports and file them away, or file away electronic copies so they can refer to them later as a last resort. This suggests the system itself isn't properly and reliably retaining information-that it has holes in its database design, often relating to historic data. It can also be a sign that users lack confidence in the system. Designing better systems diminishes this role for reports, so fewer reports might be needed. If you're specifying a replacement for an existing system, keep your eyes open for reports being used in this way.

Data Warehouse Magic

"Ah, we've got a data warehouse. We don't need to worry about reports." A data warehouse-if you haven't encountered one-is a data repository, typically driven by a relational database and either using a specialized product or built in-house, that's intended for rich querying. It might do clever things, but just because you throw everything you've got into them doesn't mean you'll magically get out the pearls of wisdom you seek. At some point, someone has to figure out what information is needed for a particular purpose and what massaging of the available data must be done to provide it. The earlier this is done, the better, which means specifying the information in the requirements.

Specifying necessary reporting in the requirements means that potential performance implications of intensive reports will come to light earlier, and testers will know what reporting to test. Reports added ad hoc later on will be subject to less scrutiny and control.

A traditional report prints numeric and textual values in a formatted manner. But reporting products are typically able to produce various kinds of charts, so don't limit your thinking to conventional presentation. Equally important, though, don't introduce charts just because you can and they're pretty-constraining developers by mandating a chart when they might find a more effective way of achieving the goal. Concentrate on the purpose and content, not on the presentation.

An important factor to consider when specifying a report is how many pages it's likely to contain when it's run in practice. When you have a large database, it's easy to devise huge reports with more pages than anyone can ever wade through. (Sometimes users are interested only in the grand totals at the bottom.) Reports that allow the user to specify selection criteria can turn out to be unexpectedly large due to the selection values entered. It's useful to be able to specify the maximum number of pages that are allowed and to warn users beforehand of potentially long or slow reports.

Content

A requirement that defines a report should specify the following:

1. Report name

2. The business intent of the report

3. The information to show

4. Sort sequence

5. Selection criteria

6. Automatic run details (Optional.) If the report is intended to be run automatically (without being requested by a user), state the frequency (for example, daily or monthly), describe who the report is to be distributed to, and indicate whether it can be run on request, too.

7. Totaling levels For which values do we want totals? Consider each level in the sort sequence and ask whether totals would be helpful whenever that value changes (for example, per customer or per currency).

8. Page throw levels Consider each level in the sort sequence and ask whether a new page should be started whenever the value changes.

The first five of these items are as described in the inquiry requirement pattern.

Template(s)

Open table as spreadsheet

Summary

Definition

«Report name» report

There shall be a report that shows «Information to show» «Selection criteria» sorted by «Sort sequence». The purpose of this report is to «Business intent». For each «Item type name», the report shall show the following: «Value name 1» «Value name 2» … [The items to show can be specified by entering any of the following selection criteria: «Selection criterion 1» «Selection criterion 2» …] Totals shall be shown for «Totaling levels». [A new page shall be started for «Page throw levels».] [The report is intended to be run automatically «Automatic run details».]

Example(s)

Open table as spreadsheet

Summary

Definition

Foreign exchange deal report

There shall be a report that lists all foreign exchange deals made in a selected time period (by the desk for whom the requester works). The report shall show the following information for each deal: Deal type Deal amount (including currency) Date and time Exchange rate Name of organization with which the deal was placed At the end the report shall show totals per organization and grand totals for the number of deals, and deal amount.

Extra Requirements

There are quite a few ways in which we might want to standardize all the reports created for a system. We can specify a pervasive requirement for each one we wish to insist upon. Here is a list of such requirements to consider including, some of which should be tailored to suit your environment:

Open table as spreadsheet

Summary	Definition
Reports security and privacy	All reporting functions shall comply with all stated security and data privacy requirements. It should not be strictly necessary to state this requirement explicitly, but we do so to stress the following implications of those requirements: No user should be able to produce a report that contains data to which they have not been granted access. Tools used to develop new reports should cause all reports produced with them to comply with all stated security requirements.
Consistent report layout	All reports shall adhere to a standard layout, which includes headings and trailers (footers). This layout shall allow for branding by the company (logo, company name, and system name in headings).
Reports show date and time produced	Every report shall show, on each page, the date and time it was produced.
Reports show parameters	Every report shall show all parameters used to control its generation. That is, it shall be possible to see which selection criteria were used (without which it's not possible to know what the report means).
Reports show recipient	Every report shall show the name of the person for whom it was produced. For reports produced upon request, this shall be the name of the requester; for reports produced automatically, the recipient shall be specified beforehand. If there are multiple recipients, it shall be possible to assign a name to the group, in which case the group name is printed as the recipient name in all copies.
Reports show degree of confidentiality	Every report shall show, on each page, a statement of its degree of confidentiality. Each report for which no confidentiality level has been expressly decided shall by default be regarded as "company confidential." This requirement does not imply the presence of a list of allowed degrees of confidentiality. It shall be possible to draw up a special statement of confidentiality to suit circumstances of a particular report (for example, "finance department confidential").
Report subtotals and totals	All reports shall show subtotals and totals where applicable.
Highlight amount overflows on reports	Where values exceed the space available, a consistent mechanism shall be used to show this fact (for example, "##########"). The purpose of this requirement is to prevent a partial value being interpreted as the full value. (Reports should, however, be designed wherever possible with sufficient space to accommodate the largest realistic amounts to prevent such overflows in the first place.)
Report page number	All reports shall show, on each page, the page number.
Report page count	All reports shall show, on each page, the total number of pages in the report. The intent of this requirement is to allow the recipient to tell whether pages are missing (when read in conjunction with the page number).
End of report line	All reports shall show an "end of report" line at the bottom. The intent of this requirement is to allow the recipient of a report to tell whether it is incomplete.
Capped data line	If data is omitted from a report because its size has been capped to a maximum number of pages, a line shall be printed at the bottom of the report to make this clear. No totals shall be printed after capping has taken place, since such totals are liable to be incorrect.
Reports on A4 paper	All reports shall be designed for printing using a laser printer on A4 paper with landscape orientation.

A further pervasive requirement can serve as a catch-all, to avoid having to laboriously specify in the requirements lots of rarely-used reports while at the same time demanding the creation of reports for data not explicitly specified in the requirements (for example, derived data generated for performance reasons):

Open table as spreadsheet

Summary	Definition
Comprehensive set of reports	All data stored within the system shall be accessible via the available reports (except data that should not be shown for security reasons). That is, if data exists, there must be the ability to view it on some report or another.

Considerations for Development

If a report writer product is used to deliver reports (which is usually the sensible thing to do), the development of each individual report is solely a matter of using the report writer's design tool. (If you're using an open source reporting product, the design tool-or tools-might come from different developers.)

Considerations for Testing

First, identify all the circumstances in which the report can be run, and then simulate all those cases. For example, different types of users might run a report in different ways, or a report might be run in a different way on the last day of the month or following a public holiday.

Testing that a report requirement is satisfied involves running the report for each identified test case to verify that it shows what it is supposed to.

Also test reports against the pervasive requirements that apply to all reports. This can be sometimes be simplified: if the reporting product used is able to guarantee that a pervasive requirement is always satisfied, then it doesn't need to be tested for each individual report.

For any report for which selection criteria can be specified, entry of those criteria should be tested in a similar manner to a data entry function. Test that each value is validated appropriately. Then test that the expected entities were actually selected.

Testing a report needs to go beyond verifying that it satisfies its original requirement. A report might achieve its business purpose but still be impractical to use. If it contains extra information, it'll probably still satisfy the requirement, but it might render it hard to read the important values. Selection criteria might add flexibility, but if users end up typing in the same values every time, it's inefficient. View the report from user's point of view. Does it fit well into their workflow?

Simulate all days on which additional reporting is performed (year-end, quarter-end, month-end, and so on).