There are many reasons why textual requirements by themselves fail to result in usable, high-quality systems.

First, it is difficult to ensure all the following functionality is present:

• All normal (sunny day) functionality
• All edge cases
• All variations of inputs, sequences, and timings
• All exception, error, and fault cases
• Qualities of service, such as performance, range, precision, timing, safety, security, and reliability
• All stakeholders appropriately represented

Getting that much is a daunting task indeed. But even beyond that, there is an air gap between realizing a possibly huge set of shall statements and actually meeting the stakeholder needs. The stakeholder believes that if the system performs a specific function, then in practice, their needs will be met. Experience has shown that is not always true. Customers often ask for features that don't address their true needs. Further, requirements are volatile and interact in often subtle but potentially catastrophic ways.

We address this issue by capturing requirements both in textual and formal means via modeling. The textual requirements are important because they are human-readable by anyone even without modeling training. The model representation of the requirement is more formal and lends itself to more rigorous thought and analysis. In general, both are necessary.

Definitions

Before we get into the recipes, let's agree on common terms:

• Requirement: A stakeholder requirement is a statement of what a stakeholder needs. A system requirement is a statement of what the system must do to satisfy a stakeholder need. We will focus on system requirements in this chapter. Normally, requirements are written in an active voice using the shall keyword to indicate a normative requirement, as in the following example:

  The system shall move the robot arm to comply with the user directive.

• Actor: An actor is an element outside the scope of the system we are specifying that has interactions with the system that we care about. Actors may be human users, but they can also be other systems, software applications, or environments.
• Use Case: A use case is a collection of scenarios and/or user stories around a common usage of a system. One may alternatively think of a use case as a collection of requirements around a usage-centered capability of the system. Still another way to think about use cases is that they are a sequenced set of system functions that execute in a coherent set of system-actor interactions. These all come down to basically the same thing. In practice, a use case is a named usage of a system that traces to anywhere between 10-100 requirements and 3-25 scenarios or user stories.
• Activities: An activity diagram in SysML is a composite behavior of some portion of a system. Activities are defined in terms of sequences of actions which, in this context, correspond to either a system function, an input, or an output.

  Activities can model the behavior of use cases. Activities are said to be fully constructive in the sense that they model all possible behavior of the use case.

• State Machines: A state machine in SysML is a composite behavior of a system element, such as a block or use case. In this context, a state machine is a fully constructive behavior focusing on conditions of the system (states) and how the system changes from state to state, executing system functions along the way.
• Scenarios: A scenario is an interaction of a set of elements in a particular case or flow. In this usage, a scenario represents a partially complete behavior showing the interaction of the actors with the system as it executes a use case. The reason that it is partially complete is that a given scenario only shows one or a very small number of possible flows within a use case. Scenarios are roughly equivalent to user stories. In SysML, scenarios are generally captured using sequence diagrams.
• User Story: A user story is a statement about system usage from a user or actor's point of view that achieves a user goal. User stories describe singular interactions and so are similar in scope to scenarios. User stories use a canonical textual formulation such as As a <user> I want <feature> so that <output or outcome>.

  Here's an example:

  As a pilot, I want to control the rudder of the aircraft using foot pedals so that I can set the yaw of the aircraft.

  User stores tend to be most beneficial for simpler interactions, as complex interactions are difficult to write out in understandable text. Scenarios are generally preferred for complex interactions or when there is a lot of precise detail that must be specified. Consider the following somewhat unwieldy user story:

  As a navigation system, I want to measure the position of the aircraft in 3 dimensions with an accuracy of +/- 1 m every 0.5s so that I can fly to the destination.

And that's still a rather simple scenario.

As stated in the chapter introduction, functional analysis is a means to both capture and improve requirements through analysis. In this case, we'll begin with scenarios as a way to elicit the scenarios from the stakeholder and create the requirements from those identified interactions. We then develop an executable model of the requirements that allows us to verify that the requirements interact how we expect them to, identify missing requirements, and perform what-if analyses for additional interactions.

Purpose

The purpose of this recipe is to create a high-quality set of requirements by working with the stakeholders to identify and characterize interactions of the system with its actors. This is particularly effective when the main focus of the use case is the interaction between the actors and the system or when trying to gather requirements from non-technical stakeholders.

Inputs and preconditions

The input is a use case naming a capability of the system from an actor-use point of view.

Outputs and postconditions

There are several outcomes, the most important of which is a set of requirements accurately and appropriately specifying the behavior of the system for the use case. Additional outputs include an executable use case model, logical system interfaces to support the use case behavior, along with a supporting logical data schema and a set of scenarios that can be used later as specifications of test cases.

How to do it

Figure 2.1 shows the workflow for this recipe. There are many steps in common with the next two recipes:

Figure 2.1 – Functional analysis with scenarios

Identify the use case

This first step is to identify the generic usage of which the scenarios of interest, user stories, and requirements are aspects.

Describe the use case

The description of the use case should include its purpose, and a general description of the flows, preconditions, postconditions, and invariants (assumptions). Some modelers add the specific actors involved, user stories, and scenarios, but I prefer to use the model itself to contain those relations.

Identify related actors

The related actors are those people or systems outside our scope that interact with the system while it executes the current use case. These actors can send messages to the system, receive messages from the system, or both.

Define the execution context

The execution context is a kind of modeling sandbox that contains an executable component consisting of executable elements representing the use case and related actors. The recommended way to achieve this is to create separate blocks representing the use case and the actors, connected via ports. Having an isolated simulation sandbox allows different systems engineers to progress independently on different use case analyses.

Capture use case scenarios

Scenarios are singular interactions between the system and the actors during the execution of the use case. When working with non-technical stakeholders, it is an effective way to understand the desired interactions of the use case. We recommend starting with normal, sunny day scenarios before progressing to edge case and exceptional rainy day scenarios. It is important to understand that every message identifies or represents one or more requirements.

Create ports and interfaces in the execution context

Once we have a set of scenarios, we've identified the flows from the use case to the actors and from the actors to the system. By inference, this identifies ports relating the actors and the system, and the specific flows within the interfaces that define them.

Create an executable state model

This step creates what I call the normative state machine. Executing this state machine can recreate each of the scenarios we drew in the Capture use case scenarios section. All states, transitions, and actions represent requirements. Any state elements added only to assist in the execution that do not represent requirements should be stereotyped «non-normative» to clearly identify this fact. It is also common to create state behavior for the actors in a step known as instrumenting the actor to support the execution of the use case in the execution context.

Verify and validate requirements

Running the execution context for the use case allows us to demonstrate that our normative state machine in fact represents the flows identified by working with the stakeholder. It also allows us to identify flows and requirements that are missing, incomplete, or incorrect. These result in Requirements_change change requests to fix the identified requirement defects.

Requirements_change

Parallel to the development and execution of the use case model, we maintain the textual requirements. This workflow event indicates the need to fix an identified requirement defect.

Update the requirements set

In response to an identified requirement defect, we fix the textual requirements by adding, deleting, or modifying requirements. This will then be reflected in the updated model.

Add trace links

Once the use case model and requirements stabilize, we add trace links using the «trace» relation or something similar. This is generally a backtrace to stakeholder requirements as well as forward links to any architectural elements that might already exist.

Perform the use case and requirements review

Once the work has stabilized, a review for correctness and compliance with standards may be done. This allows subject matter experts and stakeholders to review the requirements, use case, states, and scenarios for correctness and for quality assurance staff to ensure compliance with modeling and requirements standards.

Let's have a look at an example.

Identify the use case

This example will examine the Emulate Basic Gearing use case. The use case is shown in Figure 2.2:

Figure 2.2 – Emulate Basic Gearing use case

Describe the use case

All model elements deserve a useful description. In the case of a use case, we typically use the format shown here:

Figure 2.3 – Use case description

Identify related actors

The related actors in this example are the Rider and the Training App. The rider signals the system to change the gearing via the gears control and receives a response in terms of changing resistance. The training app, when connected, is notified of the current gearing so that it can be displayed. The relation of the actors to the use case is shown in Figure 2.2.

Define the execution context

The execution context creates blocks that represent the actors and the use case for the purpose of the analysis. In this example, the following naming conventions are observed:

• The block representing the use case has the use case name (with white space removed) preceded by Uc_. Thus, for this example, the use case block is named Uc_EmulateBasicGearing.
• Blocks representing the actors are given the actor name preceded with a and an abbreviation of the use case. For this use case, the prefix is aEBG_ so the actor blocks are named aEBG_Rider and aEBG_TrainingApp.
• The interface blocks are named as <use case block>_<actor block>. The names of the two interface blocks are iUc_EmulateBasicGearing_aEBG_Rider and iUc_EmulateBasicGearing_aEBG_TrainingApp. The normal form of the interface block is associated with the proxy port on the use case block; the conjugated form is associated with the corresponding proxy port on the actor block.

All these elements are shown in the Internal Block Diagram (IBD) in Figure 2.4:

Figure 2.4 – Emulate Basic Gearing execution context

Capture use case scenarios

Scenarios here are captured to show the interaction of the system with the actors using this use case. Note that continuous flows are shown as flows with the «continuous» stereotype. This resistance at a specific level is applied continuously until the level of resistance is changed. As is usual in use case analysis, messages between the actors are modeled as events and invocations of system functions on the use case lifeline are modeled as operations.

