Main Content

Link and Trace Requirements with IBM DOORS Next

You can link and trace Simulink® model elements and supported Model-Based Design artifacts to requirements in IBM® DOORS® Next (formerly known as IBM DOORS Next Generation or DNG) by importing DOORS Next requirements or by using direct linking.

Simulink Requirements™ imports IBM DOORS Next requirements as slreq.Reference objects, which are also called referenced requirements. When requirements change in DOORS Next, you can update the referenced requirements. The imported referenced requirements contribute to the implementation status, verification status, and change tracking. For more information, see Import Requirements from IBM DOORS Next. You can then link MATLAB® or Simulink Model-Based Design artifacts or other linkable items with the referenced requirements in the Simulink canvas or Requirements Editor. You can also navigate from the referenced requirement in Simulink Requirements to the original requirement in DOORS Next.

With direct linking, you link directly from MATLAB or Simulink to DOORS Next artifacts. You can establish traceability links and navigate directly from MATLAB or Simulink Model-Based Design artifacts to DOORS Next requirements. Direct linking does not require you to create additional files, as opposed to importing, which stores the requirements in an .slreqx file. However, the linking process requires additional setup steps, and the IBM DOORS Next requirements are not covered by Simulink Requirements analyses, such as implementation status, verification status, and change tracking.

With either linking method, you can insert backlinks in DOORS Next, which are links that allow you to navigate from the requirement in DOORS Next to the artifact in MATLAB or Simulink.

Configure IBM DOORS Next Session

To interface with IBM DOORS Next, you must configure MATLAB every session. At the MATLAB command prompt, enter:

slreq.dngConfigure
In the DOORS Server dialog box, provide the DOORS Next server address, port number, and service root as they appear in the web browser when accessing DOORS Next. If you do not see a port number, enter the default value of 443. In the Server Login Name and Server Login Password dialog boxes, enter your login credentials. In the DOORS Project dialog box, select the project and, if applicable, the configuration context. If your configuration context is not listed in the Select configuration stream or changeset list, load additional configurations by selecting <more>. For more information about configurations, see Specifying and Updating the IBM DOORS Next Configuration.

MATLAB then tests the connection in your browser. If the connection is successful, the MATLAB Connector Test dialog box appears with a confirmation message. Click OK. If the dialog does not appear or if an error appears after you enter slreq.dngConfigure, see the Tips section of slreq.dngConfigure.

Linking with Referenced Requirements

Use this approach when you want to link requirements in MATLAB or Simulink and track the implementation, verification, and change tracking in Simulink.

First, import requirements by selecting a DOORS Next module or by creating a query. For more information, see Import Requirements from IBM DOORS Next.

After you import DOORS Next requirements into a requirement set, you can link these referenced requirements the same way you link other slreq.Reference objects. For example, you can open a Simulink model, select a model element, then select the referenced requirement in the Requirements Editor and click Add Link > Link from Selected Simulink Object. See Requirement Links for more information.

Inserting Backlinks in DOORS Next

When you import requirements from DOORS Next from a module and create links to the imported referenced requirements from items in MATLAB or Simulink, you can manually insert backlinks in the DOORS Next module:

  1. Open the Requirements Editor. At the MATLAB command prompt, enter:

    slreq.editor

  2. In the Requirements Editor, click Show Links in the toolstrip to view the loaded link sets.

  3. Select the link set that contains the links that you want to use to insert backlinks in your DOORS Next module. Right-click the link set and select Update Backlinks.

  4. A dialog box displays the number of links that were checked for existing backlinks and the number of backlinks added. Click OK.

You can navigate to the original requirement by selecting the requirement in the Requirements Editor and clicking Show in Document.

When viewing DOORS Next items outside the module context, expand the Links pane, which displays any backlinks to MATLAB or Simulink under Link to. When working in the module context, select the item. In the right pane, select Selected Artifact, then select Artifact Links. The backlinks are displayed under Link to.

Directly Linking DOORS Next Requirements

Use this approach when you prefer to link directly to requirements in DOORS Next. Direct links do not require importing requirements.

After the setup is complete, you can establish direct links either by right-clicking an item and using the context menu, or by using the Outgoing Links dialog.

Link to Selected Requirements by Using the Context Menu

