This guide describes step-by-step how to export and import textual requirements between IBM Doors 9.7 and Capella modelling tool. The below figure shows the initial process considerations when authoring textual requirements and designing the system in Capella:
For the above activities some will be detailed in sections below, others it will be provided references as it is not considered part of this guide:
- “Create IBM Doors module”.
- “Capture textual requirements and attributes”.
- “Create export ReqIf module view”, this activity will be described in detail in a section below.
- “Purge Deleted Objects”, this activity will be described in detail in a section below.
- “Configure ReqIF Doors file export”.
- “Export textual requirements from Doors module”.
- “Export Capella project from the server”, this activity will be described in detail in a section hereafter.
- “Import textual requirements”, this section will be described in detail in a section hereafter.
- “Import Capella project to the server”, this section will be described in detail in a section hereafter.
- “Formalise textual requirements and design the system”. A reference to why textual requirements is needed, and an approach to requirements modelling can be found within the Model Based System and Architecture Engineering with the Arcadia method book, Chapter 11.
- “Establish textual requirements to model element traceability”. For this activity and if not created previously in the Capella model, there will be the need to created requirements traceability types.
- “Export textual requirements and traceability”, this section will be described in detail in a section hereafter.
- “Prepare and match csv file and Doors module attributes”, this section will be described in detail in a section hereafter.
- “Import textual requirements and traceability”, this section will be described in detail in a section hereafter.
For the activities (1) and (2), a tutorial reference on how to create objects and attributes in IBM Rationale Doors can be found in the IBM Documentation.
For the activities (3) and (4), a reference can be found in the Exporting the ReqIF File by using Rational DOORS 9.6, section 3.
The process captured above is considered as part of the textual requirements synchronisation roundtrip context between an IBM Doors module and a Capella project, it can be used in initial stages of an architecture development for learning purposes, practise with Capella modelling tool or business case development for use and purchase of a Capella commercial add-on.
Create export ReqIf module view
In order to export requirements and heading it can be created a tailored ReqIF export view.
In the Capella modelling tool, new filters can be created by clicking on Menu Tools -> Filter -> Define; then to create the filter for section 4 headings and requirements, the following filter should be created:
Then save the view by clicking on Menu View -> Save as.
When creating the ReqIf step 4 above this view should be referenced as below:
When created the ReqIf file it will include section 4 objects.
Purge Deleted Objects
When objects are deleted, they still remain in the module. In order to deleted them permanently, from the module the objects need to be purged. Before the purge action, it is advised to create a minor baseline of the module, so the objects can be referenced back if needed.
In order to purge Doors module object, there is the need first to see the deleted objects. Click on Menu View -> Show -> Deletions. Then right-click over the object and select “purge” as shown below:
Import textual requirements
The first step in Capella is to make sure that it is possible to see the requirements.
For this follow the steps described in:
- Visualize types
- Show requirements in semantic browser
User attributes might have been created, updated, and exported from the Doors module at the time when exporting module view content to ReqIF file. The system modeler may want to have access to this attributes and current set status, for example, if there is an attribute that captures:
- Requirement types: what type of requirement are defined (e.g., functional, or non-functional) or
- Requirement status: what is the requirement status (e.g., draft, released, reviewed).
In order to, import the Doors module user attributes, there is the need first to create a file with the extension .properties.
To create a .properties configuration file, follow the following steps:
- Create a new notepad file.
- Wright the name of each of the variables to be imported, for example, for the Doors module attribute “Requirement type”, write in the format “Requirement\ type: true”. True means the variable will be available to import in Capella. Note, there is the need to add a “\” for each space and make sure the space is added. Careful should be taken as Capella is case sensitive.
- Save as the file in the format: name.properties.
A properties file content example can be found below:
In Capella go to the menu: Window -> Preferences -> Capella -> Requirements -> Importer.
In the importer window:
- Manage files containing set of attributes section, add the file .properties.
- Select attributes to import section, choose which user attributes to import as below:
At this stage you should be able to import the Doors module textual requirements. A reference on how to import ReqIF can be found in: ReqIF Import in Capella.
When imported the ReqIF file, you should be able to see a similar Types folder and Requirements as below:
Teams for Capella ReqIF limitations
This section covers the process activities:
- “Export Capella project from the server”
- “Import textual requirements”.
- “Import Capella project to the server”.
Teams for Capella does have limitations. It is not possible to import a ReqIF file to a CDO server project. Hence, before importing the textual requirements and attributes there is first the need to “Export Capella project from the server”, that is, export the Capella project to a local drive, “Import textual requirements” and finally, the “Import Capella project to the server” activity.
More details can be found in the Teams for Capella.
Server import requirements limitations
When model is stored on a server the following steps need to be followed:
- When a reqif import is performed in a Capella project, a .capella.bridgetraces is created (filtered by default).
- As the file is hidden in the local Capella project, if you handle the version of your project in git, it will be in your next commit and updated after each import.
- The bridgestraces is not considered as part of the model, hence, not imported to the server.
- To import a reqif to a shared project: there is the need to copy/paste the .bridgeTraces inside it from the precedent import and then store the file on the server.
Bridgestraces file can be found under the workspace -> model (e.g. Electrical Infrastructure).
Textual requirements roundtrip
The following activities will be described in this section:
- “Export textual requirements and traceability from Capella”
- “Prepare and match csv file and Doors module attributes”.
It is relevant to make sure the above step were followed for the first time, that is, Capella imports the textual requirements ReqIF file exported from Doors and not creating a new requirements module in Capella. This activity will allow Capella to create and configure the Capella Requirement Module with the ReqIF Identifier as captured below:
The ReqIF Identifier is unique when exporting from the same Doors module and will be used by Capella to map and update the Capella requirements relevant module.
Later iterations, it will be allowed any order and parallel work of the following activities:
- Update Doors requirements and/or attributes, export to a ReqIF file, and import to Capella OR
- Update Capella textual requirements to model elements traceability updates, export to csv file and import to Doors.
Careful should be considered and a process should be defined when updating requirements in Doors and traceability in Capella.
It is suggested later in the Architecture section, what and where textual requirements and traceability to model elements should be performed and maintained.
Export Capella requirements to csv file
In order to do the “Export requirements from Capella” activity, a number of sub-activities can be performed as it will be described hereafter in this section.
How to guides can be found in view requirements in Capella. The guide describes:
- How to visualise requirements in a diagram.
- How to show requirements in a tabular format.
- Sort and group requirements and verify requirements traceability in a table.
It is recommended that only requirements model types are sent to the Mass Visualisation table, that is, not folder package types should be included. This allows to have the same set of attributes per view.
From the set of attributes at least the three below should be available (not hidden):
- ReqIFForeignID.
- ReqIFText.
- Allocating Elements.
Prepare csv file
We are now in a position to export the requirements and attributes to a csv file as described in Editing requirements attributes. A similar exported csv file should be shown as below:
There is the need prior to importing requirements back to IBM Doors module to “Prepare and match csv file and Doors module attributes”. The following steps need to be performed in the csv file exported:
- Delete line 2; line 2 will create an empty object in Doors.
- Rename attribute ReqIFForeignID to Absolute Number.
- In the ReqIFForeignID, format each of the .csv cells field to general.
- Delete the <div> and </div> from the ReqIFText.
- Rename ReqIFText to Object Text.
The csv file export updated and before importing to Doors should contain the following attributes:
To import a csv file to Doors, open the Doors module from where it was exported initially the textual requirements and click on File -> Import -> Spreadsheet as shown in the below figure:
Select the csv file location and keep the default settings as below:
When clicked in the “import” button, Doors will ask for any new attributes to create in the module. For the first time the csv file is imported into the IBM Doors module, it will need to be created the attribute “Allocating Elements”. This attribute contains the model element traceability done previously in Capella; confirm the new attribute.
Doors will then ask what the reference attribute for the object requirement unique ID is, select the attribute “Absolute Number” as shown in the below figure:
Doors will then present a window with the number of objects created and/or created, as below:
The final step will be to ensure that the import has been done correctly. For the object requirement below the only change was the allocating element updated with allocated element “System”.
This roundtrip process can be repeated when needed to synchronize textual requirements authored in the IBM Doors module or when new model elements traceability is done in Capella.
Architecture
The figure below shows the roundtrip directional flow that must be followed for textual requirements roundtrip synchronisation between an IBM Doors module and Capella requirements module.
In the figure below it can also be seen the tools attributes management and ownership:
- IBM Doors module: generates object unique IDs, which are associated to textual requirements and textual requirements are associated to attributes.
- Capella tool: holds and manages the requirements to model elements traceability within the project.
It is envisaged that other formats can be exported from the Capella tool, such as, model HTML pages and Word documents. The IBM Doors module can then be baselined as well as the Capella project can be created Git repositories for change control management, as below:
