Step 2: import or reference system requirements

NOTE :in this release, only "import" mode (copy) is available. "Reference" mode has been partially implemented but there are remaining bugs and so this feature has not been published yet. It is planned for next release.

In this step we will import existing requirements from Excel file (.xls) and we will "align" them on our requirement data model (step 1). We will also show how you can do same import with requirements coming from Word (.doc) and from .reqIF files.

Note: if you want to import .xlsx and .docx files, it is not possible directly in ReqCycle currently. You first need to save them as .xls and .doc older formats.

ATM system requirements

Note: System engineering generally starts with stakeholder requirement elicitation from needs. This activity is not covered by this tutorial.

We start with system requirements already available.

Create "SystemRequirements" project

We need an Eclipse project in our workspace to store requirements that we import. It will give us ability to trace those requirements to our model in ReqCycle.

in Eclipse top menu, choose "File>New project" and choose "General project". A wizard opens. Choose name "SystemRequirements".

Import System requirements from Excel file

import mechanism with OCL mapping file

Import consists in extracting functional requirements of Excel file and creating requirements that conform to "Functional" requirement type of our requirement data model (MyReqDataModel). ReqCycle provides a wizard for that with a mapping model that will precise how to map elements between source and destination. Here is below an overview. Then we focus on the mapping model.

ReqCycle has a domain specific model that conforms to Excel structure and uses standard OCL language (Object Constraint Language) to define queries in this model.

Mapping file consists in declaring 2 kinds of queries:

• is<RequirementType) : boolean that formalizes how to identify requirements of a given requirement type. In our case requirement type is "Functional" and we have a "isFunctional" query.
• def<AttributeName> : <type> that formalizes how to identify requirement attributes of type <requirementType>. In our case, we have 3 attributes and we have potentially the following queries to define:
  • isRevision : String
  • isStatus : String
  • isDerived : Boolean

As our Excel file does not contain any data concerning "derived" data, we do not need to map this attribute. Here is how we can define those queries for Excel model:

import in practice through Requirement sources view

Excel file containing ATM system requirements can be downloaded here: Media:ATM_System_Requirements.xls.zip

Unzip file. then import "ATM System Requirements.xls" file in your "SystemRequirements" eclipse project ( select your project and right click>import>General>File system and select location of your .xls file).

We also need a mapping file to tell ReqCycle how to map elements of Excel file into our requirement data model. This OCL mapping file can be downloaded here: Media:SystemFunctionalReq-ExcelMapping.ocl.zip

Import this file into your SystemRequirements project.

Now go to "Requirement sources" view.

Note: if you do not see this view (bottom left), it is perhaps because you have not selected "ReqCycle" perspective. In top menu, select "Window>Open perspective..." and choose ReqCycle. Else it might be because you have closed the view unintentionally. In this case, in top menu select "ReqCycle>Requirement sources".

In Requirement sources view, create new source with "+" button and choose "import document (using .ocl files)". Then follow wizard as below.

Note: you can use another name than the one suggested below for the requirement source but do not use special characters as it could lead to issues when using requirements for traceability.

Suggested patterns if you want to use several words:

• either "stick" all words and use uppercase letter at the beginning of each word to highlight separation (this is the pattern used in the tutorial)
• else use '-' character as separator. It seems to be well encoded and does lead to known bugs for now.

By selecting "IsFunctional" query, ReqCycle performs some checks and warns that "derived" attribute has no mapping defined. It is not a problem as we have not planned to provide mapping for this attribute.

We can now click on "Finish". Requirement source "FunctionalReq" is created in the requirement sources view. You can also notice that a new file has been created in "SystemRequirements" project: "FunctionalReq.reqcycle". This file contains our requirements in Reqcycle format, aligned on "MyReqDataModel" data model.

Visualization of requirements without any custom style

ReqCycle provides a "Requirements view" that can be used to visualize requirements of one or several requirement sources.

Select your requirement source just created and right click>Open Requirements. Requirement view is populated with selected source.

Note: we will see later in this step that we can customize this view and see all requirement attributes and even other data with different layouts (bold, italic, color...).

import Security Requirements from Excel file

Now we want to focus on safety requirements. They might be defined in any .xls file. For our tutorial they are in same Excel file but it does not matter.

We just need to adapt .ocl mapping file to retrieve only security requirements:

• Copy/paste SystemFunctionalReq-ExcelMapping.ocl into SystemSecurityReq-ExcelMapping.ocl in "SystemRequirements" project
• open (right click>open) SystemSecurityReq-ExcelMapping.ocl and replace "isFunctional" query by « isSecurity »
• Replace « FUNCTIONAL/* » regexp by « SECURITY.* »

Now create new Document (OCL) req source called « SecurityReq » with same excel file and with this SystemSecurityReq-ExcelMapping.ocl mapping file.

Select newly created requirement source and right click>Open requirement view to visualize security requirements. You should find only one requirement in this view.

Note: we will see later that we can aggregate different requirement sources to see all matching requirements (functional + security).

Import System requirements from Word file

For Word it is still principle than with Excel: we map requirement data to our custom ReqCycle data model (MyReqDataModel). But here we will not use "OCL" language for mapping. we will rather use ".types" text file mapping.

Here is word document. Notice that security requirements have an ID that starts with SYS-SEC-REQ instead of functional requirements that start with SYS-REQ.

import mechanism with .types mapping file

We still need to identify same kinds of queries but language is a little bit different. Mapping is done through key/values called ".types" file.

First we list all different mappings (.types). Then for each mapping, we define requirement types mappings starting with Requirement1Name = <requirementType>. Then we list all requirement attributes with their name and the regular expression that captures its value.

Note: regular expressions have a special associated language. Here are below two references to learn this language: [1] [2]

import in practice through Requirement sources view

Word file containing ATM system requirements can be downloaded here: Media:ATM_Requirement_document.doc.zip

Unzip file. then import "ATM System Requirements.doc" file in your "SystemRequirements" eclipse project ( select your project and right click>import>General>File system and select location of your .doc file).

We also need a mapping file to tell ReqCycle how to map elements of Word file into our requirement data model. This .types mapping file can be downloaded here: Media:SystemFunctionalReq-WordMapping.types.zip

Import this file into your SystemRequirements project.

Now go to "Requirement sources" view.

In Requirement sources view, create new source with "+" button and choose "import document (using .types file)". Then follow wizard as below (we use here "FunctionalRequirements" as name to distinguish from Excel requirement source):

By selecting "Functional" query, ReqCycle performs some checks to see if attributes are matching.

We can now click on "Finish". Requirement source "FunctionalRequirements" is created in the requirement sources view. You can also notice that a new file has been created in "SystemRequirements" project: "FunctionalRequirements.reqcycle". This file contains our requirements in Reqcycle format, aligned on "MyReqDataModel" data model.

Select your requirement source just created and right click>Open Requirements. Requirement view is populated with selected source.

import Security Requirements from Word file

Now we want to focus on safety requirements. They might be defined in any .doc file. For our tutorial they are in same Word file but it does not matter.

We just need to adapt .types mapping file to retrieve only security requirements:

• Copy/paste SystemFunctionalReq-WordlMapping.types into SystemSecurityReq-WordMapping.types in "SystemRequirements" project
• open (right click>open) SystemSecurityReq-WordMapping.types and replace "Requirement1Name=Functional" by "Requirement1Name=Security"
• replace "SYS-REQ" by "SYS-SEC-REQ" for regular expressions used to capture requirements

Now create new Document (.types) req source called « SecurityRequirements » with same word file and with this SystemSecurityReq-WordMapping.types mapping file.

Select newly created requirement source and right click>Open requirement view to visualize security requirements. You should find only one requirement in this view.

You can also read Step_2:_import_or_reference_system_requirements#Visualization_of_requirements_without_any_custom_style

Note: we will see later that we can aggregate different requirement sources to see all matching requirements (functional + security).

Import System requirements from .reqIF file

Example of ATM requirements in .reqIF format can be downloaded from here

Unzip this file locally and import it in your SystemRequirements Eclipse project (select your project and right click>import>General>File system and select location of your .reqIF file)

You can now double click on this file and RMF/ProR ReqIF editor will open to show list of available ReqIF specifications:

Then if you double click on FunctionalReq specification you will get its contents with a table of requirements with adapted layout (ProR tool).

Now we can create a .reqIF (or RMF) requirement source.

Go to requirement sources view and use "+" button to create new requirement source. Choose "ReqIF" connector. A wizard opens; give name "FunctionalR" or anything else with better meaning for you but does not yet exist in your platform.

Requirement source name shall be unique in the workspace.

In the wizard, now fill data (.reqIF file, reqIF specification, requirement data model, and scope,) as below:

Click next and now a mapping screen opens to map .reqIF specification types to your requirement data model types.

select "Functional" on both lists and click the "map" button. A new screen opens to map each attribute.

Do the mapping for each attribute and click "OK". That is the end. Your requirement source has been created and now you can manage requirements imported from .reqIF file with ReqCycle.

Note: you can create another requirement source with focus on safety requirements only (just choose "safetyReq" ReqIF specification this time).

To view your requirements, simply follow Step_2:_import_or_reference_system_requirements#Visualization_of_requirements_without_any_custom_style

define custom visualization for requirements

By default, there is no defined custom style for requirement visualization. You can define one by clicking on the "pen" icon. A modal windows opens. First time it is empty.

Use the "+" button to create a visualization.

At this stage only the entry of the visualization has been created. As there is only one configuration it is automatically selected for you. In case you have several ones, you need to select one with using the "star" icon button.

In order to configure this visualization you need to edit it through the "pen" button.

Let us look at this window. Main area concerns styles defined to support predicates (queries). It will give us ability to change requirement visualization according to attribute values (for instance see all refined requirements in green and all requirement not traced in red, or see functional requirements in blue...).

---

Before using predicates, let us start customization without predicate. We just want to define a default style that will be applied for all requirements in any situation. In order to do that we use the "Edit" button after "Default :" label. It launches another window (yes still another one: HMI is not so intuitive and efficient... some progress can be done in this area) that defines the current visualization style for your predicate selection. We did not select any predicate but this is same window used to configure a style for a given predicate. Do not take too much care about title.

We want to create a style that will display <ID>::<text>::<status>. We need 6 parts called "segments" to do that: 3 attributes and 3 static segments ("::" X2 and ".")

Let us create 6 segments by using the "+" button. Let us also change the icon associated with the requirement view and let us select the green "+" icon.

Let us create first segment (the <id>). We use the "pen" button to edit the segment (remember, we create a segment and then edit it - heavy process... but it works). Another window opens with choice between 3 kinds of segments:

• constant segment : we will use it for our static segment ("::").
• model segment: will take the value of a given attribute
• operation segment: used to compute a result from a list of defined operations like "isTraced", "covered"...

For our first segment, we use a "model" segment and then click on the "..." button to choose the attribute in the list. We select "Functional" , expand it and then select "id" attribute.

Note: this list will be improved in the future by filtering only data types that can be applied on current requirement source (in our case "functional requirements").

Now click "OK" and that is done. First segment will display "Id" requirement attribute.

Now let us create the second segment. We use "pen" button to edit second segment and then choose "constant" segment and "::" value.

Click OK. Then continue with other 4 segments. For 3rd segment, use attribute "text" and for 5th use "status" one with a "blue" color.

At the end you get:

At the bottom you get a preview of what you will see.

Click OK on each open window and then your requirement view should reflect the style you defined. This style will be used for any requirement view, except if you change this style or define and select a new one.

Concerning predicate based styles, we will see how to use them in a dedicated tutorial available soon.

define specific visual configuration for requirements with use of predicates

Now, we would like to distinguish visually requirements that are in stable status (finalized) and those that are not (to be confirmed for instance). It will help us focusing on finalized ones to create and maintain traceability. In order to get this separation we need to define predicates (queries) and associate different visualization styles associated to those predicates.

We need at least one predicate to identify requirements with status "finalized". There ID will be displayed in green. Other predicates will be displayed with default general configuration: Id in black.

Let us open predicate editor from top menu "ReqCycle">Open predicate editor.

Then create a custom predicate (button):

Then we need to load our Requirement data model to access to the different requirement types and attributes and create our query.

Expand "model" part at bottom left and click "load model" button. A list of all registered data models is displayed (it shall be filtered by ReqCycle prefix but currently it is not done - you have to do it by hand). Choose last version of data model as below:

Then choose attribute for predicate by double clicking on predicate IE Attr on left area.

Then we need to choose another predicate to precise how to check attribute value: we select "String Equal" predefined predicate and apply it on our custom predicate definition by drag and drop from right list to the predicate definition in left area. Custom predicate definition is extended (tree) with a new child predicate "String Equal".

Double click on that and a window asks for a value for this predicate: fill attribute value "FINALIZED" as below.

Now save your custom predicate with "save" icon at the bottom right. That's all for predicates. Now let us see how to use this predicate.

Go back to the requirement view and edit style with "pen" icon.

Create a new styling (visualization) configuration in the central area with "+" button. Those configurations are based on predicates. A list pops up and you can select "OnlyFinalizedRequirements" custom predicate.

Then create a visualization style for that as explained at the end of step 2. Use same visualization except "ID" attribute displayed in green.

Once done, click OK and look at your requirements view: it is now adapted with styles according to requirement status attribute: when status is "FINALIZED", id is in green (onlyFinalizedRequirement custom predicate applies and associated style is used). Else default style is used with ID in black.

Now we would like to change default visualization for requirement not finalized and display them in red.

In that case we just need to define another predicate that will give inverse results from previous one. In order to do that, we come back to predicate editor and create "NotFInalizedRequirements" custom predicate based on "NOT" predefined predicate.

Then we drag and drop "OnlyFinalizedRequirements" on this new predicate definition and save. That 's it.

We can now define a new style based on "NotFinalizedRequirements" predicate and display "Id" in red.

---

Step_3:_refine_system_requirements_through_a_SysML_model back to step 1: Model_Based_System_Engineering_tutorial_with_ATM_system'" [back to ReqCycle wiki main page: https://polarsys.org/wiki/ReqCycle]