7.1 Living Entity Requirement Pattern
7.1 Living Entity Requirement Pattern
Basic Details
| Related patterns: | Data type, data structure, configuration |
| Anticipated frequency: | Up to 5% of requirements |
| Pattern classifications: | Affects database: Yes |
Applicability
Use the living entity requirement pattern to define a type of entity for which information is stored and which has a lifespan (that is, is created, can be modified any number of times, and eventually terminated).
Do not use the living entity requirement pattern for any entity that is part of the system's configuration; use the configuration requirement pattern instead.
Discussion
A requirement for a living entity is primarily to define the information that needs to be stored for it (field by field), as well as related details such as how each entity can be uniquely identified (using IDs or other keys). Secondarily, a requirement for a living entity can also cover functions for editing (adding, modifying, and removing) and viewing an entity; these can be achieved either explicitly, or implicitly by the use of pervasive requirements that mandate such functions for all living entities. However, if there's anything particular to be said about any one of these functions, write a separate requirement for that function.
Content
A requirement for a living entity must define at least:
-
Entity name Make it clear, unique, and concise.
-
An explanation of the entity This is to make it clear what it is, what it's for, (and, if appropriate, also what it's not for).
-
The information the entity contains Present this in the form of a data structure. Usually the requirement itself defines the data structure, but it can alternatively refer to another requirement that defines it. In both cases, the data structure is as described in the data structure requirement pattern. These map roughly to the columns of a database table.
The definition of each item of information can also contain relevant details about the entry, validation, display of its value (including whether it is to be displayed at all), and/or such things as whether it can be amended after the entity has been added. Such information can be included in a requirement defining the data type in question if it applies to all occurrences of it (as per the data type requirement pattern in Chapter 6, "Information Requirement Patterns").
-
The way(s) in which an entity is uniquely identified State its ID (or IDs) plus any other ways of uniquely identifying it. (These later turn into indexes of a database table.)
-
Parent entity details (If any.) An entity of one type can sometimes only be created if some other entity already exists. A banking system might insist that a bank account can only be created if the customer it belongs to already exists. Describe the relationship with the parent or parents (because there could be more than one, and they could be different types of entity), including whether it is essential or optional.
Template(s)
| Summary | Definition |
|---|---|
| «Entity name» | The system shall store the following information about a «Entity name»:
A «Entity name» is «Entity explanation». Each «Entity name» is uniquely identified by «Entity identifier(s)». [«Parent entity details».] |
Open table as spreadsheet
Example(s)
| Summary | Definition |
|---|---|
| Basic customer details | The system shall store the following information about a customer:
Each customer is uniquely identified by its customer ID. |
Extra Requirements
See also the "Extra Requirements" section in the introduction to this chapter.
There are several kinds of pervasive requirements that can be written to apply to all living entities, to avoid having to specify them repeatedly for each type of entity. These are:
-
Editing functions We need to be able to add, modify, and remove an entity. Each function to modify an entity needs to identify which information can be modified (or, if it's more convenient, which cannot). If your system allows people to modify information about themselves, distinguish what they are allowed to change from what other users are allowed to change. For example, a Web shop customer might be able to change their personal details and preferences; an employee of the shop might be unable to change these things. Refer to the user authorization requirement patterns in Chapter 11 for how to specify in more detail who is allowed to do what.
-
Inquiry functions Specify one to list all the living entities of a certain type (or, if there are too many to list, some sort of selection or search mechanism), and one to display the details of a selected entity.
-
Change history This is typically a record of every modification to an entity (including adding and removing). It could either record every changed value (so as to have a complete picture of every change) or merely the fact that something changed. Knowing every changed value is attractive-but it's also a lot more development effort (and raises other matters-such as restricting access to sensitive information in change histories), so ask for it only for those entities for which it's justified. If in doubt, leave it out.
-
Common data These are items of information to be present in every type of living entity. They are typically used for information such as who last changed an entity and when.
If an adequate change history is maintained for each entity, common data identifying who made changes and when is not strictly necessary, because it can be derived from the change history.
-
Logical remove only When we ask for a living entity to be removed, we don't want all trace of it to disappear (because that might cause difficulties); we merely want it to behave as if it's no longer active. All respectable databases will prevent something from being removed if it is being referred to (that's called referential integrity), but we don't want it to be removed even if nothing refers to it.
Here are sample pervasive requirements for some of these things:
| Summary | Definition |
|---|---|
| Living entity last changed date and time | Every living entity shall store within it the date-and-time it was last changed. This value shall be updated automatically each time the entity is modified, and it shall not be possible for it to be modified in any other way (such as by a user changing it explicitly). |
| Living entity last changed user ID | Every living entity shall store within it the user ID of the user who last changed it. This value shall be updated automatically each time the entity is modified, and it shall not be possible for it to be modified in any other way (such as by a user changing it explicitly). |
| Living entity added date and time | Every living entity shall store within it the date and time it was added. This value shall be set automatically when the entity is added and never modified thereafter. |
| Living entity added user ID | Every living entity shall store within it the user ID of the user who added it. This value shall be left empty for any entity that was added as a result of customer action (such as a customer entity resulting for the customer self-registering). This value shall be set automatically when the entity is added and never modified thereafter. |
| Living entity change history | Every change to a living entity shall be recorded so as to build up a complete record of what values were changed, when, and by whom. |
| Remove means logical remove | Any living entity that is removed shall be logically removed only. The intent of this requirement is to allow details about any entity that has been removed to still be available when viewing historical data. For example, a report of user actions should still be able to show the names of employees who have departed. |
Follow-on requirements (for a specific living entity) can also be written for any of the first three kinds of pervasive requirement, regardless of whether a pervasive requirement has been written on the same subject. A requirement can override any of the pervasive requirements by stating which of them does not apply to a particular living entity or class of living entities. Similarly, for any of these standard functions, a requirement can be written to describe features needed by a particular type of living entity (or class of living entities). This requirement would then override the standard function as specified in the pervasive requirement. If you do this, check that it's clear that only one function of each type is needed for each type of entity: you wouldn't want developers to build one to satisfy the pervasive requirement and another for the specific requirement.
 |
A user preference is an item of information that is set by a user to indicate one aspect of how they wish the system to behave. User preferences should be encouraged, because they improve users' experience of our system by discouraging a one-size-fits-all outlook. A requirement for a living entity that represents a class of users (for example, customers) can be followed by requirements that define user preferences (one requirement for each preference).
A requirement for a user preference should contain:
-
Name A unique, descriptive, and concise name for the preference.
-
User class(es) To which users does this preference apply?
-
Allowed values, or data type Let a user avoid making a choice if they don't want to: let them choose "unspecified," "not applicable," or "I don't care," or for potentially impertinent information, "I don't wish to tell you."
-
Default value If the user doesn't set the value explicitly, what value will it have? If you've defined a non-choice value (such as "unspecified"), make that the default.
Don't ask a user to express a preference that's not used (for example, because the piece of software that would use it hasn't been written yet). If someone realizes that something they took the trouble to key in is ignored, they have a right to feel a little cheated.
It can also be worth writing one or more further requirement to ask for the ability to easily add extra preferences-at least to the extent that we don't have to modify the database structure each time-and perhaps a function for adding a user preference.
Here are three requirements that define preferences:
| Summary | Definition |
|---|---|
| Customer mailing list preference | A customer shall be able to indicate whether they wish to join the product mailing list, which periodically sends out emails about new products. |
| User time zone | A user shall be able to specify the time zone in which they reside. |
| Preferred notification method(s) | A user shall be able to specify by which means they wish to be notified of events pertaining to them. They shall be able to specify different notification method(s) for each event severity level. For each severity level, they shall be able to nominate one or more of the available notification methods. This requirement does not concern itself with which events each user is notified of. |
|
Considerations for Development
Even if no pervasive requirements have been specified for the topics discussed in the previous "Extra Requirements" section, you might regard some of them worth acting upon-simply as good practice.
Considerations for Testing
Check that add, modify, remove, and inquire functions exist for every living entity. There might be more than one function for each of these four things. A suitable range of tests needs to be prepared for each of these functions.
EAN: 2147483647
Pages: 110