Managing Requirements for Fault-Tolerant Fuel Control System (IBM DOORS)

This example uses:

The Requirements Management Interface (RMI) provides tools for creating and reviewing links between Simulink® objects and requirements documents. This example illustrates linking model objects to requirements stored in IBM® DOORS®. For more information using the RMI, see Managing Requirements for Fault-Tolerant Fuel Control System (Microsoft Office).

Setup RMI for DOORS

Make sure your DOORS installation is configured for communication with RMI. Run MATLAB® as Administrator and execute rmi('setup'). If DOORS Client installation is detected, RMI will prompt to install the required API files. You only have to do this once after reinstalling either DOORS or MATLAB. For more information, see Configure Requirements Toolbox for Interaction with Microsoft Office and IBM DOORS.

Simulink Model and DOORS Modules Used in this Example

For the purposes of this example, an example model of a fault-tolerant fuel control system called slvnvdemo_fuelsys_doorsreq.slx is included. Use it for the exercises presented below.

Open the Simulink model manually or by evaluating the following code.

open_system('slvnvdemo_fuelsys_doorsreq');

You can use any temporary DOORS module for basic link creation exercises below, and you can use the included DemoRMI.dpa archive for a more advanced exercise of Surrogate Module Synchronization.

Set Up Requirements Manager to Work with Links

In the Apps tab, open Requirements Manager.
In the Requirements tab, ensure Layout > Requirements Browser is selected.
In the Requirements Browser, in the View drop-down menu, select Links.

In this example, you will work exclusively in the Requirements tab and any references to toolstrip buttons are in this tab.

Linking via Outgoing Link Dialog

You can link a model object to requirements stored in a DOORS database (DOORS objects). You do not need to modify DOORS documents when creating links. The most hands-on way to create new links is via Outgoing Link dialog. This requires manually filling-in link attribute fields. See next subsection for an easier automated way.

Navigate to the Metered Fuel Scope block.

rmidemo_callback('locate','slvnvdemo_fuelsys_doorsreq/Metered Fuel');

Right-click the block and select Requirements > Open Outgoing Links dialog... from the context menu. The Outgoing Link dialog opens.
Click New to create a new requirement.
Set Document type to IBM DOORS.

Specify a unique target module ID in the Document input field or use the Browse button to select the target module in DOORS database.
Enter target object ID in the Location Identifier field, or use the Document Index tab to select the target object in a chosen module.
Click Apply or OK to store the new requirement link.
Right-click the same Simulink block again to see the new link label listed in the top portion of the context menu.

Linking via Context Menu Shortcuts

An easier way to establish new links is via Selection Linking Shortcuts. Right-click a block and select Requirements > Link to Selection in DOORS.

Links creation via context menu shortcuts do not require any manual input. Link target destination is determined by the current selection in DOORS, and the Description field is set to the corresponding Object Heading or to DOORS Object Text when there is no Heading. Because the Description is used for navigation shortcuts in context menus, number of characters limit applies.

RMI supports bidirectional linking with requirements in DOORS, but you will start with one-directional links. Disable bi-directional linking in the Requirements tab of the model by clicking Link Settings > Linking Options and unchecking Modify destination for bidirectional linking under the When creating selection-based links.

Alternatively, you can evaluate the following code.

rmipref('BiDirectionalLinking', false);

We will cover bidirectional linking later. Now try this out:

Select any object in your test module in DOORS.
Navigate to the throttle sensor block.

rmidemo_callback('locate','slvnvdemo_fuelsys_doorsreq/throttle sensor');

Right click the block and select Requirements > Link to Selection in DOORS in the context menu to create a link.
Right-click the throttle sensor block again and locate the link label at the top of Requirements context menu to confirm that the link was added. You may use Outgoing Link dialog later to adjust the description label or User Tag keywords.

Current Selection Linking via Outgoing Link Dialog

The Use current button in the Outgoing Link dialog box provides a combined approach:

Right-click a block in the model and select Requirements > Open Outgoing Links dialog... from the context menu.
Push the New button to add another link item.
Select DOORS Item in the Document type drop-down box.
In DOORS module window, click on the object that you want to link.
Click the Use current button to automatically fill in all the input fields with the data from the current selected DOORS object.
Adjust the Description as required.
Save the changes by clicking OK or Apply.

You can also use the Use current button to redirect an existing link:

Select the required new target object in DOORS.
In Outgoing Link dialog, click on the list item you want to update.
Click the Use current button to update link attributes.

Viewing and Navigating Links from Simulink to DOORS

You highlight and navigate DOORS links in the same way you do that with other types of links.

