1. Requirements and boilerplates
Tor Stålhane
IDI / NTNU

2. Content Requirements specifications
Why are requirements specification difficult
Templates – boilerplates and guided natural language
Guided natural language – GNL
Boilerplates
Boilerplate examples
How to communicate requirements – use cases and beyond

3. Requirements specification

4. Goal tree – 1

5. Goal tree – 2

6. Goal tree – example

7. Goal description

8. Why are requirements difficult

9. What is the problem
Effects of Inadequate Requirements development – Airbus:
Requirement: Reverse thrust may only be used, when the airplane is landed.
Translation: Reverse thrust may only be used while the wheels are rotating.
Implementation: Reverse thrust may only be used while the wheels are rotating fast enough.
Situation: Rainstorm – aquaplaning
Result: Crash due to overshooting the runway
Problem: erroneous modeling in the requirement phase

10. The challenge
The main challenges in Requirements Engineering for large systems are that:
There are many requirements – often several thousands.
Several requirements are interdependent
Requirements are related to two or more of:
Hardware – computers, sensors, actuators, machinery
Software – control, measurement, logging
Operators – procedures, behavior

11. Brake by Wire System – 1 Requirement - Natural language:
moving
Requirement - Natural language:
On a blocked wheel the brake shall be released within 100ms, while the vehicle is moving.

12. Brake by Wire System – 2
WSS = Wheel Sped Sensor

13. Templates Boilerplates and Guided Natural language

14. Humans and machines – 1
Given the amount and complexity of RE, we need to automate as much as possible.
Humans and machines have different strong and weak points.
We want to elicit and analyze requirements in a way that allows both parties to build on their strong sides.

15. Humans and machines – 2
We have focused on the differences between man and machine for requirements elicitation and formulation – understanding, observing and reasoning and requirements analysis – memory, information processing and consistency
Area
Man
Machine
Understanding
Good at handling large variations in written material
Bad at handling large variations in written material
Observation
General observations, multifunctional patterns
Specialized observations, quantitative data
Reasoning
Inductive, slow, imprecise but with good error correction capabilities
Deductive, fast, precise but with bad error correction capabilities
Memory
Innovative, general access
Copying, formal access
Information processing
Single channel, less than 10 bits per second
Multichannel, several megabits per second
Consistency
Unreliable, gets tired, depends on learning
Consistent, do not get tired, repeating several actions
Force
Low level, maximum 1500 watt
High level over a long time period
Speed
Slow, reaction times in seconds
Extremely fast

16. Humans and machines – 3 Machines are
good at observing quantitative data and being deductive, fast and precise. In addition, they are good at doing consistent repetition of several actions.
bad at handling variations in written material and pattern recognition.
Humans are good at handling variations in written material, being inductive. In addition, they are good at doing error correction.

17. Motivation for use of templates – 1
Text has the advantage of unconstrained expression. There is, however, a need for common
Understanding of concepts used to express the requirements and relations between them.
Format of presentation
Lack of common understanding makes requirement specifications expressed as free text prone to ambiguous representations and inconsistencies.
TDT 4242

18. Motivation for use of templates – 2
Template based textual requirements specification (boilerplates) will introduce some limitations when representing requirements but will also reduce the opportunity to introduce ambiguities and inconsistencies.
Boilerplates
Provides an initial basis for requirements checking
Are easy to understand for stakeholders compared to more formal representations
TDT 4242 18

19. Requirements – 1 There are three levels of requirements:
Informal – e.g. Natural language (NL): free text, no rules apply
Semiformal
Guided Natural Language (GNL): free text but allowable terms are defined by a vocabulare
Boilerplates (BP): structured text and an ontology – vocabulary plus relationships between terms
Formal: e.g. state diagrams or predicate logic
TDT 4242 19

20. Requirements – 2

21. Template based textual
BPs and GNL – 1
Template based textual =
Semantics
Syntax + +
Meta Model
Keywords:
Reflects requirement, system and domain concepts
RMM
Refinement
Specialization
Guided RSL
Boilerplates
Analysis
Correctness
Completeness
Consistency
Safety analysis
Requirements expressed on templates
Uses predefined templates based on concepts, relations and axioms to guide requirements elicitation
Example:
The <system function> shall provide <system capability> to achieve <goal>
Requirements expressed using a vocabulary guide
Uses predefined concepts, relations and axioms to guide requirements elicitation
Example:
The ACC system shall be able to determine the speed of the ego-vehicle.
Ontology: General and SP specific
Requirements classification
System attributes
Domain concepts

