Link with Requirements in IBM DOORS Next

IBM® Engineering Requirements Management DOORS® Next® (formerly known as DOORS Next Generation, or DNG) is a requirements management tool in IBM Collaborative Lifecycle Management platform. Traceability of file-based MBD artifacts (Simulink blocks, Test Cases, Data Dictionary entries) with items managed on a shared server and accessed by means of web browser can be accomplished in a few different ways. Your choice of workflow will depend on the needs and constraints of a given project. This example gives a review of DOORS Next integration features supported by Simulink Requirements, it includes step-by-step setup instruction and compares alternative workflows. Working with IBM® DOORS® Next® is supported on Microsoft Windows®.

Overview

Simulink Requirements allows two different ways to integrate with DOORS: direct linking between design elements and web-based requirements, and live cache approach where you establish traceability natively in Simulink Requirements workspace. Each approach has unique advantages and challenges.

Direct Linking approach allows to establish one-click navigation from your design to associated requirements in DOORS, and from DOORS requirements back to linked design elements. Because this approach requires system web browser interactions, DOORS server-side configuration is needed, as well as system browser customization by the user. Because link destinations are 'external' to Simulink Requirements, you can only use a limited subset of Simulink Requirements product features. For example, additional scripting will be required for Implementation and Verification status analysis, and for Change Tracking. On the other hand, you have a choice to store link information in DOORS server data, so that links can be viewed and analyzed on DOORS side without MATLAB/Simulink session.

Live Cache approach relies on importing a snapshot of DOORS Requirements into Simulink Requirements. Navigation from design or test to a related requirement in DOORS is still possible but involves an intermediate proxy entry in Simulink Requirements set. Because both ends of your created links belong to Simulink family domains, you can take full advantage of traceability features in Simulink Requirements product. Cached content can be updated anytime when there are changes on DOORS server side. Also, because links are stored only on MATLAB/Simulink side, this approach avoids the problems of stale or conflicting links on the server. This approach does not necessarily requires server-side configuration.

Details below will help you decide which approach is best for your project.

Direct Linking

You can link directly with DOORS Next artifacts, using the Link to Selected Item(s) in DNG shortcut in Requirements menu for Simulink objects, MATLAB code, or Simulink Test Cases. This capability implies that MATLAB session is aware of your selection in DOORS Next web browser, which is why extra setup steps are required:

  1. Simulink Requirements custom widget files must be copied to DOORS Next server, to make the widget available for DOORS Next users.

  2. Each user interested in linking with Simulink must add the widget to Mini Dashboard in DOORS Next web interface.

  3. System browser should be allowed to communicate with MATLAB's embedded HTTPS server (localhost:31515).

Each required setup step is detailed below.

Server-side configuration

This step is performed by DOORS Next server administrator once per IBM server installation. You will need to copy the dngsllink_config subfolder from MATLAB_INSTALL_DIR/toolbox/slrequirements/slrequirements/resources/ into the DOORS Next server's custom extensions folder. The location of custom extensions folder depends on the particular Jazz server version. For example, if you are running Jazz server version 6.0.6 on a Windows computer, your extensions folder should be here:

C:\Program Files\IBM\JazzTeamServer_6.0.6\server\liberty\servers\clm\dropins\war\extensions

You may also need to "enable dropins" in DOORS Next server configuration. Instruction below is based on the following IBM's page: https://jazz.net/wiki/bin/view/Main/RMExtensionsHostingGuide605

  1. Locate server.xml file in the C:\[JAZZ_INSTALL_DIR]\server\liberty\servers\clm folder.

  2. Open this file in a text editor, and locate this line: <applicationMonitor dropinsEnabled='false' pollingRate='10s' updateTrigger='mbean'/>

  3. Change dropinsEnabled to 'true'.

  4. Restart the server.

Below is the screenshot of IBM's original instruction:

Client Browser Configuration

This step needs to be performed once by each DOORS Next user interested in linking with MATLAB/Simulink. After dngsllink_config custom extension files are available on your DOORS Next server, follow these steps to add this custom widget to the Mini Dashboard in DOORS Next web interface. Ensure that your DOORS Next server is secure (HTTPS), or the widget won't function correctly. After logging into DOORS Next:

1. In Mini Dashboard, click the Add Widget button:

Custom gadgets menu will open.

2. Click Add OpenSocial Gadget:

3. Specify the URL that matches the location of Simulink Requirements widget code on your server. For example:

https://JAZZSERVERNAME:9443/extensions/dngsllink_config/dngsllink_config.xml:

4. Click Add Widget. Your Mini Dashboard should now display the Simulink Requirements widget:

Configuring MATLAB session

This step needs to be performed each time MATLAB session is restarted. Use the slreq.dngConfigure command to prepare your MATLAB session for linking with DOORS Next. Follow the prompts and provide the requested values. The server URL, port number, and username is stored in your personal user preferences. However, you have to enter the DOORS Next password each time.

1. When prompted, enter your DOORS Next server domain name and the port number. If you do not see any port number displayed in the address bar of your system browser when viewing DOORS Next pages, enter the default value of "9443".