In the Requirements tab, click Highlight Links to highlight all requirements in the example model. You can also evaluate the following to highlight the links.

rmi('highlightModel', 'slvnvdemo_fuelsys_doorsreq');

Make sure DOORS is running and logged in.
Right-click on one of the highlighted objects that you used to create new links in the previous section.
Select Requirements from the context menu. The labels of the links you created should be visible at the top.
Click on the link label. Your test module opens in DOORS with the correct object selected.

Be careful to only try this with the links you created. There are other links in the model that will not work just yet. We will cover fixing those links in sections below.

About Surrogate Modules and Synchronization

Surrogate module workflow is supported for DOORS to allow two-way linking without needing to modify DOORS requirements modules. The following picture illustrates the workflow.

A new formal DOORS module, referred as a surrogate module, is automatically generated by Simulink to be used as a DOORS representation of the Simulink model. You can choose to map all the objects in your model, or only those with links to DOORS, or pick one of the intermediate options as discussed in the documentation.

You can create direct links to requirements in DOORS, as demonstrated in previous sections (marked 3 in the picture) and optional matching direct links from DOORS documents to Simulink objects, as demonstrated in the last section of this example (marked 2 in the picture).

Additionally, with the surrogate module present in DOORS, you can establish links within DOORS between the items in surrogate modules and requirements stored in DOORS (marked 1 in the picture), while navigation to and from Simulink is provided by surrogate item links (marked 4 in the picture).

Surrogate module workflow provides the following advantages:

Bidirectional linking is possible without the need to modify documents in DOORS or the models in Simulink. All required information is stored in the surrogate modules and corresponding link modules.
You can manage and analyze links in the DOORS environment without necessarily running Simulink, including using the native reporting capabilities of DOORS.

Below is an example screenshot of the autogenerated Surrogate module. Note that DOORS hierarchy mirrors the structure of the originating Simulink model, and DOORS object headers match Simulink object names:

Synchronizing Your Simulink Model with a DOORS Database

Normally, you would navigate to the Requirements tab in your Simulink model and use Share > Synchronize with DOORS to create a new DOORS surrogate module for your Simulink model.

For the purposes of this example, an existing DOORS project is provided as an archive, including the surrogate module with links to other modules. To try out the interactive features of this example, restore the project into your DOORS database, and then re-synchronize the example model as explained below. Note that this archive was created in DOORS version 9.1 and may not work with earlier versions of DOORS.

Use the File > Restore feature in DOORS and point it to DemoRMI.dpa archive provided in the present working directory. If your already have a project named DemoRMI in your DOORS database, DOORS appends a number to the project name. As shown in the screenshot below, the project includes one link module and three formal modules. One formal module is the DOORS surrogate for the slvnvdemo_fuelsys_doorsreq model; the other two are example modules produced by importing Microsoft® Word documents from Managing Requirements for Fault-Tolerant Fuel Control System (Microsoft Office).

Extract all the included modules and open the surrogate module.
Note the red and orange link navigation triangles in two of the extracted modules. Right-click to navigate between modules. These links are preserved through the backup-restore procedure.

Try navigating from the extracted surrogate module to the corresponding object in Simulink from DOORS:

Click 1.11.4.1 fuel rate in the slvnvdemo_fuelsys_doorsreq surrogate module.
In main menu of the module window, click MATLAB > Select Item. A correct subsystem diagram opens and the corresponding input is highlighted.

Navigation from Simulink objects to the surrogate module is broken, because the extracted modules have new numeric IDs in your DOORS database, trying to navigate DOORS Surrogate Item link on any object will produce an error. To repair DOORS Surrogate Item links on all objects in the slvnvdemo_fuelsys_doorsreq model after you have successfully restored the DemoRMI project, resynchronize the Simulink model with the restored instance of the surrogate.

In the model window, select the Requirements tab and then click Share > Synchronize with DOORS to open a the Synchronization Settings dialog box.

Enter the following settings, using the correct DOORS path for in the DOORS surrogate module path and name input field, depending on the location of the restored project, or simply make it a current project in DOORS and use "./" notation: enter "./slvnvdemo_fuelsys_doorsreq".

Do not enable the Save Simulink model checkbox at the bottom, you will not be able to save changes to example model unless you use a writable copy.
Simulink might warn you about the previous synchronization path. Click Continue to proceed with the new path. You may get the following message in the command window: "No update needed for the surrogate module". Your restored surrogate module is correct as is.
Retry navigation from any object in the model to corresponding DOORS object in the surrogate module by right clicking the Simulink block and selecting Requirements > 1. "DOORS Surrogate Item" on the context menu. This should now highlight the corresponding DOORS item in the surrogate module.