The first scenario (Figure 2.5) shows normal gear changes from the rider. Note that the messages to self on the use case block lifeline indicate system functions identified during the scenario development:

Figure 2.5 – Emulate Basic Gearing scenario 1

The next scenario shows what happens when the rider tries to increment the gearing beyond the maximum gearing allowed by the current configuration. It is shown in Figure 2.6:

Figure 2.6 – Emulate Basic Gearing scenario 2

The last scenario for this use case shows the rejection of a requested gear change below the provided gearing:

Figure 2.7 – Emulate Basic Gearing scenario 3

Based on these sequences, we identify the following requirements:

• The system shall respond to applied pedal torque with resistance calculated from the base level of resistance, current gearing, and applied torque to simulate pedal resistance during road riding.
• The system shall send the current gearing to the training app when the current gearing changes.
• The system shall respond to a rider-initiated increase in gear by applying the new level of gearing provided that it does not exceed the maximum gearing of the gearing configuration.
• The system shall respond to a ride-initiated decrease in gear by applying the new level of gearing provided that it does not exceed the minimum gearing of the gearing configuration.

Create ports and interfaces in the execution context

It is a simple matter to update the ports and interface blocks to contain the messages going between the actors and the use case. The sequence diagrams identify the messages between the use case and actor blocks, so the interface blocks must support those specific flows (Figure 2.8):

Figure 2.8 – Emulate Basic Gearing ports and interfaces

Create an executable state model

This step constructs the normative state machine for the use case as well as instrumenting the actors with their own state machines. The state machine of the use case block is the most interesting because it represents the requirements. Figure 2.9 shows the state machine for the Emulate Basic Gearing use case:

Figure 2.9 – Emulate Basic Gearing state machine

To support the execution, the system functions must be elaborated enough to support the execution and simulation. These system functions include applyResistance(), checkGearing(), and changeGear(). Figure 2.10 shows their simple implementation:

Figure 2.10 – Emulate Basic Gearing system functions

The system variable gear is represented as a Real (from the SysML value type library), representing the gear multiplier, in a fashion similar to gear-inches, a commonly used measure in cycling. The flow properties appliedTorque and resistance are likewise implemented as Reals.

The state machines for the actor blocks are even simpler than those of the use case block. Figure 2.11 shows the Rider state machine:

Figure 2.11 – Rider actor block state machine

Figure 2.12 shows the TrainingApp state machine and the implementation of its displayGearing() function:

Figure 2.12 – TrainingApp actor block state machine

Lastly, some constants are defined. DEFAULT_GEARING is set to the same value as MIN_GEARING; in this case, 30 gear-inches. MAX_GEARING is set to about the same as a 53x10 gearing, 140. The GEAR_INCREMENT is used for incrementing or decrementing the gearing and is set to 5 gear-inches for the purpose of simulation.

Verify and validate requirements

To facilitate control of the execution, a panel diagram is created. The buttons insert events in the relevant objects and the text boxes display and support modification of the value and flow properties. A panel diagram is a useful feature of the IBM Rhapsody modeling tool used to create these models:

Figure 2.13 – Emulate Basic Gearing panel diagram

The execution of the state model recreates the sequence diagrams. Figure 2.14 shows the recreation of Scenario 1 (Figure 2.5) by the executing model. The creation of such sequence diagrams automatically from execution is another useful Rhapsody feature:

Figure 2.14 – Animated sequence diagram from model execution

While in review, the project lead notices that there is no requirement to display the initial starting value for the gearing, before a specific gear has been selected. Additionally, we see that the requirement to notify the training app was missing. These are identified as missing requirements that must be added.

Requirements_change

In this example, we notice that we omitted a requirement to update the rider display of the gearing. The change has already been made to the state machine.

Update requirement set

We add the following requirements to the requirements set:

• The system shall display the currently selected gear.
• The system shall default to the minimum gear during initialization.

Add trace links

In this case, we ensure there are trace links back to stakeholder requirements as well as from the use case to the requirements. This is shown in the use case diagram in Figure 2.15. The newly identified requirements are highlighted with a bold border:

Figure 2.15 – Emulate Basic Gearing requirements

Perform a use case and requirements review

The requirements model can now be reviewed by relevant stakeholders. The work products that should be included in the review include all the diagrams shown in this section, the requirements, and the executing model. The use of the executing model allows a what-if examination of the requirements set to be easily done during the review. Such questions as What happens to the gearing if the rider turns the system off and back on? or What is absolute maximum gearing to be allowed? can be asked. The simulation of the model allows the questions to either be answered by running the simulation case or can be identified as an item that requires resolution.