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.
Save and load view settings to regenerate a matrix.

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:

In the Traceability Matrix window, click Add.
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.
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.

Example traceability matrix with two artifacts. The links point from the Simulink blocks on the top to the requirements on the left.

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.

Example traceability matrix with five artifacts. The requirement sets are on the left, and the Simulink models and tests are on the top. The links point from the Simulink items to the requirements.

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.

Link information displayed when you click on a link. The information box includes the link source, destination, summary, and type.

For more information on programmatically modifying a traceability matrix view, see slreq.matrix.Configuration and slreq.matrix.Filter.

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.

Cell information displayed when you click the expand icon. The information box includes the left and top item associated with the cell and the existing links.

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.

Context menu that appears when you right click an item in a row or column of the matrix

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.

Artifact list after the user clicks an artifact. The selected artifact is replaced with a Show All link.

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.

Default view of the filter panel, with sections to apply filters to the top artifacts, left artifacts, or the cells. Each section has sub-sections that appear based on the context of the items and artifacts in the matrix.

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.

Artifact list for a matrix with two artifacts with filters applied

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.

Traceability matrix with highlighting applied to unlinked items

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.

Save View Settings

You can save the view settings of your traceability matrix to a file, then load the file regenerate the matrix with the same view settings. To save the view settings, in the View section, click View Settings > Save View Settings. The view settings file contains these settings:

Top artifacts
Left artifacts
Top filters
Left filters
Cell filters
Highlighting
Matrix settings

To load the view settings file and regenerate the matrix, click Add. Then, click Load View and select the view settings file.

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.

Information box that appears when you click on a cell

Create Link dialog box, showing the pre-populated Source and Destination and the Type property

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. To track and clear change issues programmatically, see slreq.getChangeInformation and slreq.clearChangeIssues.

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.

Traceability matrix showing only changed links and their corresponding items

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, a MATLAB variable that contains the table data, or as an Excel^® spreadsheet.

Export to HTML Report

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.

Export to a MATLAB Variable

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.

Export to Excel

To export the traceability matrix to Excel, click Export > Export to Excel.

The Excel spreadsheet is not interactive. Create the view that you want to export by focusing the display, collapsing or expanding hierarchies, or applying filters and highlighting before you export the matrix. The spreadsheet lists the file path to the artifacts in the matrix and shows the settings you applied before the export..

Work Programmatically with a Traceability Matrix

You can also create a traceability matrix programmatically. Use slreq.getTraceabilityMatrixOptions to create a structure and set the leftArtifacts and topArtifacts fields by providing a cell array that contains the artifact lists.

You can programmatically modify existing filters or add new filters by modifying the slreq.matrix.Configuration object in the options structure. Then use the slreq.generateTraceabilityMatrix function with the structure as an input argument to generate the matrix with the specified artifacts. See Programmatically Generate a Traceability Matrix.