Track Requirement Links with a Traceability Matrix

Traceability matrices allow you to easily view requirements and their links to other items. Traceability matrices show links between requirements, model or test entities, data dictionaries, and code, and allow you to navigate to link sources or destinations. For example, you can:

• View links between items.

• Create and delete links.

• Inspect and navigate link sources and destinations.

• Focus the display on a hierarchy of a specific artifact or item.

• Apply artifact-specific filters to rows, columns, and cells.

• View and highlight unlinked items.

• View and highlight items with associated change issues and clear the change issues.

• Perform batch operations when you select multiple cells.

Generate a Traceability Matrix

You can create a traceability matrix with two or more artifacts. You can use:

• Requirements Toolbox™ requirement sets

• Simulink^® models

• System Composer™ models

• Simulink Test™ test files

• Simulink data dictionaries

• MATLAB^® M-files

To open the Traceability Matrix window, use one of these approaches:

• In the Requirements Editor, click Traceability Matrix.

• In a Simulink model, in the Requirements tab, select Share > Open Requirements Traceability Matrix.

• At the MATLAB command line, enter:

  slreq.generateTraceabilityMatrix

To create a traceability matrix:

1. In the Traceability Matrix window, click Add.

2. Generate a matrix with either two artifacts or multiple artifacts.

   • To create a matrix with only two artifacts, select the Left and Top artifacts from the Select Artifacts dialog.

     

   • To create a matrix with multiple artifacts, click Select Multiple Artifacts. In the Configure Matrix dialog, add artifacts from the Available Artifacts pane to the left or top artifact list by clicking and dragging, or by right-clicking the artifact and selecting Add to the left or Add to the top. Remove an artifact from a list by pointing to the artifact and clicking the remove icon (), or by right-clicking the artifact and selecting Remove Artifacts.

     

3. Click Generate Matrix. You can reconfigure the artifacts in the matrix by clicking Configure Matrix, reconfiguring the artifacts, and clicking Update Matrix.

The artifacts in this image are a requirement set and a Simulink model. The requirements are listed on the left and the blocks of the Simulink model are listed on the top.

If you make changes to your artifacts, click Update to refresh your traceability matrix.

Note

Unresolved links are not displayed in the traceability matrix.

When you create a traceability matrix with multiple artifacts, a solid blue line indicates the division between artifacts.

Configure a Matrix with Multiple Artifacts

When you create or update a matrix with multiple artifacts, you can use the Configure Matrix dialog to arrange the artifacts by clicking and dragging to move an artifact from one list to another or reorder a list by dragging an artifact within a list.

You can add, remove, or arrange multiple artifacts at a time when you hold Ctrl and select multiple artifacts.

When you select an artifact in the Available Artifacts pane, any artifacts that contain links between the selected artifact are highlighted. When you add artifacts to the matrix configuration, the expand icon () in the matrix preview indicates that artifacts have links between them.

In order to be able to add an artifact to the traceability matrix, the artifact must either:

• Be loaded in your MATLAB workspace or Simulink

• Contain links to a loaded artifact

• Be associated with a loaded link set

Modify the Traceability Matrix View

The traceability matrix is a grid where the rows correspond to items from the left artifact and the columns correspond to items from the top artifact. The arrow icon () in a cell indicates that there is a link between the item in that row and column. The arrow icon points from the source item to the destination item.

When you click an arrow icon, you see information about the link.

Expand and Collapse Links

Initially, some rows and columns in your matrix may be collapsed. The expand icon () appears when a link is obscured because one or both of the hierarchies in the row or column containing the linked items are collapsed. To expand the hierarchies, double-click the expand icon ().

When you click the expand icon, you see the left and top items that correspond to that cell.

When you click on the items in the information box, the item opens in the associated application for that artifact type. For example, if you click on a requirement, the Requirements Editor window opens and displays the specified requirement.

Focus the Display

You can focus the display on the hierarchy of a specific item in your traceability matrix. Select the artifact or item whose hierarchy you want to display. Click Scope or right-click the item and click Focus the display.

Your traceability matrix only shows the selected part of the hierarchy. To show the entire hierarchy of the artifact, right-click the artifact again and click Display Entire Hierarchy.

For matrices with multiple artifacts, you can also focus the display on one of the artifacts by clicking the artifact from the list at the top of the matrix. To remove the focus from just one artifact, click Show All in the artifact list at the top of the matrix.

To expand the hierarchy of an artifact, right-click on the artifact whose hierarchy you want to expand and click Expand All. To collapse the hierarchy of an artifact, right click on the artifact whose hierarchy you want to collapse and click Collapse All.

Apply Filters

