Synchronize Simulink Models with IBM Rational DOORS Databases by using Surrogate Modules

Synchronize a Simulink Model to Create a Surrogate Module

The first time that you synchronize your model with the DOORS^® software, the DOORS software creates a surrogate module.

In this tutorial, you synchronize the sf_car model with the DOORS software.

Note

Before you begin, make sure you know how to create links from a Simulink^® model object to a requirement in a DOORS database.

To create a surrogate module, start the DOORS software and open a project. If the DOORS software is not already running, start the DOORS software and open a project.
Open the sf_car model.
```
openExample('sf_car.slx')
```
Rename the model to sf_car_doors, and save the model in a writable folder.
Create links to a DOORS formal module from two objects in sf_car_doors:
- The transmission subsystem
- The engine torque block inside the Engine subsystem
Save the changes to the model.
In the sf_car model, navigate to the Apps tab and open the Requirements Manager.
In the Requirements tab, select Share > Synchronize with DOORS.
The DOORS synchronization settings dialog box opens.
For this tutorial, accept the default synchronization options.
The default option under Extra mapping additionally to objects with links, None, creates objects in the surrogate module only for the model and any model objects with links to DOORS requirements.
Note
For more information about the synchronization options, see Customize IBM Rational DOORS Synchronization.
Click Synchronize to create and open a surrogate module for all DOORS requirements that have links to objects in the sf_car_doors model.
After synchronization with the None option, the surrogate module, a formal module named sf_car_doors, contains:
- A top-level object for the model (sf_car_doors)
- Objects that represent model objects with links to DOORS requirements (transmission, engine torque), and their parent objects (Engine).
Save the surrogate module and the model.

Create Links Between Surrogate Module and Formal Module in an IBM Rational DOORS Database

The surrogate module is the interface between the DOORS formal module that contains your requirements and the Simulink model. To establish links between the surrogate module and the requirements module, copy the link information from the model to the surrogate module:

Open the sf_car_doors model.
In the Requirements tab, select Share > Synchronize with DOORS.
In the DOORS synchronization settings dialog box, select two options:
- Update links during synchronization
- from Simulink to DOORS.
Click Synchronize.
The RMI creates links from the DOORS surrogate module to the formal module. These links correspond to links from the Simulink model to the formal module. In this example, the DOORS software copies the links from the engine torque block and transmission subsystems to the formal module, as indicated by the red triangles.

Resynchronize IBM Rational DOORS Surrogate Module to Reflect Model Changes

If you change your model after synchronization, the RMI does not display a warning message. If you want the surrogate module to reflect changes to the Simulink model, resynchronize your model.

In this tutorial, you add a new block to the sf_car_doors model, and later delete it, resynchronizing after each step:

In the sf_car_doors model, make a copy of the vehicle mph (yellow) & throttle % Scope block and paste it into the model. The name of the new Scope block is vehicle mph (yellow) & throttle %1.
In the Requirements tab, select Share > Synchronize with DOORS.
In the DOORS synchronization settings dialog box, set the Extra mapping additionally to objects with links option to Complete - All blocks, subsystems, states, and transitions. Click Synchronize.
After the synchronization, the surrogate module includes the new block.
In the sf_car_doors model, delete the newly added Scope block and resynchronize.
The block that you delete appears at the bottom of the list of objects in the surrogate module. Its entry in the Block Deleted column reads True.
Save the surrogate module.
Save the sf_car_doors model.

Navigate with the Surrogate Module

Navigate Between Requirements and the Surrogate Module in the DOORS Database

The surrogate module and the requirements in the formal module are both in the DOORS database. When you synchronize your model, the DOORS software creates links between the surrogate module objects and the requirements in the DOORS database.

Navigating between the requirements and the surrogate module allows you to review the requirements that have links to the model without starting the Simulink software.

To navigate from the surrogate module transmission object to the requirement in the formal module:

In the surrogate module object for the transmission subsystem, right-click the right-facing red arrow.
Select the requirement name.
The formal module opens, at the Transmission Requirements object.

To navigate from the requirement in the formal module to the surrogate module:

In the Transmission Requirements object in the formal module, right-click the left-facing orange arrow.
Select the object name.
The surrogate module for sf_car_doors opens, at the object associated with the transmission subsystem.

Navigate Between DOORS Requirements and the Simulink Module via the Surrogate Module

You can create links that allow you to navigate from Simulink objects to DOORS requirements and from DOORS requirements to the model. If you synchronize your model, the surrogate module serves as an intermediary for the navigation in both directions. The surrogate module allows you to navigate in both directions even if you remove the direct link from the model object to the DOORS formal module.

Navigate from a Simulink Object to a Requirement via the Surrogate Module. To navigate from the transmission subsystem in the sf_car_doors model to a requirement in the DOORS formal module:

In the sf_car_doors model, right-click the transmission subsystem and select Requirements > 1. “DOORS Surrogate Item”. (The direct link to the DOORS formal module is also available.)
The surrogate module opens, at the object associated with the transmission subsystem.
To display the individual requirement, in the surrogate module, right-click the right-facing red arrow and select the requirement.
The formal module opens, at Transmission Requirements.

Navigate from a Requirement to the Model via the Surrogate Module. To navigate from the Transmission Requirements requirement in the formal module to the transmission subsystem in the sf_car_doors model:

In the formal module, in the Transmission Requirements object, right-click the left-facing orange arrow.
Select the path to the linked surrogate object: /sf_car Project/sf_car_doors > 4. transmission.
The surrogate module opens, at the transmission object.
In the surrogate module, select MATLAB > Select item.
The linked object is highlighted in sf_car_doors.

Customize IBM Rational DOORS Synchronization

DOORS Synchronization Settings

When you synchronize your Simulink model with a DOORS database, you can:

Customize the level of detail for your surrogate module.
Update links in the surrogate module or in the model to verify the consistency of requirements links among the model, and the surrogate and formal modules.

The DOORS synchronization settings dialog box provides the following options during synchronization.

DOORS Settings Option	Description
DOORS surrogate module path and name	Specifies a unique DOORS path to a new or an existing surrogate module. For information about how the RMI resolves the path to the requirements document, see Document Path Storage.
Extra mapping additionally to objects with links	Determines the completeness of the Simulink model representation in the DOORS surrogate module. `None` specifies synchronizing only those Simulink objects that have linked requirements, and their parent objects. For more information about these synchronization options, see Customize the Level of Detail in Synchronization.
Update links during synchronization	Specifies updating any unmatched links the RMI encounters during synchronization, as designated in the Copy unmatched links and Delete unmatched links options.
Copy unmatched links	During synchronization, selecting the following options has the following results: from Simulink to DOORS: For links between the model and the formal module, the RMI creates matching links between the DOORS surrogate and formal modules. from DOORS to Simulink: For links between the DOORS surrogate and formal modules, the RMI creates matching links between the model and the DOORS modules.
Delete unmatched links	During synchronization, selecting the following options has the following results: Remove unmatched in DOORS: For links between the formal and surrogate modules, when there is not a corresponding link between the model and the DOORS modules, the RMI deletes the link in DOORS. This option is available only if you select the from Simulink to DOORS option. Remove unmatched in Simulink: For links between the model and the DOORS modules, when there is not a corresponding link between the formal and surrogate modules, the RMI deletes the link from the model. This option is available only if you select the from DOORS to Simulink option.
Save DOORS surrogate module	After the synchronization, saves changes to the surrogate module and updates the version of the surrogate module in the DOORS database.
Save Simulink model (recommended)	After the synchronization, saves changes to the model. If you use a version control system, selecting this option changes the version of the model.

Resynchronize a Model with a Different Surrogate Module

You can synchronize the same Simulink model with a new DOORS surrogate module. For example, you might want the surrogate module to contain only objects that have requirements to DOORS, rather than all objects in the model. In this case, you can change the synchronization options to reduce the level of detail in the surrogate module:

In the DOORS synchronization settings dialog box, change the DOORS surrogate module path and name to the path and name of the new surrogate module in the DOORS database.
Specify a module with either a relative path (starting with ./) or a full path (starting with /).
The software appends relative paths to the current DOORS project. Absolute paths must specify a project and a module name.
When you synchronize a model, the RMI automatically updates the DOORS surrogate module path and name with the actual full path. The RMI saves the unique module ID with the module.
If you select a new module path or if you have renamed the surrogate module, and you click Synchronize, the Requirements: Surrogate Module Mismatch dialog box opens.
Click Continue to create a new surrogate module with the new path or name.

Customize the Level of Detail in Synchronization

You can customize the level of detail in a surrogate module so that the module reflects the full or partial Simulink model hierarchy.

In Synchronize a Simulink Model to Create a Surrogate Module, you synchronized the model with the Extra mapping additionally to objects with links option set to None. As a result, the surrogate module contains only Simulink objects that have requirement links, and their parent objects. Additional synchronization options, described in this section, can increase the level of surrogate detail. Increasing the level of surrogate detail can slow down synchronization.

The Extra mapping additionally to objects with links option can have one of the following values. Each subsequent option adds additional Simulink objects to the surrogate module. You choose None to minimize the surrogate size or Complete to create a full representation of your model. The Complete option adds all Simulink objects to the surrogate module, creating a one-to-one mapping of the Simulink model in the surrogate module. The intermediate options provide more levels of detail.

