Link with Requirements in DOORS Next Generation Project

IBM® Rational® DOORS® Next Generation (DNG) is a requiremets management tool for IBM Rational Jazz platform. Linking file-based MBD artifacts (Simulink blocks, Test Cases, Data Dictionary entries) with items managed by shared server and accessed via web client requires certain configurtion steps before you can create new links. This example provides a step-by-step demonstration of DNG integration feature in Simulink Requirements.

The Hard Way: Direct Links between Simulink and DNG

You can link directly with DNG artifacts, using the Link to Selected Item(s) in DNG context menu shortcut in Requirements menu. This requires considerable overhead, because you access DNG using the web browser client, and links require notification about which one is the "selected item". The following several sections of this example show you how to set up your environment for direct linking with DNG.

Server-side configuration

Copy the Jazz server dngsllink_config subfolder in MATLAB_INSTALL_DIR/toolbox/slrequirements/slrequirements/resources/ into the DNG 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, your extensions folder may 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 DNG server configuration. Please see the DNG instructions for details:

https://jazz.net/wiki/bin/view/Main/RMExtensionsHostingGuide605

You need to edit server.xml file in the C:\[JAZZ_INSTALL_DIR]\server\liberty\servers\clm folder.

1. Open this file in a text editor, and locate this line:

<applicationMonitor dropinsEnabled='false' pollingRate='10s' updateTrigger='mbean'/>

2. change dropinsEnabled to 'true'.

3. Restart the server. Below is the screenshot from IBM's instruction:

Client Browser Configuration

Once dngsllink_config custom extension is available on your DNG server, each user interested in linking with DNG needs to add this custom widget to the Mini Dashboard in DNG client browser. After logging into DNG:

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 displays the Simulink Requirements widget:

Configuring MATLAB session

Use the slreq.dngConfigure commad to prepare your MATLAB session for linking with DNG. 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 DNG password each time.

1. When prompted, enter your DNG 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 DNG pages, enter the default value of "443".

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

3. When prompted, enter your DNG password and press Enter. After connection to the server, the list of available DNG projects is retrived.

4. Select the project and configuration stream. It is normal to see some warnings in MATLAB's command window when establishing connection with DNG. The feature will operate, unless there are errors.

5. A browser-to-localhost connection test runs automatically. This communication channel is required for your MATLAB® session to receive messages when you interact with DNG in system browser. A popup indicates that you are ready for linking:

6. If you do not see the confirmation message as shown above, it is possible that your system browser is blocking HTTPS connections to localhost. To resolve this, allow the connection. The exact steps depend on your browser. For example:

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

When you get a confirmation popup, it confirms that your browser instance can communicate with HTTPS listeners on your machine. It is best to reuse this same browser widnow for your DNG session, when linking with Simulink Requirements.

7. To test your browser without rerunning slreq.dngConfigure procedure, paste the following URL into your broser's address bar: https://localhost:31515/matlab/oslc/inboundTest

One-way Links from MATLAB/Simulink to DNG

In DNG, 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 DNG 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 make take a few secconds for MATLAB to retrieve additional data from DNG 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 DNG:

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 DNG Side

DNG integration feature in Simulink Requirements allows you to query MATLAB/Simulink links from DNG context. When you select an item from the artifacts list in DNG 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 DNG 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, it is important to ensure that all related linked artifacts on MATLAB/Simulink side are loaded in the current MATLAB session, and browser-to-MATLAB communication is allowed by the web browser. 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 DNG for Two-Way Traceability

If you prefer to always find your MATLAB/Simulink links in DNG 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 DNG, which you can see in the Links panel for the linked DNG item. You can use the hyperlinks in the Links pane to navigate from DNG item to linked objects in MATLAB/Simulink.

When enabling Modify destination for bi-directional linking option in Requirements Settings:

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

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

3. Links inserted into DNG by Simulink Requirements do not synchronize automatically. If you delete a link on Simulink side, links in DNG still exists. You need to remove these manually.

4. These links behave as shared. For example, if Simulink user A linked a DNG requirement to a block in his Simulink model, and user B linked the same DNG requirement with a different block in same or some other Simulink model, both users will see both links, and both links will navigate to the corresponding linked block, as long as the MATLAB/Simulink end of the link exists in both user's sessions.

rmipref('BiDirectionalLinking', true);

Improved Integration with DOORS Next Generation

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

  • direct linking depends on your ability to modify the DNG server configuration and install the custom Simulink Requirements gadget,

  • direct linking requires that you allow HTTPS communication between your system browser and the local MATLAB process, which could be considered a security risk when using same browser for external webpages,

  • 1-way links are difficult to discover from DNG side, and impose strict requirements on Simulink session state for links to become visible on DNG side,

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

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

  • built-in analysis in Simulink Requirements product cannot be applied to direct links.

To resolve these limitations and to bypass most of the complications, Simulink Requirements offiers an entirely different workflow option: you can cache a subset of DNG 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 DNG 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 without "dirtying" the server side, and you can use all the built-in analysis capabilities of Simulink Requirements product, including implementation and verification status, as well as change impact detection and management.

Capture DNG Collections into Simulink Requirements Set

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

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

As before, you will be prompted for the DNG login password, and possibly for the DNG server address and login name, if this is your initial connection for the current MATLAB session.

Document location selector will populate with names of all DNG 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 DNG contents into Simulink Requirements. You can import the specified module, including the herarchical relationships between DNG 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:

In both cases you get a top-level Import node with the ID that matches the name of your DNG project. The Summary text of the Import node will indicate the parameters used when capturing data from DNG. 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 DNG 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 essencial difference, however, is that you cannot unlock and modify the imported 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.

Linking with Captured DNG References

Now that you have captured DNG requirements collection of interest into a Requirement Set and saved it to .slreqx file, you can easily established traceability between Requirements and desing, then manage your Link Sets together with the rest of MBD artifacts, without affectig other users of sourced requirements on DNG server. For example, you can switch your Simulink design model into Requirements perspective view, then open the imported set of DNG 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 DNG references 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 DNG requiremets on server are updated or removed, you perform the automated update of captured 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.