Main Content

Requirement Links and Link Types

Requirements Traceability Links

When you want to navigate from a Simulink® model or from a region of MATLAB® code to a location inside a requirements document, you can add requirements traceability links to the model or code.

Requirements traceability links have the following attributes:

  • A description of up to 255 characters.

  • A requirements document path name, such as a Microsoft® Word file or a module in an IBM® DOORS® database. (The RMI supports several built-in document formats. You can also register custom types of requirements documents. See Supported Requirements Document Types.)

  • A designated location inside the requirements document, such as:

    • Bookmark

    • Anchor

    • ID

    • Page number

    • Line number

    • Cell range

    • Link target

    • Keywords that you define

Supported Model Objects for Requirements Linking

You can associate requirements links between the following types of Simulink model objects:

  • Simulink block diagrams and subsystems

  • Simulink blocks and annotations

  • Simulink data dictionary entries

  • Signal Builder signal groups

  • Stateflow® charts, subcharts, states, transitions, and boxes

  • Stateflow functions

  • Lines of MATLAB code

  • Simulink Test™ Manager test cases

Links and Link Types

Requirements links are the data structures, managed by Simulink, that identify a specific location within a document. You get and set the links on a block using the rmi command.

Links and link types work together to perform navigation and manage requirements. The doc and id fields of a link uniquely identify the linked item in the external document. The RMI passes both of these values to the navigation command when you navigate a link from the model.

Link Type Properties

Link type properties define how links are created, identified, navigated to, and stored within the requirement management tool. The following table describes each of these properties.

PropertyDescription
Registration

The name of the function that creates the link type. The RMI stores this name in the Simulink model.

Label

A string to identify this link type. In the Outgoing Links Editor, this string appears on the Document type drop-down list for a Simulink or Stateflow object.

IsFile

A Boolean property that indicates if the linked documents are files within the computer file system. If a document is a file:

  • The software uses the standard method for resolving the path.

  • In the Outgoing Links Editor, when you click Browse, the file selection dialog box opens.

Extensions

An array of file extensions. Use these file extensions as filter options in the Outgoing Links Editor when you click Browse. The file extensions infer the link type based on the document name. If you registered more than one link type for the same file extension, the link type that you registered takes first priority.

LocDelimiters

A string containing the list of supported navigation delimiters. The first character in the ID of a requirement specifies the type of identifier. For example, an identifier can refer to a specific page number (#4), a named bookmark (@my_tag), or some searchable text (?search_text). The valid location delimiters determine the possible entries in the Outgoing Links Editor Location drop-down list.

NavigateFcn

The MATLAB callback invoked when you click a link. The function has two input arguments: the document field and the ID field of the link: 

feval(LinkType.NavigateFcn, Link.document, Link.id)
ContentsFcn

The MATLAB callback invoked when you click the Document Index tab in the Outgoing Links Editor. This function has a single input argument that contains the full path of the resolved function or, if the link type is not a file, the Document field contents.

The function returns three outputs:

  • Labels

  • Depths

  • Locations

BrowseFcn

The MATLAB callback invoked when you click Browse in the Outgoing Links Editor. You do not need this function when the link type is a file. The function takes no input arguments and returns a single output argument that identifies the selected document.

CreateURLFcn

The MATLAB callback that constructs a path name to the requirement. This function uses the document path or URL to create a specific requirement URL. The requirement URL is based on a location identifier specified in the third input argument. The input arguments are:

  • Full path name to the requirements document

  • Info about creating a URL to the document (if applicable)

  • Location of the requirement in the document

This function returns a single output argument specified as a character vector. Use this argument when navigating to the requirement from the generated report.

IsValidDocFcn

The MATLAB callback invoked when you run a requirements consistency check. The function takes one input argument—the fully qualified name for the requirements document. It returns true if the document can be located; it returns false if the document cannot be found or the document name is invalid.

IsValidIdFcn

The MATLAB callback invoked when you run a requirements consistency check. This function takes two input arguments:

  • Fully qualified name for the requirements document

  • Location of the requirement in the document

IsValidIdFcn returns true if it finds the requirement and false if it cannot find that requirement in the specified document.

IsValidDescFcn

The MATLAB callback invoked when you run a requirements consistency check. This function has three input arguments:

  • Full path to the requirements document

  • Location of the requirement in the document

  • Requirement description label as stored in Simulink

IsValidDescFcn returns two outputs:

  • True if the description matches the requirement, false otherwise.

  • The requirement label in the document, if not matched in Simulink.

DetailsFcn

The MATLAB callback invoked when you generate the requirements report with the Include details from linked documents option. This function returns detailed content associated with the requirement and has three input arguments:

  • Full path to the requirements document

  • Location of the requirement in the document

  • Level of details to include in report (Unused)

The DetailsFcn returns two outputs:

  • Numeric array that describes the hierarchical relationship among the fragments in the cell array

  • Cell array of formatted fragments (paragraphs, tables, et al.) from the requirement

SelectionLinkFcn

The MATLAB callback invoked when you use the selection-based linking menu option for this document type. This function has two input arguments:

  • Handle to the model object that will have the requirement link

  • True if a navigation object is inserted into the requirements document, or false if no navigation object is inserted

SelectionLinkFcn returns the requirements link structure for the selected requirement.

GetResultFcn

The MATLAB callback invoked when you link external test cases with the requirements to the custom link type file. It is used in the custom link type file and fetches external results to integrate with verification statuses.

This function has one input argument:

  • link: This is a slreq.Link object. The function identifies the source and destination of the link.

The function returns a single output argument, result which is specified as a struct with the following fields:

  • status (Required): This is a value from slreq.verification.Status (Pass, Fail, Stale, or Unknown)

  • timestamp (Optional): Skip this field or mark NaT to avoid stale result detection.

  • info (Optional): This should be a character,vector or string. The value of info is printed as a diagnostic on the tooltip of the status.

  • error (Optional): This should be a character,vector or string. The value of error is printed as a diagnostic on the tooltip of the status. If provided, it takes precedence over the info field.

  • In order to avoid stale results, make sure that the timestamp of result file is latest than the timestamp of link creation. If the timestamp is not mentioned or set to NaT in the result returned by GetResult function, then the staleness detection gets skipped.

Outgoing Links Editor

Manage Requirements Traceability Links Using the Outgoing Links Editor

You can create, edit, and delete requirements traceability links using the Outgoing Links Editor. To open the Outgoing Links Editor:

  • in the Simulink Editor, right-click on a model object that has a requirements traceability link. From the context menu, select Requirements > Open Outgoing Links dialog.

  • in the MATLAB Editor, right-click inside a region of code that has a requirements traceability link. From the context menu, select Requirements > Open Outgoing Links dialog.

The Outgoing Links Editor opens, as shown below.

In the Outgoing Links Editor, you can:

  • Create requirements links from one or more Simulink model objects or MATLAB code lines.

  • Customize information about requirements links, including specifying user keywords to filter requirements highlighting and reporting.

  • Delete existing requirements links.

  • Modify the stored order of requirements to control the order of labels in context menus for linked objects.

Requirements Tab

On the Requirements tab, you specify detailed information about the link, including:

  • Description of the requirement (up to 255 words). If you create a link using the document index, unless a description already exists, the name of the index location becomes the description for the link.

  • Path name to the requirements document.

  • Document type (Microsoft Word, Microsoft Excel®, IBM DOORS, MuPAD®, HTML, text file, etc.).

  • Location of the requirement (search text, named location, or page or item number).

  • User-specified keyword or keyword.

Document Index Tab

The Document Index tab is available only if you have specified a file in the Document field on the Requirements tab that supports indexing. On the Document Index tab, the RMI generates a list of locations in the specified requirements document for the following types of requirements documents:

  • Microsoft Word

  • IBM DOORS

  • HTML files

  • MuPAD

Note

The RMI cannot create document indexes for PDF files.

From the document index, select the desired requirement from the document index and click OK. Unless a description already exists, the name of the index location becomes the description for the link.

If you make any changes to your requirements document, to load any newly created locations into the document index, you must click Refresh. During a MATLAB session, the RMI does not reload the document index unless you click the Refresh button.