7.3 Configuration Requirement Pattern


7.3 Configuration Requirement Pattern

Basic Details

Related patterns:

Data type, data structure, living entity

Anticipated frequency:

Up to 10 percent of requirements

Pattern classifications:

None

Applicability

Use the configuration requirement pattern to define parameter values that control how the system behaves.

Discussion

Configuration values are either systemwide or they are associated with configuration entities that behave very much like living entities-but the emphasis is on the values rather than the entities, and configuration requirements tend to reflect this. A systemwide configuration value is one for which there is only one instance: the same value is used everywhere in the system; other configuration values have multiple instances, each one used in a different circumstance. A bank might set a different cash withdrawal limit for each currency; in this case the currency is the configuration entity, and each instance of a currency has its own withdrawal limit configuration value.

A configuration value can exist at one of several degrees of flexibility, which run as follows (from least to most flexible):

  1. Hard-coded Values defined in the software itself are to be avoided. It's bad practice. Every configuration value must be modifiable so it can be set without involving developers. Do this even if you can't envisage it ever changing. Even if you're building a system just for your own company's use, the company might want to sell it if it's really nice; this has happened to systems in the past-only to run into severe trouble and embarrassment when hard-coded company-specific values come to light.

    A hard-coded value can occasionally slip in without anyone (even the developer) realizing. Pay special attention to calculation formulae. For example, bank interest calculations vary from one currency to another. (See the calculation formula requirement pattern in Chapter 6 for the gory details.) You need to be on your toes, especially if you're new to the industry you're working in.

  2. Systemwide For each systemwide value you identify, ask yourself whether it's genuinely a single value. Sometimes shortsightedness leads to parameters being made systemwide when they should actually vary-by country, by language, by currency, by customer type, by account type, by company, in some other way, or in a combination of more than one thing.

  3. In a configuration entity

  4. In several configuration entities (And perhaps systemwide, too.) This includes successive defaulting if the value isn't explicitly present at a particular level.

image from book
Don't Mess with a Running Production Line

Any change to a factory production line can upset its smooth flow-even bring it to a halt and smash things. A commercial computer system is like a production line, and its smooth processing of transactions and other everyday activities can be disrupted by a change made while it's running-a change to its configuration, that is-even if it's a sensible, necessary change. A configuration change function can, in extremis, behave like a self-destruct button-and, given the opportunity, someone will eventually press it.

So we need to consider the effect of the very act of changing a configuration value. In general, the more fundamental a value is, the more traumatic is the effect when it's changed. (In addition, the less frequently a value is changed, the less attention tends to be paid to the software that makes the change.) Imagine the effect if you suddenly changed the designated local currency, local time zone, tax rates, or the length of time before transactions are archived. Developers would probably consider these to be unreasonable things to attempt-but where does it say so? Unless the matter's properly addressed (starting with the requirements), users have no reason to suspect that normal use of some system function could cause trouble.

One answer is to examine each configuration value and decide when it's likely to be safe to change it. This can only be a guess at the time the requirements are written-so be conservative, and err on the side of being restrictive, because we don't want to raise expectations that are hard for developers to realize. Assign to each configuration value one of the following times at which it can be changed:

  1. At any time

  2. Only while normal processing is halted

  3. Only before the system goes live Some configuration values are so sensitive that they should be set once and never changed again during the life of the system. (An example might be the designated local currency.)

You might want to add other options relevant to your system. It must be clear which time category each configuration value belongs to. To avoid having to state it explicitly for every value, assume that (a) all systemwide values can be changed only while normal processing is halted; and (b) all nonsystemwide values can be changed at any time.

Some changes might have to be accompanied by the running of special conversion processing or by taking other extra steps-which might become apparent only during development.

Configuration editing functions must prevent any value being modified at the wrong time. To achieve this, we must be able to tell when the system is in each of these states: whether normal processing is underway or not, and whether the system has gone live or not. We then need one or more functions to switch the system between these different states. (Such functions can be useful for other purposes, too-such as shutting out users when the system experiences a problem.) We need extra requirements for these things; see the examples in the "Extra Requirements" section later in this pattern.

image from book