You can apply filters from the Filter Panel to the top artifact, the left artifact, or the cells. Click the filter to apply it, and click it again to remove it.

Each artifact has type-specific filters. When you create a traceability matrix with multiple artifact types, the pane lists filters by artifact types and uses icons to indicate the type. The Missing Links filter and all filters under Cell always appear.

If you apply a filter to an artifact, the matrix only shows items with those specific properties. For example, if, under Top, you click Missing Links, the traceability matrix only shows items from the top artifact that are not linked to other items. However, if a parent item does not have these specific properties but one or more of its children does, then the parent item and links to the parent item appear in the matrix, but are dimmed. For example, if you apply the Leaf Block filter to a model, the matrix shows subsystem blocks that contain leaf blocks, but dims subsystem blocks and links to subsystem blocks.

If you apply a filter to the cells, the matrix only shows the links that have those properties. However, no rows or columns are omitted. For example, if, under Cell, you click With Change Issues, the traceability matrix only shows the links that have change issues, but shows all rows and columns.

When you add a filter to the left or top artifacts of the traceability matrix, the filter appears at the top of the matrix next to the artifact name. You can clear the filters by clicking Clear Filter or, in the Filter Panel, by clicking the filter again.

If one of the artifacts in your traceability matrix is a Simulink model, then you can apply the Missing Expected Links filter. This filter displays unlinked Simulink blocks or subsystems that require links to meet HISL 0070 (Simulink).

Highlight Missing Links

To highlight unlinked cells in your traceability matrix, click Highlight Missing Links. The unlinked items in your traceability matrix are highlighted in yellow.

The unlinked items are highlighted even if they are not visible in the current matrix view. View the hierarchy for the entire traceability matrix to see all items with missing links. See Focus the Display.

Work with Links in the Traceability Matrix

Add a New Link

Create a link by clicking on a cell, then click Create Link or Create in the information box to create a link between the item in the row and the item in the column.

The Create Link window populates the link source and destination. You can reverse the link source and destination by clicking the reverse button (). The link is saved in the link set associated with the artifact that the source item belongs to. If there is no link set associated with that artifact, a link set is created with the same name as the artifact.

Note

If you create a traceability matrix using the same requirement set for the left and top artifact, you cannot create a link where the source and destination items are the same requirement. You also cannot create a link where the source or destination item is the requirement set.

Remove a Link

Remove a link by clicking on a cell containing a link and clicking Remove Links or pressing Del. The Remove Links dialog box appears and shows the link artifacts, type, and label. Click Remove to remove the link.

View and Clear Change Issues for Links

A link has a change issue if the requirement associated with the link changes. To learn how to enable change tracking and use the Requirements Editor to view and clear change issues, see Track Changes to Requirement Links.

You can view links with change issues in the traceability matrix by applying the With Change Issues filter or by selecting Highlight Missing Links > Show Changed Links Only. You can highlight links with change issues by clicking Highlight Missing Links > Highlight Changed Links. The row, column, and cell corresponding to the link with a change issue are highlighted in red.

To clear a change issue for a link, select the cell containing the link and click Clear Change Issue.

Perform Batch Operations on Multiple Cells

Create a rectangular cell selection by clicking and dragging, or by pressing Shift and clicking the cells. You can press Ctrl and click to toggle cells in the selection or to create a selection of individual cells.

You can add or remove links or clear change issues for multiple links at a time when you select multiple cells.

Export the Traceability Matrix

You can export the traceability matrix as an HTML report or as a MATLAB variable that contains the table data.

Generate the HTML report by clicking Export > Generate HTML Report. Name and save the report. The report automatically opens.

The HTML report is not interactive. Create the view that you want to export by focusing the display, collapsing or expanding hierarchies, or applying filters and highlighting. The HTML report lists the file path to the artifacts in the matrix, as well as the focused display, applied filters, and highlighting.

Create a MATLAB variable that contains the table data by clicking Export > Create MATLAB Variable. The variable slrtmxData is created in the base MATLAB workspace. If you have an existing variable slrtmxData in your workspace, the variable is overwritten.

The exported MATLAB variable is not interactive, but has the functionality of a MATLAB table. See Tables. Create the view that you want to export by focusing the display or applying filters. The MATLAB table includes items in collapsed hierarchies, but does not include highlighting.

Work Programmatically with a Traceability Matrix

In addition to the Traceability Matrix window, you can also create a traceability matrix by using APIs. Use slreq.getTraceabilityMatrixOptions to create a structure and set the leftArtifacts and topArtifacts fields by providing a cell array containing artifact lists. Then use slreq.generateTraceabilityMatrix with the structure as an input argument to generate the matrix with the specified artifacts. See Programmatically Generate a Traceability Matrix.