When you link to requirements in DOORS Next by using the context menu, you can insert a backlink when the link is created. You can also create the link in the module context and in the specified stream or changeset. If you create the link in the module context and insert a backlink, the backlink is also inserted in the module context and in the specified stream or changeset. To read more about streams and changesets, see Specifying and Updating the IBM DOORS Next Configuration.

Install the Simulink Requirements widget in IBM DOORS Next. For more information, see Install the Simulink Requirements Widget in IBM DOORS Next. To confirm the widget is operating as expected, in your DOORS Next project, in the Artifacts tab, select an item and verify that the widget contents update as expected.

Tip

Pin the Mini Dashboard to the page so that it is always visible and you know which selected ID is communicated to MATLAB.

You can verify that MATLAB is receiving information about your selection in DOORS Next. At the MATLAB command prompt, enter:

oslc.selection
The returned number should correspond to the numeric ID of the selected item in the DOORS Next browser.

When the widget is operating as expected, you can create links between Simulink linkable items and DOORS Next in one click when you use the context menu:

  1. In your DOORS Next project, select the Artifacts tab.

  2. Select the requirements that you want to link to by selecting the check box next to the requirement. The requirements that you select are displayed in the Simulink Requirements widget in the Mini Dashboard.

  3. In Simulink, right-click the Simulink model element that you want to link to the selected IBM DOORS Next requirements. Select Requirements > Link to Selected Item(s) in DOORS Next from the context menu.

  4. The DOORS Link Target dialog appears. If the Simulink Requirements widget is functioning as expected, then the Project Area and Requirement ID fields are populated with information from your selection.

  5. To create the link in the module context, select Link in module context. Then, set the Module context to the module that the requirement belongs to.

  6. To insert a backlink in DOORS Next, select Insert backlink. If the link is created in the module context, the backlink is also inserted in the module context.

  7. Click OK to create the link and, if selected, insert the backlink.

To navigate to the linked requirement in DOORS Next, right-click the same Simulink model element and select Requirements. The link appears at the top of the context menu.

If the widget in IBM DOORS Next is unavailable or fails to communicate with MATLAB due to security restrictions, you can create the link without selecting a requirement in DOORS Next:

  1. In Simulink, right-click the Simulink model element that you want to link to the selected IBM DOORS Next requirements. Select Requirements > Link to Selected Item(s) in DOORS Next from the context menu.

  2. The DOORS Link Target dialog box appears, but no information is populated. Set the Project Area to the project that you want to work with.

  3. In the Requirement ID field, enter the DOORS Next numeric ID of the requirement that you want to link to.

  4. To create the link in the module context, select Link in module context. Then, set the Module context to the module that the requirement belongs to.

  5. To insert a backlink in DOORS Next, select Insert backlink. If the link is created in the module context, the backlink is also inserted in the module context.

  6. Click OK to create the link and, if selected, insert the backlink.

Link to Requirements by Using the Outgoing Links Dialog Box

Creating links by using the Index tab of the Outgoing Links dialog does not require communication between MATLAB and the system browser.

  1. Right-click the Simulink model element that you want to link to IBM DOORS Next requirements.

  2. Select Requirements > Open Outgoing Links dialog.

  3. In the Outgoing Links dialog, click New and set Document type to DNG Requirement.

  4. Click Browse. In the DOORS Project dialog box, select the project to work with and, depending on the project, select the configuration context. If your configuration context is not listed in the drop-down, load more configurations by selecting <more>.

  5. The next step depends on whether you want to link to the requirement in the module context.

    • If you want to create links in the module context:

      1. Click the Document Index tab to see the list of module names.

      2. Double-click the module that you want to link to.

      3. When the list updates, select the requirement that you want to link to.

    • If your project doesn't have modules or if you don't want to create the link in the module context, enter the numeric ID of the DOORS Next link target requirement in the Location field.

      Note

      If you create a link to a requirement in the module context and then create more links to requirements in the same module, the links are created in the module context.

  6. To create the link, click OK or Apply to create the link.

When you create links using the Index tab in Outgoing Links dialog or by entering the ID in the dialog, the link is created without a backlink. You can post-insert backlinks in your DOORS Next project. See Insert Missing Backlinks.

Insert Missing Backlinks

