Requirements and boilerplates
Tor Stålhane
IDI / NTNU
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
Requirements specification
Goal tree – 1
Goal tree – 2
Goal tree – example
Goal description
Why are requirements
difficult
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
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
Brake by Wire System – 1
moving
Requirement - Natural language:
On a blocked wheel the brake shall be released
within 100ms, while the vehicle is moving.
Brake by Wire System – 2
WSS = Wheel Sped Sensor
Templates
Boilerplates
and
Guided Natural language
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.
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
General observations,
multifunctional patterns
Specialized observations,
quantitative data
Inductive, slow, imprecise but with
good error correction capabilities
Deductive, fast, precise but with
bad error correction capabilities
Innovative, general access
Single channel, less than 10 bits
per second
Copying, formal access
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
Observation
Reasoning
Memory
Information processing
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.
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
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
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
Requirements – 2
Step 1:
Capture
Requirements in
Natural Language
Req.012: The system
shall enable cabin
temperature regulation
between 15°C and 30°C
…
…
Req.124: Cabin
temperature shall not
exceed 35°
Step 2:
Transfer Requirements and
functions into a semi-formal
requirements model
Function 1
Function 2
Req 001
Req 002
Req 012
…
Req 124
Req 011
Req 028
Req 050
…
…
Step 3:
Refine the requirements model
and derive detailed requirements
Function 1
Function 1a
Function 1b
Req 001.01
Req 001.02
….
Function 1c
Parallel Steps:
Apply dictionary with common vocabulary; validate and check Requirements consistency and completeness
Step 4:
Create a
preliminary
design model
based on the
requirement
model (to be
used and
refined in
SP3)
BPs and GNL – 1
Template based textual
Guided RSL
=
Boilerplates
Syntax
+
Semantics
Keywords:
Reflects requirement,
system and domain
concepts
Requirements expressed on templates
Uses predefined templates based on concepts, relations
and axioms to guide requirements elicitation
+
Analysis
-Correctness
-Completeness
-Consistency
-Safety analysis
Meta Model
RMM
- Refinement
- Specialization
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
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.
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
Guided Natural language
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.
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
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.
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) …
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
Ontologies – example
infers
…
…
Water-level
…
…
has
Boiler-tank
Feeding-pump
Non-return valve
Tank
Max-limit
is controlled
by
Pump
infers
has-state
is coupled
with
Min. water level
Max. water level
Water-level indicator
On
Off
Control-system
Boilerplates
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>.
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
Boilerplate attributes
Main part – 1
Main part – 2
The main thing to be achieved by the
requirement, e.g.
• "…<system> shall <action>”
• ”…<system> shall allow <entity> to be
<state>”
Prefix – 1
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>...”
Suffix – 1
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>”
Using the boilerplates
The RE process is as follows:
1. 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.
2. If needed, identify and include mode boilerplates –
prefixes
3. Instantiate all attributes
A boilerplate consists of fixed terms and attributes. It
may, or may not, contain one or more modes.
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.
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>.
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.
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
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
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
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
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
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...>
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
User stories
Why user stories
User stories is another way to use templates.
• Boilerplates define the terms to use
• User stories define the required content
What is a User Story
• 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
User Story Cards have three parts
1. Description - A written description of the user
story for planning purposes and as a reminder
2. Conversation - A section for capturing further
information about the user story and details of
any conversations
3. Confirmation - A section to convey what tests will
be carried out to confirm the user story is
complete and working as expected
User Story Template – 1
-
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
User Story Template – 2
• Who (user role)
• What (goal)
• Why (reason)
o gives clarity as to why a feature is useful
o can influence how a feature should function
o can give you ideas for other useful features
that support the user's goals
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.
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]
Boilerplate examples
SafeLoc – 1
Robot arm
Robot platform
Position switch
Light
emitter
Fence
Area A
Restart
switch
Robot rail
Gate A
Area B
Light
receiver
Gate B
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
SafeLoc – 3
• If <event>, <system> shall <action>
if <robot moves into an occupied zone>, <robot
control> shall <stop> <robot>
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>
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>
Heating unit – system overview
Heating
element
Controller
Temperature
sensor
220V AC
I/O panel
Natural language requirements
1. 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
2. The time intervals are not allowed to overlap
3. The user shall be able to use a simple panel to define a
temperature tolerance value d.
4. If the user don't set a temperature tolerance, the system
shall use default value d = 2oC
5. If the temperature falls below Ti – d, the heather shall be
turned on
6. If the temperature exceeds Ti + d, the heather shall be
turned off
7. If time is outside all defined intervals the temperature
shall be set to a predefined default value T0.
Boilerplate requirements – 1
1. <user> shall be able to <define> <time interval a = [ts,
te]>
2. <system> shall not allow <time intervals> to <overlap>
3. <user> shall be able to <set> <temperature Ta for time
interval a>
4. <user> shall be able to <set> <temperature tolerance d>
5. If <temperature tolerance not set>, <system> shall <set>
<temperature tolerance = 2>
6. <system> shall have <simple input / output panel>
7. <system> shall have <heating unit>
8. <system> shall have <default temperature = T0>
9. In order to <measure temperature>, <system> shall have
<temperature sensor>
Boilerplate requirements – 2
10. In order to <control temperature>, <heating unit> shall
have <on / off switch>
11. If <temperature sensor reading exceeds T + d>, <system>
shall <switch on heating unit>
12. If <temperature sensor reading is below T - d>, <system>
shall <switch off heating unit>
13. When <time in [ts, te] for interval a>, <system> shall <set>
<T = Ta>
14. <system> shall <sample> <temperature sensor> at least
<3> times per <minute>
15. <system> shall not allow <time intervals> to <overlap>
16. If <time is outside all time intervals>, <system> shall <set>
<T = T0>
How to communicate
requirements
Use cases and beyond
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
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
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
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
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
Extend
Respond to emergency
communication down
Control center
operator
<<extends>>
Request arrives
through radio or phone
Generalize
Request (re)scheduling
of maintenance
Maintenance
worker
Proposed time
not acceptable
Changes in time
consumption or personnel
Already scheduled
- reschedule
Ask for new
suggestion
Adding details
We can add details to a use case diagram by splitting
uses cases into three types of objects.
Boundary object
Control object
Entity object
Adding details – example
• Input and output via boundary objects
• Validate input and output via control objects
• Save via entity objects
Main page
Result page
Show
Validate
Web server
Update
Database
From UC to SD – 1
From UC to SD – 2
From UC to SD – 3
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
Textual use cases - 1
Identify the key components of your use case. The
actual use case is a textual representation
TDT 4242
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
Textual use cases – 3
Most textual use cases fit the following pattern:
Request with data
Validate
Change
Respond with result
Textual use case – example
Use case name
Review treatment plan
Use case actor
Doctor
User action
System action
1. Request treatment plan for
patient X
2.
3.
Check if patient X has this doctor
Check if there is a treatment plan for
patient X
4.
Return requested document
5.
Doctor reviews treatment plan
Exceptional paths
2.1 This is not this doctor’s patient
2.2 Give error message
This ends the use case
3.1 No treatment plan exists for this patient
This ends the use case
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
Textual use case <<include>>
Use case name
Controller
Use case actor
NA
Start timer
Get data
Use case name
BIT
Use case actor
NA
Get test pattern A
Action necessary?
Write test pattern
Yes => Set Actuator
Read test pattern
Timer expired ?
No => BIT
Check error status
On => Error handling
End Controller
Compare patterns
Difference => Set error
status
End BIT
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