22. BPs and GNL – 2
Guided Natural Language and Boilerplates will reduce variation and thus giving the machines the opportunity to do what they are best at: to be fast, precise and consistent. By combining humans and machines and let both do what they are best at, we get a better result than we would get if we left the job of handling requirements to just one of them.

23. Why BPs and GNL – 3
The final goal is to allow the machine to assist the developers in analysing requirements for:
Consistency – no requirement contradicts an other requirement
Completeness – all necessary requirements are stated
Safety implications – consider the possibility for hazards

24. Guided Natural language

25. What is GNL - 1
Free text requirement elicitation with the assistance of prescribed words from a dictionary. This will give us requirements which use all terms in a uniform way, thus reducing misunderstandings
No formal constraints
Requires minimal expertise.

26. What is GNL - 2
Bridge the gap between unconstrained expression and quality checking when representing requirements as free text.
Quality measures:
Correctness
Consistency
Completeness
Un-ambiguity (reduced variability)
Provide the basis for semantic processing and checking of requirements.
Dictionary – Simple taxonomy or more formal ontology

27. Ontologies – 1
Ontologies are an important part of CESAR's approach to requirements engineering. An ontology has three parts
a thesaurus
a set of relationships between terms in the thesaurus
rules for making interferences based on these relationships.
The information used to build an ontology is in our case mainly found in standards and glossaries.

28. Ontologies – 2
Ontology = Thesaurus + Inference Rules
Thesaurus – Domain concepts: entities, terms and events
Inference Rules – Relations, attributes and axioms
Causality, similarity, reflexivity, transitiveness, symmetric, disjoint (contradiction) …

29. Ontologies – 3 Required Activity
Knowledge capture: Information embedded in domain events from domain experts and ontologist
Implementation: Formal representation of captured knowledge. Language: OWL, Support environment: Protégé.
Verification: Checking that represented ontology is correct using
Classifiers/reasoners
Domain experts (semantic accuracy)
Mapping of requirement segments to ontology concepts

30. Ontologies – example Boiler-tank infers Feeding-pump Non-return valve…
Water-level
Boiler-tank
Feeding-pump
Non-return valve
Tank
Max-limit
Pump
infers
has
is controlled by
Min. water level
Max. water level
Water-level indicator On
Off
Control-system
has-state
is coupled with

31. Boilerplates

32. What is a boilerplate – 1
The concept of boilerplates was originally suggested by Hull et al. There is one boilerplate template for each type of requirements, e.g.
the <system> shall be able to <action> to <entity>
the <system> shall not allow <user> to <action>.

33. What is a boilerplate – 2
Boilerplates is a set of structures that can be used to write requirements. They use high-level concept classification and attributes
TDT 4242

34. Boilerplate attributes

35. Main part – 1

36. Main part – 2 The main thing to be achieved by the requirement, e.g.
"…<system> shall <action>”
”…<system> shall allow <entity> to be <state>”

37. Prefix – 1

38. Prefix – 2 Prefixes are used to state:
The condition under which the action part of a requirement should be executed, e.g.
"While <state>…“
"If <event>…“
The rational or goal of the requirement, e.g.
“In order to <action>...”

39. Suffix – 1

40. Suffix – 2 A suffix is used to describe:
Sequencing – e.g. “...before <event>”
Exceptions – e.g. “...except for <action>”
Timing – e.g. “...within <number> <unit>”
Repetitions – e.g. “...at least <quantity> times per <unit>”

41. Using the boilerplates
The RE process is as follows:
Select a boilerplate or a sequence of boilerplates. The selection is based on the attributes that need to be included and how they are organized – fixed terms.
If needed, identify and include mode boilerplates – prefixes
Instantiate all attributes
A boilerplate consists of fixed terms and attributes. It may, or may not, contain one or more modes.