If a requirement in your DOORS Next project does not contain a backlink because a backlink was not inserted when the link was created or because the backlink was deleted, you can insert missing backlinks:

  1. Open the Simulink model or other artifact that contains direct links to requirements in DOORS Next.

  2. Open the Requirements Editor by entering the following at the MATLAB command prompt:

    slreq.editor

  3. Select Show Links and select the link set containing the link that does not contain a backlink.

  4. Right-click the link set and select Update backlinks. The Backlinks Checked dialog appears and displays the number of missing backlinks added.

Note

When you insert missing backlinks with this method, backlinks are added for all direct links in the link set where the destination project matches your currently configured DOORS Next project. If your link set contains links to other DOORS Next projects, these links will not be processed. You will need to re-run the Update backlinks procedure after re-configuring your MATLAB session for the other project to insert backlinks in the other project.

Each backlink in DOORS Next is independent of the link stored in Simulink Requirements. If you later decide to delete the link in Simulink, the backlink will remain in DOORS Next until manually deleted. If you delete the backlink in DOORS Next, the change does not propagate to Simulink Requirements.

Additionally, the backlinks in DOORS Next will be visible to users of this configuration context, including users who do not have access to the Simulink source artifact.

To read more about updating backlinks, see Manage Navigation Backlinks in External Requirements Documents.

Navigate Between DOORS Next Requirements and Directly Linked Items

Once you've directly linked a linkable item in MATLAB or Simulink to a DOORS Next requirement, you can navigate to the requirement from MATLAB by using the Requirements Editor.

  1. Open the Requirements Editor by entering the following at the MATLAB command prompt:

    slreq.editor

  2. Select Show Links and select the link that you want to navigate.

  3. In the Details pane, under Properties, click the hyperlink next to Destination to navigate to the requirement in DOORS Next.

If you inserted backlinks in your DOORS Next project then you can navigate from the requirement in DOORS Next to the linked item in MATLAB or Simulink:

  1. In your DOORS Next project, in the desired stream or changeset, select the Artifacts tab.

  2. Select the desired requirement. If the requirement was linked in the module context, select the requirement in that module context.

  3. In the right pane, ensure the Selected Artifact tab is selected.

  4. In the right pane, select Artifact Links. Backlinks are listed under Links to.

  5. Click the backlink to navigate to the linked item in MATLAB or Simulink.

Specifying and Updating the IBM DOORS Next Configuration

Projects with configuration management enabled in IBM DOORS Next support multiple branches called streams and changesets (which are also referred to as configurations). Simulink Requirements enables you to update the outgoing link destination for an existing link in Simulink to the same requirement in a different stream or changeset.

Specifying the Configuration Stream or Changeset

Select the IBM DOORS Next project and the stream or changeset you want to work with. At the MATLAB command prompt, enter:

slreq.dngConfigure
For more information about the function, see slreq.dngConfigure.

Updating Stored Stream or Changeset by API

Simulink Requirements provides functions to manage your DOORS Next requirements when your stream or changeset changes:

Using the Simulink Requirements Widget to Synchronize and Update Session Context

The Simulink Requirements widget displays information about the current configuration stream context in Simulink Requirements. The widget indicates a mismatch between the active configuration stream contexts in Simulink Requirements and in IBM DOORS Next by displaying and highlighting the active Simulink Requirements configuration stream context in red:

To resolve a mismatch, click the red highlighted text in the widget and click Update in the DNG Configuration Context Mismatch dialog box. Alternatively, you can change the active configuration stream in IBM DOORS Next.

You can update the configuration context for existing links by either using the functions listed in Updating Stored Stream or Changeset by API or by using the Query Links from SL hyperlink in the Simulink Requirements widget.

  1. In DOORS Next, under the Simulink Requirements widget, click Query Links from SL. A new window opens in the browser with a summary of links for the selected requirements in DOORS Next.

  2. Click the Managed link configurations hyperlink to display the report on DOORS Next links in the current MATLAB session and grouped by the target configuration context attribute.

  3. Click redirect for the group of links that you want to associate with a different configuration context.

  4. When the window is updated, click the stream or changeset you want to associate with.

  5. Locate one of the streams or changesets whose links you updated, and confirm that the link now brings you to the expected configuration of the linked requirement.

See Also

Related Examples

More About