Synchronize Requirements Traceability in IBM DOORS by Using Surrogate Modules

You can establish traceability between elements in your Simulink^® model and requirements in IBM^® DOORS^® without modifying the IBM DOORS requirements module by using surrogate modules. A surrogate module is a DOORS module that contains proxy objects that represent model elements from a Simulink model. You can use surrogate modules to see the traceability between DOORS requirements and Simulink model elements without opening the Simulink model. This image shows the relationship between the Simulink model, the surrogate module, and the IBM DOORS requirements modules.

You can establish the links by using Requirements Toolbox™ or IBM DOORS. After you establish the links and synchronize the traceability information between Requirements Toolbox and IBM DOORS, you can view the traceability information from the surrogate module. When you make changes to the Simulink model or add and remove links from the Simulink model to the surrogate module or to requirements in IBM DOORS, you can re-synchronize Requirements Toolbox and IBM DOORS to update the surrogate module and reflect the traceability changes.

Note

If you want to use Requirements Toolbox analysis tools such as implementation status, verification status, change tracking, and traceability matrices, you must import your third-party requirements to Requirements Toolbox. For more information, see Import Requirements from IBM DOORS.

Choose Traceability Source of Truth

Before creating a surrogate module, you must decide if Requirements Toolbox or IBM DOORS is the traceability source of truth. When you add or remove links in the source of truth, you can synchronize the traceability to the other application. Both tools allow you to create links without modifying the IBM DOORS requirements module.

You can make Requirements Toolbox the traceability source of truth by creating direct links from the Simulink model to the requirements in IBM DOORS. When you synchronize the traceability information to IBM DOORS, Requirements Toolbox creates links from the surrogate module to the IBM DOORS requirements module that match the direct links from the Simulink model.

Alternatively, you can make IBM DOORS the traceability source of truth by creating the surrogate module, then creating links from the surrogate module to requirements in IBM DOORS. When you synchronize the traceability information to Requirements Toolbox, Requirements Toolbox creates links from the Simulink model to the IBM DOORS requirements module that match the links from the surrogate module.

Traceability Source of Truth	Benefits	Link Creation and Synchronization
Requirements Toolbox	You can use the Requirements Toolbox user interface or APIs to create links. Requirements Toolbox creates and manages the link set file for you. You can include the link set file in a project that contains other design and test items. For more information, see Create Projects.	Create the direct links before you create the surrogate module. For more information, see Link Directly to Requirements in Third-Party Applications. Synchronize the links from Requirements Toolbox to IBM DOORS when you create the surrogate module.
IBM DOORS	You can use IBM DOORS to create and manage the links.	Create the links in IBM DOORS after you create the surrogate module. Synchronize the links from IBM DOORS to Requirements Toolbox after you create the surrogate module.

If you choose Requirements Toolbox as the traceability source of truth, disable bidirectional linking before you create the links from the Simulink model, because creating bidirectional links modifies the IBM DOORS requirements module. To disable bidirectional linking:

Open the Requirements Editor.
In the Links section, click .
In the Requirements Settings dialog box, select the Selection Linking tab.
Under When creating selection-based links, clear Modify destination for bidirectional linking.

Create Surrogate Modules

Before you can create a surrogate module, you must configure Requirements Toolbox for interaction with IBM DOORS. For more information, see Configure Requirements Toolbox for Interaction with Microsoft Office and IBM DOORS.

Note

You can only create surrogate modules for Simulink models that link to requirements in IBM DOORS and contain Simulink or Stateflow^® model elements. You cannot create surrogate modules for Simulink data dictionaries, MATLAB^® code files, Simulink Test™ files, System Composer™ models, or for models that contain other types of model elements.

To create the surrogate module:

Open an IBM DOORS project.
Open the Simulink model that contains direct links to requirements in IBM DOORS.
Open the Requirements Manager app. In the Simulink model, in the Apps tab, under Model Verification, Validation, and Test, click Requirements Manager.
In the Requirements tab, click Share > Synchronize with DOORS.
In the DOORS synchronization settings dialog box, set the file path and name for the surrogate module. Under DOORS surrogate module path and name, enter the path and name. You must specify the IBM DOORS project by using a relative path or a full path, followed by the surrogate module name.
- To add the surrogate module to the currently open IBM DOORS project, specify a relative path by entering a forward slash, and then ./ in front of the surrogate module name. For example, specifying ./MySurrogateModel adds a surrogate module called MySurrogateModel to the current IBM DOORS project.
- To add the surrogate module to a specified IBM DOORS project, specify the full path by entering the project name and the surrogate module name, separated by a forward slash. For example, specifying /MyProject/MySurrogateModel adds a surrogate module called MySurrogateModel to the IBM DOORS project called MyProject.
You can also get the full path of an IBM DOORS project or existing surrogate module by clicking Browse, selecting the project, and clicking OK.
Choose extra Simulink model elements to include in the surrogate module. Under Extra mapping additionally to objects with links, select an item from the list. If you choose None, the surrogate module contains only the Simulink model elements that link directly to requirements in IBM DOORS and their parent objects.

