User manual¶

• Table of contents
• User manual
  • About requirements workflow tailoring and the user manual
  • Clases: Requirements (Req) and Requirement Documents (ReqDoc).
  • Anatomy of a requirement in cSysReq

About requirements workflow tailoring and the user manual¶

‘cosmoSys-Req’ is often called simply ‘cSysReq’

A requirement management tool usually needs some tailoring before using it. Every company has its own requirements workflow. cSysReq is (thanks to its Redmine basis) easily customizable to meet each user’s needs.

In order to show how to use this tool, we will set a reference workflow. cSysReq, from scratch, will be configured to support this reference workflow. The tool documentation will be using the reference workflow.
To show the use of the tool tailored to meet other workflows is beyond the target of the cSysReq development team.

We strongly recommend, specially if you are an early adopter of the tool, to keep as much as possible the tool as is. Our capabilities to give non-professional (community) support to users will dramatically decrease if the tool has been tailored.

Clases: Requirements (Req) and Requirement Documents (ReqDoc).¶

An engineering project classically uses documents. It is an easily readable and understandable way to share the requirements of a system. It has some benefits and limitations.

The requirement databases underlying the management tools are addressed to make these limitations disappear. As it is also a good idea to try to keep the benefits of the document based system, cSysReq is able to show the requirements stored in the database as documents.

While the class Req is used to describe a requirement, the class ReqDoc is used to describe a requirements document. All the requirements must be included in one (and just one ReqDoc). Multiple ReqDoc can exist in a project.

Sometimes a project needs its documents structured in a “documents tree” or in a ·documents wood· (this means, multiple “documents tree”).

A ReqDoc can have another ReqDoc as a parent, or can have no parent. If it has no parent, it is a root document of the “documents wood” of the project.

Having said that he requirements are included in requirements documents, these requirements can be structured in a “requirements wood” inside a document. The requirements which parent is a ReqDoc will be placed in the first level of the document, and other requirements may hang from them in a tree structure.

Using the typical document structure in LibreOffice Writer or Microsoft Word as an analogy, ReqDocs are documents, and Requirements are chapters. The root requirements of a document will use the “Heading 1” style. Other requirements will hang from these chapters as “Heading 2”. Subsequently, other requirements will hang from the last ones having “Heading 3” styles, etc. In fact, as we will see later, when cSysReq tool generates ODT (document) reports, it will create an ODT file per ReqDoc item, and will create the chapters inside the documents as a tree structure of headings reproducing the tree structure of the Req items.

Apart from grouping requirements, the ReqDoc items have other features:

• When generating the project requirements download file (RqDownload.ods) in an spreadsheet format, they will appear as tabs inside the spreadsheet, containing the ReqItems as rows, showing the “requirements wood” structure of the document.

• When creating the project requirements reports, a report document will be created per ReqDoc item in the project.

• When exporting the project requirements to Doorstop, a Doorstop folder will be created per ReqDoc item in the project.

• Requirements have unique identifiers that consist in a prefix and a numeric value. The prefix is always ended by a hyphen. The ReqDoc item sets the prefix. As an example, an identifier like SR-0004 has a SR prefix and a numeric value of 0004. The ReqDoc item with identifier SR defines the prefix as SR-, so every requirement inside the SR document will have an identifier fitting in the next shape: SR-NNNN.

warning, At the moment, Doorstop import/export feature is executed by using a Jupyter notebook script through the REST API. If you need this functionality, contact the cSysReq team to get the script. This feature is not in the development flow and this causes that the script can be outdated, so for the moment we prefer to check it before delivering it.

Anatomy of a requirement in cSysReq¶

A requirement (Req item) consists necessarily of:

• BdID: The requirements database identifier. This is a numeric value unique in all the requirements database (containing all the projects). This identifier is used for the links between items. Thanks to this ID, several baselines of a requirements set can be present in the same Redmine server, using a Redmine project per baseline, repeating the same identifiers, without creating reference problems. In some views, the identifier can be shown preceded by the character “#” (f.i. #265, #23, …).

• RqID: An unique identifier in the scope of a Redmine project. It consists on a prefix ended by a hyphen. This identifier has been described with a greater detail above.

• RqTitle: Title of the requirement. A short text to better understand the requirement. It will be used at the diagrams so the shorter the better. It has to be quite descriptive. While one can repeat titles, it is a good practice not to do it.

• Parent: Relationship with the parent requirement within the requirements wood of the document. It can also be pointing to a ReqDoc item, if the requirement is at the top level of the requirements wood of the document (it means it is a root requirement). The cardinality is (1 parent : N children).

• Related requirements: Dependence relationship between requirements. In some cases one requirement depends on another, or on a group of other requirements. This is denoted by the string “←“. “A ← B” means “A depends of B”. This relationship has a cardinality of (N : N). The inverse relationship is denoted by the string “→”. “A → B” means “B depends of A”.

• Description: This is the requirement sentence itself. It allows multiline long texts. As we will see later, a Req item can be representing an “actual” requirement or a “Information” one. It is highly recommended that the “actual” have concise sentences written in a specifically predefined syntax. The syntax and the conciseness of the text is responsibility of the user. Typically the syntax will force the description to follow a pattern like “the system shall….” and the organization procedure will require that the sentence must be unambiguous, stating a reachable target, …

• RqRationale: To avoid requirements creep (specially when deleting requirements), to have a rationale sentence inside the requirement item itself is a very good practice. One may use this sentence to justify why the requirement was created, or why it has been written in the way it was. This information is normally kept as confidential to be shared only within the organization which is writing the requirements, and should be rarely included in the reports that this organization may send to its customer. Some example sentences are “this is set because the speed limit in Spain is 120km/h”, “this is because the gravity”, “this is because a recommendation of our design handbook”, or even “this is to allow the reuse of a previous development, to maximize benefit”, or “bronze is better, but we have a big amount of aluminium at the stock and we are trying to get rid of it ;o)”. By default, its value is .

Following the reference workflow of the user manual, we have added the following attributes:

• RqLevel: Level of the requirement.
  • None: default value : Level of the requirement has not been defined yet.
  • System: The requirement acts as system level. It is perceived as a requirement to be fulfilled by the system.
  • Derived: The requirement has been derived from another one, normally because is too complex (RqType = Complex) to be faced from a single engineering discipline .
  • External: This is not a requirement to be fulfilled by our system, but by another entity at the system environment. We add these requirements to our document to include the external requirements that are affecting to our system, so as to have a complete dependence diagram. In some cases our organization is developing a system while other organization is developing a neighbours one. The customer of both systems can change some requirements outside of our system that could affect ours, so this is the reason we need to keep track of them.
  • Shared: The requirement has been set at the super system level (considering the requirements project to be set at system level). In a typical requirements flow down activity, a shared requirement will create several System and several External requirements. One can say that the system under development has some System requirements that are collaborating with other External ones to fulfill a Shared requirement that the super system shall fit.

• RqType: Requirement type.
  • Info: default value : Not an “actual” requirement, it is just a “for information” requirement. It is normally used to describe a part of the system or a functionality (let’s call this a “topic”) in an understandable way, before describing the actual requirements that will describe how the system may behave regarding that topic. While they are normally included in the reports to improve readability, they are normally hidden when doing requirements manipulations as revisions or controlling the progress of the development in later stages.
  • Complex: The requirement is considered too complex to be taken as the starting point of a single discipline development process. We will use the word “atomic” as the opposite of Complex. Later Hw, Sw, Mech, Opt, types of requirements are “atomic”. The normal way to begin a requirements management process is to first focus of the requirements at the system level, set all the “actual” requirements of a system to “Complex” type, review them to see if they are achievable, unambiguous, etc, and later see if the requirement can be directly feeding single discipline (Hw / Sw / Opt / Mech …) engineering development processes. In that is the case case, the type is changed from Complex to the discipline type (f.i. Sw if it can be implemented using a software feature). Otherwise the requirement type stays as Complex, and several other requirements (which RqLevel should be set as Derived) have to be created to divide the requirement in simpler ones. In some cases, and normally for better fitting a functional architecture, a Complex requirement can be split into not only single discipline ones, but also into several Derived Complex ones. If this is the case, the Complex ones will need to be subsequently split until they arrive to atomic ones ones.
  • Hw: Atomic requirements that can be implemented using Electronics development process. In some cases it is worth to even split them into simpler ones, be sure they are clear, simple, and it is easy to later used in the validation plan.
  • Sw: Atomic requirements that can be implemented using Software development process. In some cases it is worth to even split them into simpler ones, be sure they are clear, simple, and it is easy to later used in the validation plan.
  • Opt: Atomic requirements that can be implemented using Optical devices development process. In some cases it is worth to even split them into simpler ones, be sure they are clear, simple, and it is easy to later used in the validation plan.
  • Mech: Atomic requirements that can be implemented using Mechanic devices development process. In some cases it is worth to even split them into simpler ones, be sure they are clear, simple, and it is easy to later used in the validation plan.

