Recipes in this chapter

• Functional Analysis with Scenarios
• Functional Analysis with Activities
• Functional Analysis with State Machines
• Functional Analysis with User Stories
• Model-Based Safety Analysis
• Model-Based Threat Analysis
• Specifying Logical System Interfaces
• Creating the Logical Data Schema

This chapter contains recipes to do with the capturing and analysis of requirements. The first four recipes are alternative ways to achieve essentially the same thing. Functional analysis generates high-quality requirements, use cases, and user stories – all means to understand what the system must be.

By “high-quality requirements,” I mean requirements focused on a use case that are demonstrably:

• Complete
• Accurate
• Correct
• Consistent
• Verifiable

The problem is that natural language is ambiguous, imprecise, and only weakly verifiable. Keeping the human-readable text...

Why aren’t textual requirements enough?

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 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 detail 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 this is not always true. Customers often ask for features...

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’s 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 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 ...

Functional Analysis with Scenarios

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

...

Functional analysis with activities

Functional analysis can be performed in subtly different ways. In the previous recipe, we started with the sequence diagram to analyze the use case. That is particularly useful when the interesting parts of the use case are the interactions. The workflow in this recipe is slightly different, although it achieves exactly the same objectives. This workflow starts with the development of an activity model and generates scenarios from that. In this recipe, just as in the previous one, when the work is all complete, it is the state machine that forms the normative specification of the use case; the activity diagram is used as a stepping stone along the way. The objective of the workflow, as with the previous recipe, is to create an executable model to identify and fix defects in the requirements, such as missing requirements, or requirements that are incomplete, incorrect, or inaccurate. Overall, this is the most favored workflow among model-based systems...

Functional analysis with state machines

Sometimes beginning with the state machine is the best approach to do use case analysis. This is particularly true when the use case is obviously “modal” in nature with different operational modes. This approach generally requires systems engineers who are very comfortable with state machines. The recipe is much like the previous use case analyses and can be used instead; the output is basically the same for all three of these recipes.

The primary differences are that no activity diagram is created and the sequence diagrams are created from the executing use case state behavior.

Purpose

The purpose of the recipe is to create a set of high-quality requirements by identifying and characterizing the key system functions performed by the system during the execution of the use case capability. This recipe is particularly effective when the use case is clearly modal in nature and the system engineers are highly skilled...

Functional Analysis with User Stories

The other functional analysis recipes in this chapter are fairly rigorous and use executable models to identify missing and incorrect requirements. User stories can be used for simple use cases that don’t have complex behaviors. In the other functional analysis recipes, validation of the use case requirements can use a combination of subject matter expert review, testing, and even formal mathematical analysis prior to their application to the system design. User stories only permit validation via review and so are correspondingly harder to verify as complete, accurate, and correct.

A little bit about user stories

User stories are approximately equivalent to scenarios in that both scenarios and user stories describe a singular path through a use case. Both are “partially constructive” in the sense that individually, they only describe part of the overall use case. User stories do it with natural language text, while...

Model-Based Safety Analysis

The term safety can be defined as freedom from harm. Safety is one of the three pillars of the more general concern of system dependability. Safety is generally considered with respect to the system causing or allowing physical harm to persons, up to and including death. Depending on the industry, different systems must conform to different safety standards, such as DO-178 (airborne software), ARP4761 (aerospace systems), IEC 61508 (electronic systems), ISO 26262 (automotive safety), IEC 63204 and IEC 60601 (medical), and EN50159 (railway), just to name a few. While there is some commonality among the standards, there are also a number of differences that you must take into account when developing systems to comply with those standards.

The recipe in this chapter provides a generic workflow applicable to all these standards but you may want to tailor it to your specific needs. Note that we recommend this analysis is done on a per-use case basis so...

Hazard analysis

There is normally one FTA diagram per identified hazard, although that FTA can be decomposed into multiple FTA diagrams (although the Cameo profile lacks the transfer operator from the FTA standard, there are other means to accomplish this decomposition). A system, however, normally has multiple hazards. These are summarized into a hazard analysis. A hazard analysis summarizes the hazard-relevant metadata, including the hazard name, description, severity, likelihood, risk, tolerance time, and possibly, related safety-relevant requirements, and design elements.

It should be noted that safety analysis is a rich and deep topic, the details of which are beyond the scope of this book. In this recipe, we will provide a simple FTA-based approach for performing safety analysis.

Purpose

The purpose of this recipe is to create a set of safety-relevant requirements for the system under development by analyzing safety needs.

Inputs and preconditions

A use...

Model-Based Threat Analysis

It used to be that most systems were isolated and disconnected; the only way to attack such a system required physical presence. Those days are long gone.

These days, most systems are internet-enabled and connected via apps to cloud-based servers and social media. This presents opportunities to attack these systems, compromise their security, violate their privacy, steal their information, and cause damage through malicious software.

Unfortunately, little has been done to protect systems in a systematic fashion. The most common response I hear when consulting is “Security. Yeah, I need me some of that,” and the issue is ignored thereafter. Sometimes, some thought is given to applying security tests ex post facto, or perhaps doing some code scans for software vulnerabilities, but very little is done to methodically analyze a system from a cyber-physical security posture standpoint. This recipe addresses that specific need.

Basics...

Specifying Logical System Interfaces

System interfaces identify the sets of services, data, and flows into and out of a system. By logical interfaces, we mean abstract interfaces that specify the content and precision of the flows but not their physical realization. For example, a system interface to a radar might include a message herezaRadarTrack(r: RadarTrack) as a SysML event carrying a radar track as a parameter without specifying what communication means will be used, let alone the bit-mapped structure of the realizing 1553 Bus message. Nevertheless, the specification of the interface allows us to consider the set of services requested of the system by actors, the set of services needed by the system from actors, and the physical and information flow across the system boundary.

The initial set of interfaces is a natural outcome of use case analysis. Each use case characterizes a set of interactions of the system with a group of actors for a similar purpose. These interactions...

Creating the Logical Data Schema

A big part of the specification of systems is specifying the inputs and outputs of the system as well as what information a system must retain and manage. The input and outputs are data or flows and may be direct flows or may be carried via service requests or responses. Early in the system engineering process, the information captured about these elements is logical. The definition of a logical schema is provided below, along with a set of related definitions.

Definitions

Data Schema: a data or type model of a specific problem domain that includes blocks, value properties, value types, dimensions, units, their relations, and other relevant aspects collectively known as metadata. This model includes a type model consisting of a set of value types, units, and dimensions, and a usage model showing the blocks and value properties that use the type model.

Logical Schema: a data schema expressed independently from its ultimate implementation...