42. Boilerplates in CESAR
The original set of boilerplates had an ad-hoc structure and several of them were difficult to combine into more complex requirements. The CESAR project has an on-going process where
Project partners use the current set of boilerplates to write requirements for safety critical systems and report problems back to the boilerplate working group – NTNU, Infineon and TU Vienna
The boilerplate working group meet when necessary to solve reported problems and issue new boilerplates and update existing ones.

43. Boilerplate structure
A complete boilerplate requirement consist of a prefix, a main part and a suffix.
An example of a complete boilerplate requirement is shown below. Even though this requirement is in a semi-formal form it is still easy to read.
If <temperature reaches max temperature>, the <boiler controller> shall <reduce the power to the heating unit> within <2> <seconds>.

44. Ontologies and boilerplates
The full potential of using boilerplates for requirements will only be realized when we combine them with one more ontologies. We can then:
Check the completeness of the requirements in relations to a given ontology. E.g. if we are using the steam-boiler ontology and do not have a requirement for a safety valve, the tool will tell you that the requirements are not complete and, if inquired, will tell you that it expects one or more safety valve requirements.
Enforce a consistent use of terms, just as for GNL. E.g. in the steam boiler ontology, the terms tank and vessel will be replaced by the term boiler-tank.

45. Boilerplate examples - 1
The <user> shall be able to <capability>
Attributes:
<user> = driver
<capability> = <verb> <entity> = start the ACC system
Requirement
The driver shall be able to start the ACC system
TDT 4242

46. Boilerplate examples - 2
The <system> shall be able to <action> <entity>
Attributes:
<system> = ACC system
<action> = <verb> = determine
<entity> = the speed of the ego-vehicle
Requirement
The ACC system shall be able to determine the speed of the ego-vehicle
TDT 4242

47. Boilerplate examples - 3
Prefix: While <state>
Main part: <user> shall be able to <capability>
Attributes
<state> = activated
<user> = driver
<capability> = override engine power control of the ACC system
Requirement
While activated the driver shall be able to override engine power control of the ACC-system
TDT 4242

48. Non-functional requirement example – 1
Non-functional requirements and soft goals fits into the same BPs as functional requirements
The <system> shall be able to <action> to <entity>
Suitability: The <system > shall be able to <provide an appropriate set of functions> to <the user>
TDT 4242

49. Non functional requirement example – 2
Non-functional requirements and soft goals fits into the same BPs as functional requirements
The <system> shall be able to <capability>
…for a period of at least <quantity> <unit>
Maturity: The <system > shall be able to <operate without failure> for a sustained period of at least <quantity> <time unit>
TDT 4242

50. Non functional requirement example – 3
While <state>
The <system> shall be able to <action> <entity>
While <normal state> the <system> shall be able to <tolerate> <90% of software faults of category...>

51. Summing up The use of boiler plates and ontologies will
Enforce a uniform use of terms
Reduce the variability of presentations – requirements that are similar will look similar
Reduced variation in form and contents simplifies the use of automatic and semi-automatic tools for
Checking requirement quality – e.g. completeness and consistency
Creating test cases

52. User stories

53. Why user stories User stories is another way to use templates.
Boilerplates define the terms to use
User stories define the required content

54. What is a User Story Stories are used as:
A concise, written description of a piece of functionality that will be valuable to a user (or owner) of the software.
Stories are used as:
Descriptions of user’s needs
Product descriptions
Planning items
Tokens for a conversation
Mechanisms for deferring conversation

55. User Story Cards have three parts
Description - A written description of the user story for planning purposes and as a reminder
Conversation - A section for capturing further information about the user story and details of any conversations
Confirmation - A section to convey what tests will be carried out to confirm the user story is complete and working as expected

56. User Story Template – 1 Example:
As a [user role] I want to [goal] so I can [reason]
As a [type of user] I want to [perform some task] so that I can [reach some goal]
Example:
As a registered user I want to log in so I can access subscriber-only content

57. User Story Template – 2 Who (user role) What (goal) Why (reason)
gives clarity as to why a feature is useful
can influence how a feature should function
can give you ideas for other useful features that support the user's goals

58. From user story to test case
We can use templates to write test cases for the use stories. One tool that employs such templates is CUCUMBER:
Scenario: a short description of the test scenario
Given: test preconditions
When: test action – input
Then: test result – output
And: can be used to include more than one precondition, input or output.

