Requirements Traceability with IBM DOORS Next

You can link and trace Simulink^® model elements and other supported Model-Based Design artifacts to requirements in IBM^® DOORS^® Next (formerly known as IBM DOORS Next Generation, and often abbreviated as DNG).

You can link and trace requirements between Simulink Requirements™ and IBM DOORS Next by importing DOORS Next requirements or by using direct linking.

You can import a subset of requirements into Simulink Requirements as slreq.Reference objects, which are referred to as referenced requirements. The captured collection can be a specified module or a list of matches for a given query. You can then link MATLAB^® or Simulink Model-Based Design artifacts or linkable items with the referenced requirements and create the links by dragging and dropping in the Simulink Editor. You can also navigate from the referenced requirement in Simulink Requirements to the original requirement in DOORS Next. When requirements change in DOORS Next, you can update the previously captured referenced requirements. The imported referenced requirements contribute to the implementation status (see Review Requirements Implementation Status), verification status (see Review Requirements Verification Status), and change tracking (see Track Changes to Requirement Links).

With direct linking, you can establish traceability links and navigate directly from MATLAB or Simulink Model-Based Design artifacts or linkable items to DOORS Next artifacts. Linkable items are items within a Model-Based Design artifact, like a Simulink block or a Simulink requirement. You do not need additional files to store DOORS Next requirements. However, the linking process requires additional setup steps, and because the requirements managed by IBM DOORS Next are not available in Simulink Requirements, they are not covered by Simulink Requirements analyses such as implementation status, verification status, and change tracking.

After using 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

Start each MATLAB session by configuring MATLAB and Simulink for DOORS Next traceability. 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. 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 drop-down, load more 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 slreq.dngConfigure tips.

Linking with Imported Requirements

Use this approach when you prefer to perform linking in MATLAB or Simulink and want to track the implementation and verification status and change tracking analysis in Simulink.

You can import requirements by selecting a DOORS Next module or by creating a query. Requirements are imported as slreq.Reference objects.

When you import requirements from DOORS Next, you must import the requirements into a new requirement set. You cannot import multiple sets of DOORS Next requirements into the same requirement set.

Note

When importing from a DOORS Next project with Configuration Management enabled, you must set the desired Configuration Context for your MATLAB session before importing. For more information on MATLAB session setup, see slreq.dngConfigure. The imported requirement set will be associated with this configuration for navigation using Show in document updating using Update from server actions. For more information, see Linking and Updating Imported DOORS Next Items in Simulink Requirements.

Importing DOORS Next Requirements from a Module

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

   slreq.editor

2. In the Requirements Editor, click Import.

   In the Importing Requirements dialog box, set Document type to IBM DOORS Next.

   

3. Set the Document location to the project that you want to work with.

4. Under Get requirements from, select Full module hierarchy (takes time if large module). Wait for the DNG Module selector to populate.

   

5. Select the desired module from the DNG Module drop-down menu.

6. Adjust the name of the Requirement Set.

7. Click Import and wait for the process to import the data from the server into Simulink Requirements. The Requirements Editor will display the hierarchy of the imported items.

Importing DOORS Next Requirements by Using Queries

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

   slreq.editor

2. In the Requirements Editor, click Import.

   In the Importing Requirements dialog box, set Document type to IBM DOORS Next.

   

3. Set the Document location to the project that you want to work with.

4. Under Get requirements from, select Filter by query (flat list of matched items).

5. Click Query Builder to open the OSLC Query Builder and specify your query. Use the drop-down menus next to Object Type to choose the object type to import.

   For example, you can import only stakeholder requirements by using this query:

   

6. To create a query with parameters other than Object Type, click Add Filter.

   Note

   If an attribute is only defined for a given Object Type, you must select the Object Type before you can filter by that attribute.

7. When you are done building your query, click Add to Query and then click OK. In the Importing Requirements dialog, the Raw query string is populated.

8. Adjust the name of the Requirement Set.

9. Click Import and wait for the process to import the data from the server into Simulink Requirements. The Requirements Editor will display the hierarchy of the imported items.

Linking and Updating Imported DOORS Next Items in Simulink Requirements

After you import DOORS Next requirements into a requirement set, you can link these referenced requirements the same way you link with 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.

If you update the items in DOORS Next after importing them to Simulink Requirements, you can update the requirement set to reflect the changes. In the Requirements Editor, select the top import node and, in the Details pane, under Requirement Interchange, click Re-import Module or Re-run Query, depending on the type of import you originally did.

Tip

Re-importing a large module might take some time. If you know which item has changed on the server, you can select that referenced requirement in the Requirements Editor and in the Details pane, under Properties, click Update from Server to quickly update that imported requirement.

You can use the Requirements Editor to navigate from the referenced requirement to the original requirement in DOORS Next. Select the referenced requirement derived from the original requirement that you want to navigate to. In the Details pane, under Properties, click Show in document.

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

After the setup is complete, you can establish direct links by using either the Outgoing Links dialog or by right-clicking an item in your model and using Requirements > Link to Selected Item(s) in DOORS Next.

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.

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

Linking with 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, you might need to select the configuration context. If your configuration context is not listed in the drop-down, load more configurations by selecting <more>.

5. Once the project is selected, the next step depends on whether your project has modules or not.

   • If your project doesn't have modules, enter the numeric ID of the DOORS Next link target requirement into the Location field.

   • If your DOORS Next project has modules:

     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.

     This method inserts the link in the module context.

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

When you create links using the Outgoing Links 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:

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