• RqSources: Requirement sources. This is a text field to allow users to keep track of other reference document that have acted as sources of the requirement. For instance, a report showing the results of a simulation, a technical note justifying a technique, a minutes document of a meeting with the costumer, an typical RFQ (Request for Quotes) documents showing the master technical concept or the master preliminary requirements from the customer point of view. A good hint is to upload them in the Redmine “Documents” tab of the project, assign them a reference document identifier as RD1, RD2, RD3… and then using a list of these identifiers in the RqSources field. In the requirements workflow of several companies to provide the RqSources of every requirement is mandatory, and in some cases (specially when deriving requirements) there is no external requirement sources document. Leaving RqSources as void can lead to a confusion: it has no source or its sources have not been described? To avoid this confusion, a good technique is to set the self-reference phantom identifier RD0 as source. Finding an RD0 at the RqSources text field means that the requirement has been build as part of the requirement management workflow, and has no external reference. Finding the RqSources text field void means that the requirement is still a draft and can not be reviewed because its sources have not been described. It is also a good practice to write the RqRationale using the references of the RqSources field, so it is always desirable that both fields show some kind of consistency between them.

• RqChapter: An string to be used for showing the requirements in a document in an understandable order. The RqTree view is automatically calculating it and overwriting its contents each time the “commit” button is pressed. It is not a real property of the requirement. It can be changed manually, but we discourage this practice. It can be also easily set at the RqUpload.ods document before uploading it to the tool, but we still recommend to leave the task of defining the chapter string to the RqTree viewer. In the near future this field will be hidden and automatically managed, to avoid problems.

• RqTarget: The development process of a system can be divided in releases, stages, targets, etc… A good practice is to plan the iteration when a requirement must be fulfilled by the system development artifacts. Setting the targets in the project settings, and selecting the target of a requirement allow the prioritization of the requirements revision, and also guides developers and QA validation teams. In order to freeze the requirements of a release, it makes easier to filter the requirements database to just include the requirements which target are equal or previous to the release to freeze. Customer can be accepting these partial requirements sets without discussing about the ones to be incorporated in the future. In some cases different disciplines must join their developments in an specific release, and showing only the requirements involved in that release will help to see if all the dependences are consistent within the release of the team has wrongly set the target of a needed document in a future release.

• RqValue: In many cases a requirement is setting a numeric value and an unit, por instance: “the system has to switch on the WarningLed if the temperature is greater than 50ºK +/- 1ºK”. Thinking in a MBSE paradigm, one can imagine that it will be a good point to be able to automatically generate code of validation tests from the requirement. To make this easier, we have included the RqVar and RqValue fields, to define an unambiguous name for the variable containing the value, and for the value itself. In the above example the ReqVar could be set as “WarningTemp” and the RqValue as “50ºK +/- 1ºK”. In the near future, the development team is planning to allow the Description text of a document to be written using just the RqVar names, so writing the value twice will be not needed anymore. After that change, the requirement would be described as “the system has to switch on the WarningLed if the temperature is greater than WarningTemp”, while in the automatically generated views or reports will still be read as “the system has to switch on the WarningLed if the temperature is greater than WarningTemp (50ºK +/- 1ºK)”. With this feature, one can change the WarningTemp value without modifying the requirements description text. Apart from storing numeric values, it can be also used to store symbols, vectors, tables, or any other value.

• RqVar: As described above, RqVar is used to set the variable name for an RqValue.