Using Model Advisor for RMI Consistency Checking

The example model comes with some pre-existing links to DOORS document, FuelSys Design Description module. Similarly to the original DOORS Surrogate Item links, these links are broken, because the restored copy of the module has a new ID in your local database. For example, right-click the Airflow calculation subsystem in the model and select "1.2.1 Mass Airflow estimation" from the Requirements context menu. This will produce an error message. Evaluate the following code to navigate to the Airflow calculation block.

rmidemo_callback('locate',['slvnvdemo_fuelsys_doorsreq/fuel rate controller/' ...
    'Airflow calculation']);

We will now fix these links using RMI consistency checking in Model Advisor.

In the Simulink model window in the Requirements tab, click Check Consistency to bring up the Model Advisor graphical interface.
Locate Identify requirement links with missing documents item under Requirements consistency checking and select it with a mouse.
Click Run This Check button at the top-left of the right-hand panel. Blocks with broken links are listed. You can fix listed inconsistencies one-by-one or, in the Model Advisor pane you can use Fix All link at the bottom. We will use the Fix All shortcut, because we know that all broken links need to be redirected to the same restored copy of the original module.

In the Model Advisor pane, click Fix All link at the bottom - DOORS database browser comes up.

Locate the restored FuelSys Design Description module in your database and select it with a mouse.
Click OK to close DOORS database browser.
Click Run This Check again. The check should now pass.
Re-try navigation: right-click the Airflow calculation subsystem in the model and select Requirements > "1.2.1 Mass Airflow estimation" from the context menu. This will now highlight the correct object in one of the DOORS modules you restored from the included archive.

Copying Link Information from Simulink to DOORS

Now that your direct links from Simulink to DOORS are correct, you can use synchronization to copy link information into the DOORS database. Links will be duplicated in the DOORS project, where you can use native DOORS navigation, analysis and reporting tools. These links between the surrogate and other DOORS modules can even be reused with a new copy of the model.

Re-open Share > Synchronize with DOORS dialog and configure the following settings. Make sure to disable the Remove unmatched in DOORS checkbox, because there are unmatched links in the restored project that you need later.

Click Synchronize button at the bottom.
Give it a couple of seconds and check the surrogate module in DOORS. It should now display more links - some that existed in the original restored project (links to the FuelSys Requirements Specification module), and some that were just copied from Simulink (links to the FuelSys Design Description module).
Locate the Airflow calculation subsystem.

rmidemo_callback('locate',['slvnvdemo_fuelsys_doorsreq/fuel rate controller/' ...
    'Airflow calculation']);

Navigate to the corresponding surrogate object using the Requirements > 1. "DOORS Surrogate Item" on the context menu for this block.
The new red triangle shows an outgoing link for 1.12.5 Airflow calculation item in DOORS. Right-click to navigate this DOORS link - this brings you to item 1.2.1 Mass airflow estimation in the FuelSys Design Description module.

Copying Link Information from DOORS to Simulink

Synchronization via surrogate module provides a convenient way to propagate system requirements updates in DOORS to corresponding Simulink implementation elements. To demonstrate this workflow, the restored project contains DOORS links from the surrogate module to the FuelSys Requirements Specifications DOORS module that are not present in the Simulink model. In DOORS, navigate back to the module that you restored in the section "Synchronizing Your Simulink Model with a DOORS Database".

Starting in the FuelSys Requirements Specification module, locate 2.1 Normal Mode of Operation.
Use the DOORS link to navigate to the "1.11.3 fuel" item in the surrogate module by right-clicking the yellow link in the DOORS module, and clicking through on the context menu to navigate to "1.11.3 fuel" item in the slvnvdemo_fuelsys_doorsreq DOORS module.
While "1.11.3 fuel" is selected, click MATLAB > Select Item in the surrogate module main menu to locate the corresponding source object in Simulink model.
Right-click the located fuel input element in Simulink and check Requirements in the context menu. 1. "DOORS Surrogate Item" is the only available link: there are no links to documents.

To copy link information from DOORS to Simulink, re-synchronize with Update links during synchronization enabled, and select from DOORS to Simulink.

Re-open the Share > Synchronize with DOORS dialog.
Configure the following synchronization options:

It is now OK to enable Remove unmatched in Simulink checkbox. After the previous synchronization step, there are no unmatched links in Simulink.

Keep some diagrams open and highlighted to visualize changes when new links are added in Simulink.