2. Enter your DOORS Next user name, which may be different from your computer login user name:

3. When prompted, enter your DOORS Next password and press Enter. It is normal to see a few warnings in MATLAB's command window when establishing connection with DOORS Next. The feature will operate, unless there are errors.

4. After successful connection to the server is established, a dialog box appears to allow you select a DOORS Next projects from the list, as well as the preferred configuration stream (if enabled for the selected project).

5. A browser-to-localhost connection test runs automatically. This communication channel is required for your MATLAB session to receive messages when you select DOORS Next item in the web browser. You may see an empty browser page, and a popup from MATLAB indicating that you are ready for linking:

6. If you do not see the confirmation message as shown above, your system browser may be blocking HTTPS connections to https://localhost:31515. To resolve this issue, allow the connection. The exact steps depend on your web browser. For example:

In this case, click Advanced and then click the hyperlink to allow the connection:

If you still do not get the popup from MATLAB, your MATLAB session may be listening on a different (non-default) port number, which can happen when starting more than one instance of MATLAB on the same host. To quickly check the active port number, run this command: connector.securePort. If this command returns anything other than 31515, make sure that you do not have any other MATLAB instances running on the same host, then restart MATLAB. Repeat connector.securePort command to confirm the correct port number. Rerun slreq.dngConfigure setup steps.

Once you see the confirmation dialog, do not close the browser window. It is best to reuse this same browser window for your DOORS Next session when linking with Simulink Requirements, because you have just authorized this instance of the web browser application to communicate with MATLAB. If you open a new browser window, depending on web browser type and version, secure communication with MATLAB may be blocked again. If this happens, you can simply copy-paste the following URL into your browser's address bar: https://localhost:31515/matlab/oslc/inboundTest then, again, click on "Proceed to localhost" to allow connection with MATLAB.

One-way Links from MATLAB/Simulink to DOORS Next

In DOORS Next, open Show artifacts view for the requirements collection of interest, and select the checkbox for the item you want to link with. You will notice that the Simulink Requirements widget is updated to confirm the ID and label of the selected item. This information is sent to MATLAB when you interact with DOORS Next item checkboxes.

In Simulink, right-click a block you want to link from, then select Link to Selected Item(s) in DNG under Requirements context menu. It may take a few seconds for MATLAB to retrieve additional data from DOORS Next and create the link.

Click the same block again to see the new link at the top of Requirements submenu. Click the link label to navigate from Simulink to DOORS Next:

Note: if you do not see the Link to Selected Item(s) in DNG shortcut in the Requirements context menu, you may need to enable DOORS linking option in Selection Linking tab of Requirements Settings dialog:

Alternatively, you can control this setting via the command-line API:

rmipref('SelectionLinkDoors',true);

Reviewing MATLAB/Simulink Links from the DOORS Next Side

DOORS Next integration feature in Simulink Requirements allows you to query MATLAB/Simulink links from DOORS Next context. When you select an item from the artifacts list in DOORS Next page, the Simulink Requirements widget displays information about the selected item, and provides a hyperlink for querying links as stored in Simulink Requirements. Click Query Links from SL to get a popup with the list of incoming links for the selected DOORS Next item.

One should keep in mind that these links cannot be discovered when MATLAB is not running, or when the corresponding data files are not loaded on Simulink side. For example, the link we created above is stored in .slmx file for the linked Simulink model. If this .slmx file is not loaded in the current MATLAB/Simulink session, no links will be reported in the browser popup. When relying on Query Links from SL to review links, you must first ensure that:

  1. MATLAB is running

  2. MATLAB session is configured for DOORS Next linking (slreq.dngConfigure step was completed)

  3. all related linked design artifacts are loaded

You can review the list of loaded Link Sets by switching the Requirements Editor into the Links View (more on this below).

Store Links in DOORS Next for Two-Way Traceability

If you prefer to always find your MATLAB/Simulink links in DOORS Next context, independent from whether Simulink is running or whether the linked MBD artifacts are loaded, you have an option of truly bi-directional linking. Re-open the Requirements Settings dialog to the Selection Linking tab and enable the Modify destination for bi-directional linking checkbox.

Alternatively, you can use the command-line API rmipref('BiDirectionalLinking',true) to toggle the option. Once bi-directional linking is enabled, each new link you create will not only add an entry in the Simulink Requirements Link Set, but will also insert an External Web Link from DOORS Next, which you can see in the Links panel for the linked DOORS Next item. You can use the hyperlinks in the Links pane to navigate from DOORS Next item to linked objects in MATLAB/Simulink.

When enabling Modify destination for bi-directional linking option in Requirements Settings, consider the following:

1. Every DOORS Next user will see these links when working with same version of this DOORS Next project, even if they do not use Simulink or do not have access to linked MBD artifacts.

2. Navigation from DOORS Next will fail, unless MATLAB is running, and linked artifact is either already loaded or can be found on MATLAB path.

3. Links inserted into DOORS Next by Simulink Requirements do not synchronize automatically. If you delete a link on Simulink side, link in DOORS Next remains, and you need to remove it manually.