59. Use stories (US) vs. boilerplates (BP)
We can use boilerplates to formulate use stories
US: As a [user role] I want to [goal] so I can [reason] BP: The [user role] shall [action] in order to achieve [goal]
US: As a [type of user] I want to [perform some task] so that I can [reach some goal] BP: The system shall be able to [perform some task] in order to achieve [some goal]

60. Boilerplate examples

61. SafeLoc – 1 Robot rail Position switch Robot arm Robot platform
Light emitter
Light receiver
Gate B
Gate A
Area A
Area B
Fence
Restart switch

62. SafeLoc – 2
if <state>, <system> shall <action> within <quantity> <unit> if <gate is opened to the zone where the robot is operating>, <robot control> shall <stop> <robot> within <10> <milliseconds>,
<system> shall not allow <entity> to be <state>, unless <state> <robot control> shall not allow <robot> to be <started>, unless <all gates are closed> and <reset button is pushed>
TDT 4242

63. SafeLoc – 3
If <event>, <system> shall <action> if <robot moves into an occupied zone>, <robot control> shall <stop> <robot>

67. ACC requirements – 1
The minimum selectable time gap for steady state vehicle following shall be greater than or equal 1s for all speeds. At least one time gap tau in the range 1.5s to 2.2s shall be provided <ACC> shall not allow <driver> to <set> <time gap less than 1s>
<ACC> shall be able to <select> <at least one time gap tau> within <1.5 to 2.2> <seconds>
The ACC system shall be able to determine the speed of the ego-vehicle <ACC> shall be able to <determine > <the speed of the ego-vehicle>
An ACC system is not required to respond to stationary targets. If the system is not designed to respond to stationary targets the driver shall be informed at least by a statement in the vehicle owner’s manual <ACC > may <response> <to stationary targets>
If <ACC does not respond to stationary targets>, <ACC manual> shall <inform> < driver>

68. ACC requirements – 2
The ACC system shall enable steady state vehicle following on (a) straight roads (class I, II, III and IV) and (b) curves with a radius down to 500m (class II, III and IV), down to 250 m (class III and IV), and down to 125m (class IV) <ACC> shall be able to <steady state vehicle following> on {<straight roads class I, II, III and IV> and < curves with a radius down to 500m on roads class II, III and IV> and <curves with a radius down to 250 m roads class III and IV> and <curves with a radius down to 125m on roads class IV>}
An ACC system shall provide means for a driver to select a desired set speed <driver> shall be able to <select> <desired speed>
The driver shall always have the authority to override the ACC system engine power control <driver> shall be able to <override> <ACC engine power control>

69. Heating unit – system overview
Temperature sensor
Heating element
220V AC
Controller
I/O panel

70. Natural language requirements
The user shall be able to use a simple panel to define time intervals, consisting of
Starting time
Ending time
Temperature during this interval – Ta
The time intervals are not allowed to overlap
The user shall be able to use a simple panel to define a temperature tolerance value d.
If the user don't set a temperature tolerance, the system shall use default value d = 2oC
If the temperature falls below Ti – d, the heather shall be turned on
If the temperature exceeds Ti + d, the heather shall be turned off
If time is outside all defined intervals the temperature shall be set to a predefined default value T0.

71. Boilerplate requirements – 1
<user> shall be able to <define> <time interval a = [ts, te]>
<system> shall not allow <time intervals> to <overlap>
<user> shall be able to <set> <temperature Ta for time interval a>
<user> shall be able to <set> <temperature tolerance d>
If <temperature tolerance not set>, <system> shall <set> <temperature tolerance = 2>
<system> shall have <simple input / output panel>
<system> shall have <heating unit>
<system> shall have <default temperature = T0>
In order to <measure temperature>, <system> shall have <temperature sensor>

72. Boilerplate requirements – 2
In order to <control temperature>, <heating unit> shall have <on / off switch>
If <temperature sensor reading exceeds T + d>, <system> shall <switch on heating unit>
If <temperature sensor reading is below T - d>, <system> shall <switch off heating unit>
When <time in [ts, te] for interval a>, <system> shall <set> <T = Ta>
<system> shall <sample> <temperature sensor> at least <3> times per <minute>
<system> shall not allow <time intervals> to <overlap>
If <time is outside all time intervals>, <system> shall <set> <T = T0>

73. How to communicate requirements Use cases and beyond

74. Finding use cases
Describe the functions that the user wants from the system
Describe the operations that create, read, update, and delete information
Describe how actors are notified of changes to the internal state of the system
Describe how actors communicate information about events that the system must know about
TDT 4242

75. Key points for use cases - 1
Building use cases is an iterative process
You usually don’t get it right at the first time.
Developing use cases should be looked at as an iterative process where you work and refine.
Involve the stakeholders in each iteration
TDT 4242

76. Reuse opportunity for use cases – 1
There is duplicate behavior in both the buyer and seller which includes "create an account" and "search listings".
Extract a more general user that has the duplicate behavior and then the actors will "inherit" this behavior from the new user.
TDT 4242

77. Reuse opportunity for use cases – 2
Relationships between use cases:
Dependency – The behavior of one use case is affected by another. Being logged into the system is a pre-condition to performing online transactions. Make a Payment depends on Log In
Include – One use case incorporates the behavior of another at a specific point. Make a Payment includes Validate Funds Availability
TDT 4242

78. Reuse opportunity for use cases – 3
Relationships between use cases:
Extends – One use case extends the behavior of another at a specified point, e.g. Make a Recurring Payment and Make a Fixed Payment both extend the Make a Payment use case
Generalize – One use case inherits the behavior of another; it can be used interchangeably with its “parent” use case, e.g. Check Password and Retinal Scan generalize Validate User
TDT 4242

79. Extend Respond to emergency Control center operator
communication down
<<extends>>
Request arrives through radio or phone

80. Generalize Request (re)scheduling of maintenance Maintenance worker
Already scheduled - reschedule
Proposed time not acceptable
Maintenance worker
Ask for new suggestion
Changes in time consumption or personnel

81. Adding details
We can add details to a use case diagram by splitting uses cases into three types of objects.
Entity object
Control object
Boundary object

82. Adding details – example
Input and output via boundary objects
Validate input and output via control objects
Save via entity objects

83. From UC to SD – 1

84. From UC to SD – 2

85. From UC to SD – 3

86. Use case diagrams – pros and cons
Simple use case diagrams are
Easy to understand
Easy to draw
Complex use case diagrams – diagrams containing <<include>>> and <<extend>> are difficult to understand for most stakeholders.
Use case diagrams do not show the sequence of actions

87. Textual use cases - 1
Identify the key components of your use case. The actual use case is a textual representation
TDT 4242

88. Textual use cases - 2 Examples of alternative flow are:
While a customer places an order, their credit card failed
While a customer places an order, their user session times out
While a customer uses an ATM machine, the machine runs out of receipts and needs to warn the customer
Alternative flow can also be handled by using <<extend>> and <<include>>
TDT 4242

89. Textual use cases – 3
Most textual use cases fit the following pattern:

90. Textual use case – example
Use case name
Review treatment plan
Use case actor
Doctor
User action
System action
Request treatment plan for patient X
Check if patient X has this doctor
Check if there is a treatment plan for patient X
Return requested document
Doctor reviews treatment plan
Exceptional paths
This is not this doctor’s patient
Give error message
This ends the use case
No treatment plan exists for this patient

91. Textual use case <<extend>>
Use case name
Respond to
System
emergency call
Use case actor
Operator
User action
System action
System OK => Receive system signal
System Down => Use radio
Receive system
message
Act on message
Send response
End REC – 1
Use case name
Respond to radio
emergency call
Use case actor
Operator
User action
System action
Receive radio
message
Act on message
Send response
End REC – 2

92. Textual use case <<include>>
Use case name
Controller
Use case actor NA
Start timer
Get data
Action necessary?
Yes => Set Actuator
Timer expired ?
No => BIT
Check error status
On => Error handling
End Controller
Use case name
BIT
Use case actor NA
Get test pattern A
Write test pattern
Read test pattern
Compare patterns
Difference => Set error status
End BIT

93. Textual use cases – pros and cons
Complex textual use cases
Are easier to understand than most complex use case diagrams
Are easy to transform into UML sequence diagrams
Require more work to develop
Show the sequence of actions