Click Synchronize. The surrogate module window may come up to the front, but there are no red markers, because there are no changes in DOORS.
Navigate back to the fuel input in Simulink, or evaluate the following.

rmidemo_callback('locate','slvnvdemo_fuelsys_doorsreq/engine gas dynamics/fuel');

Right-click and expand the Requirements Traceability section of the context menu. Notice the new link below the DOORS Surrogate Item link: "->2.1 Normal Mode of Operation". The arrow prefix indicates that this requirement was not created in Simulink but copied from DOORS.
Click the new link to navigate to the corresponding requirement in DOORS - 2.1 Normal Mode of Operation section opens in FuelSys Requirements Specification module.

Review Your Changes Using User Tags

You now apply the user tag filter to confirm the changes you made to the model. All DOORS requirements that existed in the original version of the example model were tagged "design". You now use this fact to selectively highlight or hide these links:

Navigate back to the fuel rate controller subsystem and in the Requirements tab, click Highlight Links.

rmidemo_callback('open_highlight','slvnvdemo_fuelsys_doorsreq/fuel rate controller');

In the Requirements tab, click Link Settings > Linking Options to open the Requirements Settings dialog.
Navigate to the Filters tab and configure as shown below, checking the Filter links by keywords when highlighting and reporting requirements box and entering design in the Include links with any of these tags field.

Check the highlighted objects in diagrams. These are the links that existed in the original model.
Now modify the Filters settings as shown below to exclude "design" links:

Check the Simulink model. The highlighting now points to links you have just copied from DOORS database.

Removing Links in Simulink and DOORS

Synchronization also allows you to maintain consistency when links are removed. For example:

Navigate to the fuel input again.

rmidemo_callback('locate','slvnvdemo_fuelsys_doorsreq/engine gas dynamics/fuel');

Right-click, select Requirements > Open Outgoing Links Dialog....
Select the "->2.1 Normal Mode of Operation" item in the dialog.
Click Delete button to remove the item from the list.
Click OK to apply the changes.
Check the context menu again to confirm that the link is gone.
Note that the link is still present in DOORS, connecting 1.11.3 fuel in the surrogate module to "2.1 Normal Mode of Operation" in the FuelSys Requirements Specification module.
Purge the removed link from DOORS by re-running synchronization with link updates option set to Simulink to DOORS and the Remove unmatched in DOORS checkbox enabled.

Click Synchronize. Observe the link in DOORS disappear.

Similarly, when links are removed in DOORS and you need to propagate the changes to Simulink, rerun synchronization with the DOORS to Simulink option selected and Remove unmatched in Simulink checkbox enabled.

Optional Direct Links from DOORS to Simulink

When using selection linking with DOORS, you have an option to automatically insert reference objects into DOORS documents to enable direct navigation from DOORS to Simulink without the need for the surrogate module.

WARNING: The DOORS document is modified when you use this feature of RMI.

In the Requirements tab, click Link Settings > Linking Options to open the Requirements Settings dialog.
Enable the Modify destination for bidirectional linking checkbox.

Now, when you use selection linking, Simulink creates navigation objects. There are two types of references to choose from. When Use ActiveX for incoming links option at the bottom of Selection Linking tab is ON, RMI will insert new DOORS objects with Simulink icon and destination object label as DOORS Object Text. With Use ActiveX... option OFF, RMI will insert External Link hyperlinks. For the following exercise, try both options and decide what works best for you.

Locate and select "2.2.6 Speed Sensor Failure" in FuelSys Requirements Specification module.
Locate the Speed Estimate block in the Simulink model.

rmidemo_callback('locate',['slvnvdemo_fuelsys_doorsreq/fuel rate controller/' ...
    'Sensor correction and Fault Redundancy/Speed Estimate']);

Right-click the block and select Requirements > Link to Selection in DOORS.
Observe the new object inserted as the first child of the target object in DOORS.

Click the just inserted navigation object in DOORS, or use MATLAB > Select Item from the main menu of the DOORS module window.
When using External Link hyperlinks, navigate the MATLAB hyperlink in the expanded cascade of right-click context menu.
The correct diagram opens in Simulink and the linked block is highlighted.

Note: You have just enabled navigation from DOORS to Simulink model without needing to save any changes in the model. Consider this workflow when modifications to models need to be avoided.

Normally, when the Simulink model is saved after creating links, two-way navigation is possible while bypassing the complexity of surrogate synchronization process. However, there is the disadvantage of cluttering DOORS documents with Simulink navigation objects.

To avoid making unintentional modifications to your DOORS documents, re-open the Requirements Settings dialog to the Selection Linking tab and disable Modify destination for bidirectional linking checkbox.