Drop-Down List Option	Description
`None (Recommended for better performance)`	Maps only Simulink objects that have requirements links and their parent objects to the surrogate module.
`Minimal - Non-empty unmasked subsystems and Stateflow charts`	Adds all nonempty Stateflow^® charts and unmasked Simulink subsystems to the surrogate module.
`Moderate - Unmasked subsystems, Stateflow charts, and superstates`	Adds Stateflow superstates to the surrogate module.
`Average - Nontrivial Simulink blocks, Stateflow charts and states`	Adds all Stateflow charts and states and Simulink blocks, except for trivial blocks such as ports, bus objects, and data-type converters, to the surrogate module.
`Extensive - All unmasked blocks, subsystems, states and transitions`	Adds all unmasked blocks, subsystems, states, and transitions to the surrogate module.
`Complete - All blocks, subsystems, states and transitions`	Copies all blocks, subsystems, states, and transitions to the surrogate module.

Resynchronize to Include All Simulink Objects

This tutorial shows how you can include all Simulink objects in the DOORS surrogate module. Before you start these steps, make sure you have completed the tutorials Synchronize a Simulink Model to Create a Surrogate Module and Create Links Between Surrogate Module and Formal Module in an IBM Rational DOORS Database.

Open the sf_car_doors model that you synchronized in Synchronize a Simulink Model to Create a Surrogate Module and again in Create Links Between Surrogate Module and Formal Module in an IBM Rational DOORS Database.
In the Requirements tab, select Share > Synchronize with DOORS.
The DOORS synchronization settings dialog box opens.
Resynchronize with the same surrogate module, making sure that the DOORS surrogate module path and name specifies the surrogate module path and name that you used in Synchronize a Simulink Model to Create a Surrogate Module.
For information about how the RMI resolves the path to the requirements document, see Document Path Storage.
Update the surrogate module to include all objects in your model. To do this, under Extra mapping additionally to objects with links, from the drop-down list, select Complete - All blocks, subsystems, states and transitions.
Click Synchronize.
After synchronization, the DOORS surrogate module for the sf_car_doors model opens with the updates. All Simulink objects and all Stateflow objects in the sf_car_doors model are now mapped in the surrogate module.
Scroll through the surrogate module. Notice that the objects with requirements (the engine torque block and transmission subsystem) retain their links to the DOORS formal module, as indicated by the red triangles.
Save the surrogate module.

Detailed Information About The Surrogate Module You Created. Notice the following information about the surrogate module that you created in Resynchronize to Include All Simulink Objects:

The name of the surrogate module is sf_car_doors, as you specified in the DOORS synchronization settings dialog box.
DOORS object headers are the names of the corresponding Simulink objects.
The Block Type column identifies each object as a particular block type or a subsystem.
If you delete a previously synchronized object from your Simulink model and then resynchronize, the Block Deleted column reads true. Otherwise, it reads false.
These objects are not deleted from the surrogate module. The DOORS software retains these surrogate module objects so that the RMI can recover these links if you later restore the model object.
Each Simulink object has a unique ID in the surrogate module. For example, the ID for the surrogate module object associated with the Mux block in the preceding figure is 11.
Before the complete synchronization, the surrogate module contained the transmission subsystem, with an ID of 3. After the complete synchronization, the transmission object retains its ID (3), but is listed farther down in the surrogate module. This order reflects the model hierarchy. The transmission object in the surrogate module retains the red arrow that indicates that it links to a DOORS formal module object.

Synchronization with IBM Rational DOORS Surrogate Modules

Synchronization is a user-initiated process that creates or updates a DOORS surrogate module. A surrogate module is a DOORS formal module that is a representation of a DOORS model hierarchy.

When you synchronize a model for the first time, the DOORS software creates a surrogate module. The surrogate module contains a representation of the model, depending on your synchronization settings. (To learn how to customize the links and level of detail in the synchronization, see Customize IBM Rational DOORS Synchronization.)

If you create or remove model objects or links, keep your surrogate module up to date by resynchronizing. The updated surrogate module reflects any changes in the requirements links since the previous synchronization.

Note

The RMI and DOORS software both use the term object. In the RMI, and in this document, the term object refers to a Simulink model or block, or to a Stateflow chart or its contents.

In the DOORS software, object refers to numbered elements in modules. The DOORS software assigns each of these objects a unique object ID. In this document, these objects are referred to as DOORS objects.

You use standard DOORS capabilities to navigate between the Simulink objects in the surrogate module and requirements in other formal modules. The surrogate module facilitates navigation between the Simulink model object and the requirements, as the following diagram illustrates.

Advantages of Synchronizing Your Model with a Surrogate Module

Synchronizing your Simulink model with a surrogate module offers the following advantages:

You can navigate from a requirement to a Simulink object without modifying the requirements modules.
You avoid cluttering your requirements modules with inserted navigation objects.
The DOORS database contains complete information about requirements links. You can review requirements links and verify traceability, even if the Simulink software is not running.
You can use DOORS reporting features to analyze requirements coverage.
You can separate the requirements tracking work from the Simulink model developers' work, as follows:
- Systems engineers can establish requirements links to models without using the Simulink software.
- Model developers can capture the requirements information using synchronization and store it with the model.
You can resynchronize a model with a new surrogate module, updating any model changes or specifying different synchronization options.