Create and Store Links

You can use links and link sets to trace requirements to the design and test items that implement and verify them. Each link and link set has a corresponding API object. You can use the Requirements Editor, Requirements Perspective, a traceability matrix, Outgoing Links Editor, or the MATLAB^® command line to create links between requirements, MATLAB code, Simulink^® blocks, Simulink Test™ test cases, and other items. You can also view and edit the links.

Link Objects, Sources, and Destinations

Each link has a corresponding slreq.Link object. You can provide additional traceability information by using link properties, custom attributes, and stereotypes. For more information, see:

Links point from source items to destination items, which are contained in source artifacts and destination artifacts, respectively. For example, consider a link that points from a Simulink block to a requirement. The Simulink model is the source artifact and the block is the source item. The requirement set is the destination artifact and it contains the requirement, which is the destination item.

A linked item has an outgoing link if it is the source of a link. Conversely, an item has an incoming link if it is the destination of a link. For example, if a link points from a Simulink block to a requirement, the Simulink block has an outgoing link and the requirement has an incoming link.

Link Storage

Link sets contain links. Each link set you load has a corresponding slreq.LinkSet object. When you create a link, Requirements Toolbox™ creates a link set and saves it as an SLMX file in the same folder as the source artifact. The link set name is the source artifact base name and the source artifact extension, separated by a tilde. For example, Requirements Toolbox stores outgoing links from a MATLAB function called myFunction.m in a link set file called myFunction~m.slmx.

Note

Link sets that contain links from Simulink models combine the model base name and ~mdl to prevent link resolution issues if the model file extension changes between .mdl and .slx. For example, Requirements Toolbox stores outgoing links from crs_plant.slx in a link set file called crs_plant~mdl.slmx.

Save Links

When you create links from artifacts such as Simulink models or Simulink Test files, you can save the changes to the link set by saving the artifact.

When you create or edit links to lines of MATLAB code or plain-text external code, use one of these approaches to save the link set:

In the MATLAB Editor, right-click and select Requirements > Save Links.
In the Requirements Editor, click Show Links. Select the link set, and click Save.
At the MATLAB command line, use save.

Store Links from Models Externally or Internally

When you create a link from a Simulink model to a requirement, you can store the links internally to the model or as an external SLMX file. When you store links externally, creating or modifying requirements links does not modify your model. By default, the externally stored requirements links are stored in a file whose name is based on the model file. When links are stored internally, the time stamp and version of the number of the model changes every time you modify your requirements links.

For information on how to specify the default link storage, see Specify Requirements Link Storage for Models. This setting applies immediately to models that do not already contain requirements links. If you open a model that already has requirements links, Requirements Toolbox uses the storage mechanism you used previously with that model, regardless of what your default storage setting is. To change the storage mechanism for existing links, see Move Internally Stored Requirements Links to External Storage and Move Externally Stored Requirements Links to the Model File.

Guidelines for Storing Links from Models Externally

When sharing models, use the default name and location.
By default, external requirements are stored in a file named model_name.slmx in the same folder as the model. If you share the model with others to review the requirements traceability, share both the model and SLMX files. Opening the model loads the links file.
Do not rename the model outside of Simulink.
If you need to re-save the model with a new name or in a different location, in the Simulation tab, click Save As to re-save the model and automatically re-save the corresponding SLMX file using the updated model name or location.
Be aware of unsaved requirements changes.
If you create new requirements links that are stored externally, your model does not indicate that it has unsaved changes, because the model file itself has not changed. You must explicitly save the links. Additionally, when you close the model, Requirements Toolbox prompts you to save the requirements links in the external file.

Linkable Items

You can create links between these requirements items, model entities, test artifacts, and code:

Requirements Toolbox objects:
- slreq.Requirement objects
- slreq.Reference objects
- slreq.Justification objects
Simulink entities:
- Blocks
- Subsystems
Simulink data dictionary entries
Simulink Fault Analyzer™ artifacts:
- Faults (since R2023b)
- Conditionals (since R2023b)
- Safety Analysis Manager cells (since R2023b)
- Safety Analysis Manager rows (since R2024b)
For more information, see Link Artifacts (Simulink Fault Analyzer).
Stateflow^® objects:
- States
- Charts and subcharts
- Transitions
System Composer™ architecture entities:
- Components
- Ports
- Views
System Composer sequence diagram entities:
- Lifelines
- Gates
- Messages
- Fragments
Simulink Test objects:
- Test files
- Test suites
- Test cases
- Iterations
- Assessments
Lines of MATLAB code in:
- MATLAB code files (.m extension). For more information, see Link MATLAB Code to Requirements.
- MATLAB Function blocks. For more information, see Author Blocks Using MATLAB Functions (Simulink).
- MATLAB-based Simulink tests. For more information, see Test Models Using MATLAB-Based Simulink Tests (Simulink Test).
Lines of code in plain-text external code files, such as C and H files. You can also link to HTML files, but not XML or JSON.
Note
To create links to lines of plain-text external code, you must open the code in the MATLAB Editor. For more information, see Link Requirements to MATLAB or Plain Text Code.

You can also link directly to requirements in third-party applications. For more information, see Link Directly to Requirements in Third-Party Applications.

Create Links

You can use the Requirements Editor, Requirements Perspective, a traceability matrix, the MATLAB command line, or the Outgoing Links Editor to create links.

To create a link from a design or test item to a requirement by using the Requirements Editor:

Select one of these items:
- Simulink or Stateflow model element
- Simulink Fault Analyzer artifacts
- System Composer architecture element
- Simulink Test test case
- Code range in the MATLAB Editor
- Simulink data dictionary entry
Tip
To link to MATLAB functions and enable change tracking for the entire body of the function, create the link to the line that contains the function keyword.
In the Requirements Editor, select the requirement.
Click Add Link, then select the menu option that contains the selection that you want to link to.

To create a requirement-to-requirement link:

Select the requirement that you want to link as the source item.
Click Add Link > Select for Linking with Requirement.
Select the requirement that you want to link as the destination item.
Create the link by selecting Add Link > Create a link from.

Tip

You can create links without leaving the Simulink Editor by using the Requirements Perspective. For more information, see View and Link Requirements in Simulink.
You can create links between multiple artifacts in a single window by using a traceability matrix. For more information, see Track Requirement Links with a Traceability Matrix.

Create Links Programmatically

To create links at the MATLAB command line:

Get the object or handle for the link source. For example, suppose that you have a model called MyModel that has a block called MyBlock:
```
open_system("MyModel")
src = get_param("MyModel/MyBlock","Handle");
```
Get the object or handle for the link destination. For example, suppose that you have a requirement that has the summary My requirement:
```
dest = slreq.find(Type="Requirement",Summary="My requirement");
```
Use the slreq.createLink function to create the link.
```
newLink = slreq.createLink(src,dest);
```

To create links to MATLAB code or plain-text external code programmatically, use slreq.TextRange objects. For more information, see Link MATLAB Code to Requirements.

Create Links by Using the Outgoing Links Editor

To create links to requirements in Requirements Toolbox by using the Outgoing Links Editor:

Right-click a linkable item and select Requirements > Open Outgoing Links dialog.
Click New.
Describe the link in the Description field.
Set Document type to Requirements Toolbox.
Click Browse and select the requirement set that contains the requirement to link.
Alternatively, select a requirement in the Requirements Editor, then click Use current.
Specify the requirement to link to by selecting the Document Index tab and double-clicking the requirement.
Alternatively, in the Requirements tab, you can specify the requirement ID in the Location field.
To add keywords to the link, enter a comma-separated list in the Keywords field.
Create the link by clicking Apply or OK.

For information about creating direct links to requirements in third-party applications by using the Outgoing Links Editor, see Link Directly to Requirements in Third-Party Applications.

Link Types

Each link has a type that describes the relationship between the source and destination items. The Type property value of the slreq.Link object describes the link type.

Assigned Link Types

Each link type has an intended use case. For example, the Implement link type indicates a relationship between a requirement and a design item that implements the requirement. When you create a link between two items, Requirements Toolbox sets the link type and designates the items as the source or destination depending on the type of artifact that they belong to. For example, if you create a link between a requirement and a Simulink model element, Requirements Toolbox assumes that the model element implements the requirement, sets the link type to Implement, and designates the model element as the source and the requirement as the destination.

If there is no assumed link type for a link created between two items, then Requirements Toolbox sets the link type to Relate. For example, requirement-to-requirement links default to Relate.

Edit the Link Type

After you create the link, you can edit the link type in the Requirements Editor, the Requirements Perspective, or at the MATLAB command line. In the Requirements Editor, click Show Links. Select a link and, in the right pane, under Properties, select the desired link type from the Type list.

Built-in Link Types

Requirements Toolbox provides six built-in link types.

The forward direction indicates how the source relates to the destination. Similarly, the backward direction indicates how the destination relates to the source.

Type	Description	Source-to-Destination Example	Forward Direction	Backward Direction
`Relate`	General relationship between items for most use cases Bi-directional link	Requirement to requirement	The first requirement is related to the second requirement.	The second requirement is related to the first requirement.
`Implement`	Specifies the source item that implements the requirement Contributes to the implementation status For more information, see Track Requirement Links by Using Implementation Status.	Simulink model element to requirement	The Simulink model element implements the requirement.	The requirement is implemented by the Simulink model element.
`Verify`	Specifies which source item verifies the requirement Contributes to the verification status if the source item is one of the accepted item types For more information, see Review Requirements Verification Status.	Simulink test case to requirement	The Simulink test case verifies the requirement.	The requirement is verified by the Simulink test case.
`Derive`	Specifies which source item derives the destination item	Imported referenced requirement to requirement	The imported referenced requirement derives the requirement.	The requirement is derived from the imported referenced requirement.
`Refine`	Specifies which source item adds detail for the functionality specified by the destination item	Low-level requirement to high-level requirement	The low-level requirement refines the high-level requirement.	The high-level requirement is refined by the low-level requirement.
`Confirm`	Specifies a relationship between a requirement and an external test result source Can contribute to the verification status in certain cases For more information, see Include Results from External Sources in Verification Status.	Requirement to external test result	The requirement is confirmed by the external test result.	The external test result confirms the requirement.

The Implement and Verify link types describe requirement-to-model and requirement-to-test relationships. These links affect the implementation status and verification status. For more information, see Track Requirement Links by Using Implementation Status and Review Requirements Verification Status.

The link type also affects the impact direction in the Traceability Diagram window. For more information, see Visualize Links with Traceability Diagrams.

Custom Link Types

In addition to the built-in types, you can define custom link types. Custom link types must use one of the built-in types as the base behavior. The custom link type inherits some functionality from the built-in type, including how the link type contributes to the implementation and verification statuses. For more information, see Choose a Built-in Type as a Base Behavior.

You can define custom link types by using stereotypes or by using sl_customization files. For more information, see Define Custom Requirement and Link Types and Properties.

View and Edit Links

To view the loaded link sets and the links they contain, in the Requirements Editor, click View Links. You can then select a link and view or edit its properties or custom attributes. For more information, see Set Link Properties, Custom Attributes, or Stereotype Properties.

You can also view the links for a particular requirement in the Requirements Editor when you select a requirement. In the right pane, under Links, the outgoing links icon indicates outgoing links and the incoming links icon indicates incoming links.

To view links in the Simulink Editor by using the Requirements Perspective:

Open the Requirements Perspective in a Simulink model by clicking the Show Perspectives views icon in the lower-right corner of the model canvas and select Requirements.
In the Requirements tab, ensure that Layout > Requirements Browser is selected.
In the Requirements Browser, in the View menu, select Links.

To visualize links, create a traceability matrix or traceability diagram. For more information, see Track Requirement Links with a Traceability Matrix and Visualize Links with Traceability Diagrams.

Delete Links and Link Sets

To delete a link, in the Requirements Editor, click Show Links. Select a link and, in the Links section, click .

To delete a link set:

Locate the SLMX file that contains the link set. By default, link set files are in the same folder as the source artifact.
Close the linked artifacts before deleting a link set, including requirement sets, Simulink Test files, MATLAB code, Simulink data dictionaries, and Simulink, Stateflow or System Composer models.
At the MATLAB command line, clear the loaded requirements and links by entering:
```
slreq.clear
```
Delete the SLMX file.

Note

If you want to delete a link set file associated with a Simulink model, ensure that the links are stored externally. For more information about how to store links externally, see Link Storage.