8.1 Inquiry Requirement Pattern
8.1 Inquiry Requirement Pattern
Basic Details
| Related patterns: | Report |
| Anticipated frequency: | 2–15% of requirements |
| Pattern classifications: | Functional: Yes |
Applicability
Use the inquiry pattern to define a screen display function that shows specified information to the user. The word "inquiry" implies that the information being displayed is not modified by this function.
Discussion
Inquiries are the pinnacle of a system, in the sense that you've gone to great trouble and expense to gather valuable information-and now you finally get to show it to people. Specifying a requirement for an inquiry is straightforward enough, though there's potentially quite a lot to say, which is described in the list of content that follows. But there's also the question of how to decide what inquiries we need. This is all too often a hit-and-miss affair, a wish-list of anything anyone can think of. A free-for-all can leave us with some inquiries that no one ever uses, while others that are needed are missed. Inquiry requirements are numerous, so it's hard to tell whether something's been forgotten. One way to be more systematic is to start with pervasive requirements demanding that every item of information be viewable on at least one inquiry (as described in the "Extra Requirements" section later in this pattern). This means we needn't worry about simple and mundane inquiries. We can then concentrate on inquiries for a specific business purpose. If we forget anything, there will be an inquiry of last resort to show us what we want, even if it's not ideally suited to the task at hand.
The bulk of inquiries are for stored information (data from the database), but they can also be for dynamic information about the state of the system's hardware and software components, or information from attached devices (card readers or credit card payment devices, for example) or any other source of information.
This book spells inquiry with an "i" consistently (rather than enquiry). This was an arbitrary choice, but having decided, it's useful to stick to it rigidly. It enables you search on "inquiry" and be reasonably confident of finding every one.
Content
A requirement that defines an inquiry should specify the following:
-
Inquiry name Give each inquiry an unambiguous name, so that separate inquiries don't get mixed up. Try to keep the name short, though this might not be possible if two similar inquiries must be distinguished from each other.
-
The business intent of the inquiry This is appropriate if the inquiry fulfills a specific purpose rather than being useful for a variety of reasons. An example of a multi-purpose inquiry might be a general customer details inquiry. The business intent can explain the circumstances in which the inquiry is intended to be used and by whom, which could be specific ("finance department") or general (any employee, customers). Properly capturing the intent of an inquiry is more important than its details (the next item), especially if it allows developers the opportunity to build one inquiry function that satisfies more than one of the inquiry requirements.
-
The information to show This refers to the values (fields) that are to be shown for each entity displayed (not to which entities are shown, which is covered by the selection criteria item that follows). Don't specify the inquiry's appearance, just its content. Make clear where this information comes from (typically the entity or entities it relates to) and what details to show about it. You don't always need to spell out every item of information. Describing it in general terms is often preferable ("full details" or "financial details," for instance), because it avoids the risk of missing something. A general description also remains correct if items are added later. If any item of information is to be calculated on the fly, explain how. If any items of information are to be highlighted (especially when they're in particular states), explain them. If totals and/or other summary information are to be shown for inquiries that show a list, specify them separately from the information for each item in the list itself.
Occasionally, it's worthwhile to mention information that is not to be shown or to state explicitly that only the information indicated-nothing else-is to be shown. Otherwise, if a prominent piece of information is not indicated, a developer might regard it as an omission and show it anyway. If there is a sound reason why certain information is not to be shown, it's a good idea to state that reason.
-
Sort sequence (Optional.) If more than one item can be shown, state the order in which they are to be shown. If the user can choose between two or more sequences, the requirement must say so. You might want to specify, as a desirable add-on, alternative sort sequences, in which one sort sequence could be specified in the requirement, and a refinement requirement (with a lower priority) added for the other(s).
-
Selection criteria (Optional.) Selected criteria can be either chosen by the user, fixed, or a mixture of both. If the user can control which items will be shown, specify which values can be used as selection criteria. For fixed selection criteria, describe what they are, and take care that the selection doesn't appear arbitrary to the user or vary from one request to another; for example, if the inquiry shows historic data, the user might be confused if the length of time covered isn't always the same or items appear and disappear at the beginning or end, apparently at random.
-
Navigation (Optional.) Describe any specific ways in which we allow the user to navigate around the inquiry (that is, internally within it) or to other functions (for example, to drill down to other inquiries or to invoke a maintenance function to edit the data). You can also describe how this inquiry is invoked-how users get to it-but only bother if there's something useful to say.
-
Interactions (Optional.) If there are any special ways in which the user can interact with the inquiry, describe them clearly. Specify only what these interactions need to achieve; don't get embroiled in detailed aspects of the user interface (buttons, hyperlinks, and so on).
-
Automatic refreshing (Optional.) If the inquiry is able to refresh the data it displays (without the user having to request it), specify how such refreshes are to be triggered. Typically, refreshes are triggered either by time (such as every 30 seconds) or when the underlying data itself changes-and it's important to specify which. If you suspect automatic refreshing might be difficult or costly (using the technology you expect, for instance), only demand it if it's really necessary. If this item is omitted, assume the display does not refresh itself.
This is quite a long list, with too many topics to cover in a single requirement-though few inquiry requirements involve more than half of them. As soon as an inquiry requirement grows unduly large, divest the rest into separate refinement requirements. Each of the last three topics often deserves its own refinement requirement if there is enough to say about it.
Template(s)
| Summary | Definition |
|---|---|
| «Inquiry name» inquiry | There shall be an [«Inquiry name»] inquiry that shows «Information to show». Its purpose is «Business intent». For each «Entity name», the inquiry shall show the following:
[The items to show shall be listed in «Sort sequence details» sequence.] [The items to show can be specified by entering any of the following selection criteria:
[The user shall be able to navigate «User navigation details».] [The user shall be able to interact with the inquiry «User interaction details».] [The information shown shall automatically refresh «Automatic refresh details».] |
Open table as spreadsheet This summary form is preferred to a verb-phrase form such as "View «Inquiry purpose summary»." This is because each inquiry needs a name-which the latter form doesn't provide, thus leaving an unknown someone, later in the project, to name it, and leaving us with no tie between that name and this requirement.
Example(s)
| Summary | Definition |
|---|---|
| Financial transaction inquiry | There shall be an inquiry that shows the financial transactions for a selected customer in a selected date range. It shall show a detail line for each financial transaction made by the customer in the time period, in reverse chronological order. Each detail line shall show
The inquiry shall also show the total number of transactions made by the customer in the period. The user shall be able to select any transaction shown and view its full details. |
| Recent orders inquiry | There shall be an order inquiry that enables a customer to view details about their recent and outstanding orders. "Recent" means all orders fulfilled or removed within a specified length of time. This length of time shall be a systemwide configuration parameter (set to, say, 30 days). This inquiry shall be accessible only by the customer who placed the order and by authorized employees. (In the latter case, the user shall select which customer to show orders for.) This inquiry is static; it does not refresh itself automatically. |
| Component status inquiry | There shall be an inquiry to allow an operator to view details of the current status of a single system component (such as a machine or server process). The details shown shall depend upon the type of component. This inquiry can be invoked either by selecting a component in some other inquiry or by entering its component name. |
Here's a refinement requirement that defines the refresh characteristics of an inquiry:
| Summary | Definition |
|---|---|
| Large order inquiry refresh | The large order inquiry shall redisplay itself, without user action with refreshed values, to maintain the timeliness of its content. This requirement does not state how this should happen (in particular, whether it redisplays periodically or values should be broadcast whenever they change), nor does it define what it means by "timeliness." If the inquiry refreshes periodically, rather than dynamically keeping itself up-to-date, then:
|
Extra Requirements
A single requirement (plus any refinement requirements) usually suffices for an inquiry-which is just as well, because inquiries are numerous and we don't want the number of requirements about them to explode. But there are a couple of topics for which pervasive requirements can usefully be specified, and these are discussed in the following subsections:
-
Comprehensive inquiries To prevent having to diligently specify an inquiry for every little piece of information, specify a few catch-all requirements to deal with everything you forget.
-
Common inquiry characteristics If there are rules that you want to apply to all inquiries, specify them once, such that they apply across the whole system.
The aim in both cases is to specify only once something we want, in general terms, rather than lots of times for individual cases. This both saves considerable specification effort and leaves out no part of the system.
Comprehensive Inquiries
The premise of this section is that all the information in the system should be viewable, one way or another. This sounds like a sensible goal for every system, but it's rarely asked for. Who knows how many systems actually achieve it: not many, probably. A system having information that no one can get at-or which none of its users knows is there-can be dangerous. Once an omission of this sort is discovered, it's often resolved by means of an ad hoc addition, without normal validation and security controls. These requirements act as insurance if we fail to specify a comprehensive set of inquiries, and demand a comprehensiveness of inquiry coverage rarely found in requirements specifications. Here are a few sample pervasive requirements of this kind:
| Summary | Definition |
|---|---|
| All information viewable in an inquiry | Every piece of information in the system shall be viewable in at least one inquiry. That is, there is to be no information that lurks inaccessible within the system. Pieces of information not to be displayed for security reasons (such as passwords, hashed data, or data encrypted using a key unknown to the user) or for other valid reasons are excluded from this requirement-but the presence of this information shall be indicated in at least one inquiry. |
| All information navigable for inquiry | There shall be a systematic way to navigate to every piece of information in the system and then to view it using an inquiry as per the previous requirement. That is, there is no information that lurks unknown in the system (even if the previous requirement provides some way to view it if only we knew how). The motivation for this requirement is to prevent a situation where we know something's in there somewhere, but we have no way to get to it. (For example, something that can only be displayed by entering its ID cannot be navigated to systematically if we don't know the ID.) |
| All user-accessible information viewable by that user | Every piece of information stored by the system that is accessible to a user shall be viewable in at least one inquiry to which that user has access. That is, there is to be no information that lurks invisible to a user who is authorized to view it. |
Note that if you have access control, there's still the possibility the system contains data to which no one has access-but that's a separate question.
These requirements cover business information, but one could, in theory, write similar requirements covering other kinds of things that are amenable to display in an inquiry-such as the status of hardware and software components. But this book does not attempt to go beyond business information because it's impractical to figure out just what constitutes all information for them, let alone whether it's worthwhile.
Requirements of this sort have wide-ranging implications-for developers, testers, and when estimating overall development effort: roughly speaking, for each kind of information (that is, each database table), an inquiry must be built.
Common Inquiry Characteristics
Specify only once any characteristic that you want all inquiries (or all inquiries of a particular type) to share, rather than requesting it repeatedly for each one. It saves time and avoids the risk of individual requirements differing. Ask for characteristics that are good practice or that you want to standardize across all inquiries in the system. Here's an example that insists that every inquiry not only show information, but also make clear what information it shows:
| Summary | Definition |
|---|---|
| Inquiry selection criteria displayed | Each inquiry shall make clear what it is currently showing. That is, it shall not merely display information; it shall also inform the user how the information was selected (in other words, what it means). In particular:
Any variable information shall form part of the inquiry display (rather than being obtainable in some other way) to permit the inquiry to be printed and still be equally meaningful. |
Considerations for Development
Check that the information is available.
Consider whether there are potential performance concerns.
If the display is to automatically refresh itself, how easy is it to achieve that in the prospective user interface environment?
Considerations for Testing
Testing that an inquiry requirement is satisfied must include displaying the inquiry to verify that it shows what it's supposed to.
Pay special attention to pervasive inquiry requirements, because they mean you must scour the system for all the inquiries they apply to-and then you must test that each inquiry complies. If there's a requirement that insists that every type of information in the system must be viewable by at least one inquiry, you have to go one step further and start by identifying all the types of information (which usually means all the database tables).
EAN: 2147483647
Pages: 110