Tip
If IBM DOORS is the traceability source of truth, choose any setting except None so the surrogate module contains items that you can link to.
Choose whether to synchronize the traceability information:
- If Requirements Toolbox is the traceability source of truth, under Synchronizing links, select Update links during synchronization. Under Copy unmatched links, select from Requirements Toolbox to DOORS.
- If IBM DOORS is the traceability source of truth, under Synchronizing links, clear Update links during synchronization.
Choose whether to save the surrogate module and Simulink model after synchronization by selecting or clearing Save DOORS surrogate module and Save Simulink model (recommended) under After synchronization.
To save the current synchronization settings, click Save settings.
Create the surrogate module by clicking Synchronize.
If IBM DOORS is the traceability source of truth:
1. Create the links from the requirements module to the surrogate module. For more information, see Creating Links on the IBM website.
2. In Simulink, in the Requirements tab, click Share > Synchronize with DOORS.
3. Under Synchronizing links, select Update links during synchronization.
4. Under Copy unmatched links, select from DOORS to Requirements Toolbox.
5. Under Delete unmatched links, clear the selection.
6. Click Save settings.
7. Click Synchronize.
Requirements Toolbox adds links to the Simulink model to match the links from IBM DOORS requirements to the surrogate module.

If you create the surrogate module with incorrect settings, you can create a new surrogate module. In the Requirements tab, click Share > Synchronize with DOORS. In the DOORS synchronization settings dialog box, choose a different name for the surrogate module, update your settings, then click Synchronize. The Requirements: Surrogate Module Mismatch dialog indicates that the Simulink model was previously synchronized with a different surrogate module. Click Continue to create the new surrogate module.

For an example of creating surrogate modules, see Create Surrogate Module for a Fault-Tolerant Control System.

Navigate Between Simulink and IBM DOORS

After you synchronize the traceability between Requirements Toolbox and IBM DOORS, you can navigate between the Simulink model, the requirements in IBM DOORS, and the surrogate module.

To navigate from elements in the Simulink model to linked requirements in IBM DOORS, right-click the model element, select Requirements, and select the linked requirement in IBM DOORS.

The mouse points to linked requirement "1.1.1.3 Oxygen Sensor" in the Requirements context menu for a Simulink block called EGO.

To navigate from elements in the Simulink model to the corresponding item in the surrogate module, right-click the model element and select Requirements > 1. "DOORS Surrogate Item".

To navigate from requirements in IBM DOORS to linked items in the surrogate module, right-click the orange in-links arrow icon and, in the context menu, select the linked item in the surrogate module.

The mouse points to the linked EGO item in the surrogate module in the in-links context menu from the Oxygen Sensor requirement in IBM DOORS.

To navigate from items in the surrogate module to the linked requirements in IBM DOORS, right-click the red out-links arrow icon and, in the context menu, select the linked requirement.

To navigate from items in the surrogate module to the model element in the Simulink model, in IBM DOORS, click the item and select MATLAB > Select item.

The item 1.1.1 EGO is selected in a surrogate module in IBM DOORS. The mouse points to the Select item option in the MATLAB menu.

Re-Synchronize to Reflect Changes

If you make changes to the Simulink model, you can re-synchronize Requirements Toolbox and IBM DOORS to update the surrogate module. Additionally, if you add or remove links in the traceability source of truth, you can re-synchronize to reflect those changes in the other tool.

To re-synchronize Requirements Toolbox and IBM DOORS:

In Simulink, open the Requirements Manager app.
In the Requirements tab, click Share > Synchronize with DOORS.
To enable updating the links, enable link synchronization. Under Synchronizing links, select Update links during synchronization.
To synchronize the links between Requirements Toolbox and IBM DOORS, under Copy unmatched links, select from Requirements Toolbox to DOORS or from DOORS to Requirements Toolbox, depending on which is the traceability source of truth.
To delete links from the surrogate module that no longer have a matching link from the Simulink model to the requirements in IBM DOORS, under Delete unmatched links, select Remove unmatched links in DOORS. To delete links from the Simulink model that no longer have a matching link from the surrogate module to the requirements in IBM DOORS, under Delete unmatched links, select Remove unmatched links in Simulink.
Click Save settings.
Click Synchronize.

The DOORS synchronization settings dialog is shown for a model called myModel. The link settings are configured to copy unmatched links from Requirements Toolbox to DOORS and delete unmatched links in DOORS.

If you removed model elements from the Simulink model, the model elements remain in the surrogate module but the Block deleted? column in IBM DOORS indicates that the model element no longer exists in the Simulink model.