A couple of other recurring subjects have special considerations when applied to configuration:

  1. Access control Examine the access control needs for each configuration value. Don't simply assume that one important person will look after all the configuration, because it's risky to put control over everything into one person's hands. Give proper thought to organizing your configuration values, so that values with a related purpose are grouped together; it's not necessarily the same as the physical organization of the data. Separate the editing of sensitive, rarely-changed values from others, so they're harder to change by mistake. This is best worked out after all the configuration requirements have been determined, for obvious reasons. Grouping values according to when they can be changed is a good starting point. (See the user authorization requirement patterns in Chapter 11 for more.)

  2. Integrity Configuration, like all data, is best stored in a database. Recall the discussion about data integrity in the introduction to this chapter (Area 1). Storing configuration values in a flat file might be convenient for developers (especially if new types of values keep being added), but it's dangerous. Consider first what happens if you lose the disk that the file's stored on: what changes were made since it was last backed up? And second, when do changes take effect? If a configuration file is read into memory when the system starts up, will a change be read into memory straight away? If not, how do we cause it to? The whole situation is messy, and the best answer is to avoid the risk altogether: mandate that all configuration data is to be stored in a database. If developers really want the flexibility that they use flat files for, they can choose to store a whole configuration "file" as a blob in a database-but that doesn't by itself solve all these complications.

Content

There are two ways of structuring a configuration requirement:

  1. Define a configuration value, and then describe the level (or levels) at which it lives.

    This way is preferable purely because it focuses its attention onto a single aspect of configuration, which makes it hard to escape describing it properly. It also saves duplication if you want to configure a value at multiple levels. One drawback of this way is that it doesn't let you see together all the configurable values defined for a particular entity, which also means developers and database designers have to pull all the values together for themselves.

  2. Define a configuration entity, the whole of which forms part of the configuration.

    This way is more convenient if you have several items of information to specify at the same level, but it discourages saying much about each one.

A requirement for a configuration value needs to contain:

  1. Name and purpose It's important to make clear the intended use of each configuration value, especially where there are multiple values with similar meanings. If developers inadvertently use the wrong value, the resulting errors could be subtle and hard to detect; much damage could be done before it's sorted out.

  2. Representative value For a systemwide value, this is either the expected value (if this is known) or a sensible suggested value. It gives readers an idea of what we have in mind. It can sometimes stimulate useful discussion: someone remarking that it's not a realistic value might be a sign we've misunderstood something. These representative values can also be used when initially setting up the developed system, both for testing and for live use.

  3. Data type Either specify this in-line as described in the data type requirement pattern in Chapter 6, or refer to a separate requirement that defines a data type.

  4. Level(s) This is either "systemwide" or the name of the configuration entity to which the value belongs (per currency, per account type, and so on). A value may exist at more than one level; if so, explain how precedence (and perhaps defaulting, too) is to be handled. For example, if an approval limit is set for a person, use that; otherwise if a limit is set for a role, use that; as a last resort, use a systemwide default limit.

  5. When the value can be changed. See the preceding section "Don't Mess with a Running Production Line." Note the rules for what value to assume if the requirement doesn't say explicitly.

A requirement for a configuration entity contains:

  1. Entity name

  2. The purpose of the entity What is it, and what is it for?

  3. The entity's contents Write it in the form of a data structure. When each value can be changed can be stated explicitly as necessary. An example can be given for each value.

  4. How an entity is uniquely identified State its ID (or IDs).

  5. When the entity can be changed This applies to all the entity's values, except those for which it is explicitly overridden. If omitted, a default is assumed, as described in the preceding section "Don't Mess with a Running Production Line."

Every value in a configurable entity is regarded as a configurable value (we don't count its ID and supporting information such as last-changed-date as "values" in this sense), and configurable values live only in configurable entities. So none of the values in any living entity (say, a customer) constitutes part of the system's configuration.

Template(s)

The first template here is for specifying a single configuration value; the second is for a whole configuration entity.

Open table as spreadsheet

Summary

Definition

«Configuration value name»

It shall be possible to specify «Configuration value name» for the purpose of «Value purpose». This is a «Data type description» value (for example, «Representative value») and is «Configuration level(s) description».

[This value can be changed only «Change time description».]

«Configuration entity name»

The system shall store the following information about a «Configuration entity name» for the purpose of «Entity purpose»:

  • «Configuration value 1 description».

Each «Configuration entity name» is uniquely identified by «Entity identifier».

[Such an entity can be changed only «Change time description».]

Example(s)

Open table as spreadsheet

Summary

Definition

Local currency

It shall be possible to designate which is the systemwide local currency.

This value cannot be changed after the system goes live.

Cash withdrawal limit

It shall be possible to specify the cash withdrawal limit, which is a monetary amount expressed in local currency that determines the maximum value of a cash withdrawal transaction that a user can perform.

This value can be set for: (1) an employee; (2) an employee role; (3) a department; and (4) a systemwide default, such that if not specified at one of these levels, the one at the following level shall be used. It is optional at all levels except systemwide. It can be changed at any time at any level.

Currency details

It shall be possible to specify the following details for a currency:

  • Currency code, as per ISO 4217 (e.g. "USD"). Three characters long.

  • Descriptive name (e.g. "U.S. Dollar").

  • Symbol (e.g. "$," "A$"). Up to three characters are allowed.

  • Number of decimal places (e.g. 2). A number between 0 and 3.*

  • Interest calculation days in year (e.g. 360). Allowed values are 360, 365, and actual.*

  • Interest calculation days in month (e.g. 30). Allowed values are 30 and actual.*

* Values identified by an asterisk cannot be modified after the system goes live (though they can be entered for a new currency when it's being added).

Each currency shall be identified by its ISO 4217 code. The descriptive name shall also be unique (to prevent confusion).

Extra Requirements

See also the "Extra Requirements" in the introduction to this chapter.

Here is a pervasive requirement to enforce a "no hard-coding" rule:

Open table as spreadsheet

Summary

Definition

No hard-coding of parameters

No parameter used to control the way in which the system behaves shall be hard-coded in the software; systemwide variables shall be used instead.

A parameter for the purposes of this requirement is a value for which it is possible to conceive realistic circumstances in which a different value could be substituted.

Here are a few basic requirements to facilitate preventing configuration values from being edited at the wrong time:

Open table as spreadsheet

Summary

Definition

User access state

It shall be possible to specify what access by users is currently permitted. The allowed states are:

  • Normal access

  • Login not allowed Users already logged in can continue as normal, but no one else can log in.

  • No access allowed Users are not allowed to do anything.

Access by system administrators for the purpose of operating the system are unaffected by these states.

System processing state

It shall be possible to specify whether system processing is currently permitted or not. For the purposes of this and following requirements, system processing is processing carried out by the system itself as part of its usual operation.

Overall processing state

The overall processing state of the system is determined from the user access state and the system processing state. For the purpose of changing configuration, normal processing is deemed to be halted when no user access is allowed and no system processes are currently running.

System activity inquiry

There shall be an inquiry that shows current activity in the system. It shall show:

  • The number of users currently logged in.

  • The number of logged-in users for which the system is currently performing processing.

  • The number of system processes currently running.

System gone live state

It shall be possible to specify whether the system has gone live or not.

These requirements do not pretend to be adequate for proper system management.

Considerations for Development

Consider the effect of changing each configuration value while the system is running. If this might cause problems, take steps to prevent damaging changes from being made. Also publicize the potential danger, so everyone who ought to know does know and so that it is properly documented.

Introduce extra configuration values if you need to; it's perfectly natural for extra ways to control the system to arise during development. Don't hard-code values. Again, publicize any new value and have it properly documented.

Considerations for Testing

The testing of the basics of configuration-adding, modifying, removing, and viewing values-is essentially the same as for living entities. But once that's been done, test the effect of changes of configuration upon the functions that use it. As has been noted previously, changing certain configuration values can have profound effects-possibly very negative effects. Many of these sensitive things are systemwide variables, so take a look through all the systemwide variables for ones that look dangerous to modify.

Bear in mind that extra configuration values, over and above those specified in the requirements, might have been introduced during design and development.




Microsoft Press - Software Requirement Patterns
Software Requirement Patterns (Best Practices)
ISBN: 0735623988
EAN: 2147483647
Year: 2007
Pages: 110

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net