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.

If you import requirements from IBM DOORS Next to Requirements Toolbox™, the imported requirements become slreq.Reference objects, which are 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 Requirements Toolbox to the original requirement in DOORS Next.

If you use direct linking to link the requirements, then you create a link between the requirements in MATLAB or Simulink and the 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 Requirements Toolbox 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.

1. At the MATLAB command prompt, enter:

   slreq.dngConfigure

2. In the DNG Server Login Configuration dialog box, enter the DOORS Next server address, port number, and service root as they appear in the web browser when accessing DOORS Next. Enter your username and password, or enter the name of a custom authentication callback function. For more information, see setCustomLoginProvider. Click OK.

   If you do not see a port number in the web browser, enter the default value of 443.

3. 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>. To display global configurations in the configurations list, at the MATLAB command line, enter:

   rmipref("OslcUseGlobalConfig",true);

   For more information, see rmipref and Specifying and Updating the IBM DOORS Next Configuration.

Tip

You can also programmatically establish a connection between your MATLAB session and an IBM DOORS Next server without using the DNG Server Login Configuration dialog box or DOORS Project dialog box. For more information, see slreq.dngConfigure.

MATLAB tests the connection by opening a window 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 Tips for using slreq.dngConfigure.

Note

If you plan to create direct links to requirements in IBM DOORS Next, you must leave the test connection browser window open, because this instance of the web browser is authenticated to communicate with MATLAB. Use this web browser to select requirements in your IBM DOORS Next project to create direct links. You can re-open the test connection browser window by copying and pasting this address in the browser address bar: https://localhost:31515/matlab/oslc/inboundTest.

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 or test, select a model element or test case, and then create a link to the selected referenced requirement in the Requirements Editor. You can also create a link without leaving the Simulink model by clicking and dragging a requirement from the Requirements Perspective. For more information, see:

• Link Requirements to Model Artifacts

• Link Test Cases to Requirements

• View and Link Requirements in Simulink

If you update the requirements in DOORS Next after importing them to Requirements Toolbox, you can update the requirement set to reflect the changes. For more information, see Update Referenced Requirements. If the update changes or removes a referenced requirement that has links, the links have a change issue. For more information, see Track Changes to Requirement Links.

After you create a link, you can edit the link type in the Requirements Editor. For more information, see Link Types.

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 do not have 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 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. Linking to requirements in DOORS Next by using the context menu requires additional setup in the Requirements Editor, and in your DOORS Next server.

To create links using the context menu, you first need to ensure that selection-based linking is enabled with IBM DOORS Next.

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

   slreq.editor

2. In the Links section of the toolstrip, click Preferences.

3. In the Requirement Settings dialog, in the Selection Linking tab, next to Enabled Applications, ensure that DOORS is selected.

Install the MathWorks Requirements Toolbox widget in IBM DOORS Next and enable dropins. For more information, see Configure an IBM DOORS Next Server for Integration with Requirements Toolbox. To confirm the widget is operating, 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, you can create links between Simulink linkable items and DOORS Next 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 MathWorks Requirements Toolbox widget in the Mini Dashboard pane.

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 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.

   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.

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 IBM DOORS Next.

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.

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. After you create the links, you can insert backlinks in your DOORS Next project for requirements that are missing backlinks. 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 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.

When you update backlinks, the software removes backlinks from the external document if the original link in Requirements Toolbox no longer exists. For more information, see Manage Navigation Backlinks in External Requirements Documents.

Note

Requirements Toolbox only removes the backlinks when the current configuration context in MATLAB matches the configuration context in IBM DOORS Next.

The backlinks in DOORS Next are visible to users of this configuration context, including users who do not have access to the MATLAB or Simulink source artifact.

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 right 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.

5. Under Links to, click the backlink to navigate to the linked item in MATLAB or Simulink.

If you didn't insert backlinks in your DOORS Next project, you can use the MathWorks Requirements Toolbox widget to query links for a given requirement.

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

2. Select the desired requirement. Ensure that the MathWorks Requirements Toolbox widget updates to reflect the selected requirement.

3. In the MathWorks Requirements Toolbox widget, click Query Links from SL. The Links from MATLAB/Simulink window opens in the browser.

   Note

   The linked artifact in MATLAB or Simulink must be loaded for the link to appear in the browser window.

   

4. Click the hyperlink under Source Object to navigate to the 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). Requirements Toolbox 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

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

• Find the number of links in an slreq.LinkSet object to a specific DOORS Next stream or changeset with slreq.dngCountLinks.

• Query your DOORS Next project for known streams or changesets with slreq.dngGetProjectConfig.

• Identify streams or changesets linked in an slreq.LinkSet object with slreq.dngGetUsedConfig.

• Update existing links to point to a different stream or changeset of the DOORS Next requirements when the stream or changeset changes with slreq.dngUpdateConfig.

Using the MathWorks Requirements Toolbox Widget to Synchronize and Update Session Context

The MathWorks Requirements Toolbox widget displays information about the current configuration stream context in Requirements Toolbox. The widget indicates a mismatch between the active configuration stream contexts in Requirements Toolbox and in IBM DOORS Next by displaying and highlighting the active Requirements Toolbox 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 MathWorks Requirements Toolbox widget.

1. In DOORS Next, under the MathWorks Requirements Toolbox 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 updates, 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.