4. Simulink Requirements product does not check for conflicts in DOORS Next links. For example, if Simulink user A linked a DOORS Next requirement to a block in a Simulink model, the links inserted in DOORS Next will behave consistently for this user, but user B will see the link from DOORS Next, and can navigate it to the same block in his version of same Simulink model, even if his copy of the Simulink model does not store a link from Simulink block to DOORS Next. If user B decides to create his own link from same block to same DOORS Next item while his personal preference is configured for bi-directional linking, this will insert a duplicate link on DOORS Next side. If user A later changed his mind and deleted a link from block to Simulink, and then tries to cleanup the backlinks from DOORS Next, both links will need to be deleted on DOORS Next side, and now user B will be left with only a one-way link from Simulink to DOORS Next. Using personal streams and changesets in DOORS Next should minimize this sort of problems.

rmipref('BiDirectionalLinking', true);

Working with Cached Requirements Collections

As can be seen from the above, both 1-way and 2-way direct linking solutions have disadvantages:

  • direct linking requires that you modify the DOORS Next server configuration and install the Simulink Requirements custom gadget,

  • direct linking requires HTTPS communication between your system browser and the local MATLAB process, which could present a security risk when using this same browser for external web pages,

  • 1-way links are difficult to discover from DOORS Next side, and are entirely hidden unless linked artifacts are loaded in current MATLAB session,

  • 2-way links may become difficult to manage in large multi-user projects or when switching between DOORS Next streams and changesets,

  • you cannot control the Type of links from DOORS Next to MATLAB/Simulink, the links are always of generic "Link To" type,

  • built-in analysis in Simulink Requirements product do not cover the direct links.

To resolve these limitations and to bypass most of the complications, Simulink Requirements offers an entirely different workflow option: you can cache a subset of DOORS Next requirements into an internally managed Simulink Requirements Set, then perform all linking and analysis in Simulink Requirements environment as you would do with the usual internally managed or imported entries.

You will not be able to edit cached DOORS Next contents locally, and you will not immediately see the updates when the sourced requirements are updated on the server, but you get the advantage of native linking support between Simulink artifacts, including drag-drop linking with Simulink objects, without disturbing the server side, and you can use all the features of Simulink Requirements product for reviewing and analysing links, including implementation and verification status, as well as change impact detection and management.

Capture DOORS Next Collections into Simulink Requirements Set

In the Requirements Editor, click Import in the main menu:

Select "IBM DOORS Next Generation" in Document type selector:

As before, you will be prompted for the DOORS Next login password. If this is your initial connection for the current MATLAB session, you will also be prompted to confirm the server URL and the username.

Document location selector will populate with names of all DOORS Next project available on the specified server. Once you select the Project to import from, additional option controls will appear:

Two different modes are supported for capturing DOORS Next contents into Simulink Requirements. You can import the specified module, including the hierarchical relationships between DOORS Next requirements, or you can switch into the Filter by query mode, which produces a flat list of matched requirements.

When using the Filter by query option, in most cases, you will not need to type the query expression manually, but use the Query Builder dialog to configure the filter:

When you import using Filter by query, you can only use one filter at a time.

In both cases you get a top-level Import node with the ID that matches the name of your DOORS Next project. The Summary text of the Import node will indicate the parameters used when capturing data from DOORS Next. You can now work with the imported items as you would with the usual entries in Simulink Requirements:

  • create links with related MBD artifacts and use all the built-in analysis capabilities.

  • navigate to the original requirements in DOORS Next by clicking the Show in document button,

  • refresh the captured content using the Update from Server button,

  • when you save to a .slreqx file, the links are saved to a corresponding .slmx file.

The one essential difference, however, is that you cannot unlock and modify cached requirements: all the needed updates should happen on the server side. You then use the Re-run query button for the Import node (or the Update from Server button for a single requirement) to pull-in updates from the server.

You cannot import images or tables from DOORS Next to Simulink Requirements.

Linking with Captured DOORS Next Items

Now that you have captured DOORS Next requirements collection of interest into a Requirement Set and saved it to .slreqx file, you can easily established traceability between Requirements and design, then manage your Link Sets together with the rest of MBD artifacts, without affecting other users of the same DOORS Next project. For example, you can switch your Simulink model into Requirements perspective view, then open the captured set of DOORS Next requirements in requirements browser, and create links by drag-drop between the requirements browser and the blocks in your Simulink diagram. You will see linked blocks highlighted together with linked cached DOORS Next items in the requirements browser.

Reviewing and Analyzing Traceability Data

As with links to internally-managed requirements, you can switch into the Links view to access more details about links, and to edit link properties such as Type, Description, Rationale, keywords, and Comments.

As with all other Simulink Requirements links, you enable display of Implementation and Verification status to check which requirements lack coverage, and which tests need to be rerun or updated.

When DOORS Next requirements on the server are updated or removed, you perform the automated update of cached requirements subsets in Simulink Requirements, and you check the Links View for flagged stale or broken links, to quickly identify the needed design or testing changes.