Main Content

Check Direct Links for Validity

Validate Requirements Links in a Model

Check Requirements Links with the Model Advisor

To make sure that every requirements link in your Simulink® model has a valid target in a requirements document, run the Model Advisor Requirements consistency checks:

  1. Open the example model:

    openExample("simulink/" + ...
    "NavigateToExternallyStoredRequirementFromAModelExample")
open_system("slvnvdemo_fuelsys_officereq.slx")

  2. Open the Model Advisor to run a consistency check. In the Apps tab, click Requirements Manager. In the Requirements tab, click Check Consistency.

    In the Requirements Consistency Checking category, all the checks are selected. For this tutorial, keep all the checks selected.

    Checks in the Requirements Consistency Checking category, with all checks selected

    These checks identify the following problems with your model requirements.

    Consistency CheckProblem Identified
    Identify requirement links with missing documentsThe Model Advisor cannot find the requirements document. This might indicate a problem with the path to the requirements document.
    Identify requirement links that specify invalid locations within documents

    The Model Advisor cannot find the designated location for the requirement. This check is implemented for:

    • Microsoft® Word documents

    • Microsoft Excel® documents

    • IBM® DOORS® documents

    • Simulink objects

    Identify selection-based links having description fields that do not match their requirements document text

    The Description field for the link does not match the requirements document text. When you create selection-based links, the Requirements Management Interface (RMI) saves the selected text in the link Description field. This check is implemented for:

    • Microsoft Word documents

    • Microsoft Excel documents

    • IBM DOORS documents

    • Simulink objects

    Identify requirement links with path type inconsistent with preferences

    The path to the requirements document does not match the Document file reference field in the Requirements Settings dialog box Selection Linking tab. This might indicate a problem with the path to the requirements document.

    On Linux® systems, this check is named Identify requirement links with absolute path type. The check reports a warning for each requirements links that uses an absolute path.

    Note

    For information about how Requirements Toolbox™ resolves the path to the requirements document, see Document Path Storage.

    The Model Advisor checks to see if any applications that have link targets are running:

    • If your model has links to Microsoft Word or Microsoft Excel documents, the consistency check requires that you close all instances of those applications. If you have one of these applications open, it displays a warning and does not continue the checks. The consistency checks must verify up-to-date stored copies of the requirements documents.

    • If your model has links to DOORS requirements, you must be logged in to the DOORS software. Your DOORS database must include the module that contains the target requirements.

  3. For this tutorial, make sure that you close both Microsoft Word and Microsoft Excel.

  4. Click Run Selected Checks.

    After the check is complete:

    • The green circles with the check mark indicate that two checks passed.

    • The yellow triangles with the exclamation point indicate that two checks generated warnings.

    Results of the requirements consistency check

    The right-hand pane shows that two checks passed and two checks had warnings. The Report box includes a link to the HTML report.

Keep the Model Advisor open. The next section describes how to interpret and fix the inconsistent links.

Note

To step through an example that uses the Model Advisor to check requirements links in an IBM DOORS database, run the Managing Requirements for Fault-Tolerant Fuel Control System (IBM DOORS) example in the MATLAB® command prompt.

Fix Invalid Requirements Links Detected by the Model Advisor

In Check Requirements Links with the Model Advisor, three requirements consistency checks generate warnings in the slvnvdemo_fuelsys_officereq model.

Resolve Warning: Identify requirement links that specify invalid locations within documents.  To fix the warning about attempting to link to an invalid location in a requirements document:

  1. In the Model Advisor, select Identify requirement links that specify invalid locations within documents to display the description of the warning.

    Warning with a list of linked model blocks and requirements that have invalid locations

    This check identifies a link that specifies a location that does not exist in the Microsoft Word requirements document, slvnvdemo_FuelSys_DesignDescription.docx. The link originates in the Terminator1 block. In this example, the target location in the requirements document was deleted after the requirement was created.

  2. Get more information about this link:

    1. To navigate to the Terminator1 block, under Block, click the hyperlink.

    2. To open the Outgoing Links Editor for this link, under Requirements, click the hyperlink.

  3. To fix the problem from the Outgoing Links dialog, do one of the following:

    • In the Location field, specify a valid location in the requirements document.

    • Delete the requirements link by selecting the link and clicking Delete.

  4. In the Model Advisor, select the Requirements Consistency Checking category of checks.

  5. Click Run Selected Checks again, and verify that the warning no longer occurs.

Resolve Warning: Identify selection-based links having description fields that do not match their requirements document text.  To fix the warnings about the Description field not matching the requirements document text:

  1. In the Model Advisor, click Identify selection-based links having description fields that do not match their requirements document text to display the description of the warning.

    Warning with list of links with requirement descriptions that do not match requirements document descriptions

    The first message indicated that the model contains a link to a bookmark named Simulink_requirement_item_7 in the requirements document that does not exist.

    In addition, this check identified the following mismatching text between the requirements blocks and the requirements document:

    • The Description field in the Test inputs Signal Builder block link is Normal mode of operation. The requirement text is The simulation is run with a throttle input that ramps from 10 to 20 degrees over a period of two seconds, then back to 10 degrees over the next two seconds. This cycle repeats continuously while the engine is held at a constant speed.

    • The Description field in the MAP Estimate block link is Manifold pressure failure. The requirement text in slvnvdemo_FuelSys_DesignDescription.docx is Manifold pressure failure mode.

  2. Get more information about this link:

    1. To navigate to a block, under Block, click the hyperlink.

    2. To open the Outgoing Links Editor for this link, under Current Description, click the hyperlink.

  3. Fix this problem in one of two ways:

    • In the Model Advisor, click Update. This action automatically updates the Description field for that link so that it matches the requirement.

    • In the Link Editor, manually edit the link from the block so that the Description field matches the selected requirements text.

  4. In the Model Advisor, select the Requirements Consistency Checking category of checks.

  5. Click Run Selected Checks again, and verify that the warning no longer occurs.

Validate Requirements Links in a Requirements Document

Check Links in a Requirements Document

To check the links in a requirements document:

  1. At the MATLAB command prompt, enter:

    rmi('checkdoc',docName)

    docName is a character vector that represents one of the following:

    • Module ID for a DOORS requirements document

    • Full path name for a Microsoft Word requirements document

    • Full path name for a Microsoft Excel requirements document

    The rmi function creates and displays an HTML report that lists all requirements links in the document.

    The report highlights invalid links in red. For each invalid link, the report includes brief details about the problem and a hyperlink to the invalid link in the requirements document. The report groups together links that have the same problem.

  2. Double-click the hyperlink under Document content to open the requirements document at the invalid link.

    The navigation controls for the invalid link has a different appearance than the navigation controls for the valid links.

  3. When there are invalid links in your requirements document, you have the following options:

    If you want to...Do the following...
    Fix the invalid linksFollow the instructions in Fix Invalid Links in a Requirements Document.
    Keep the changes to the navigation controls without fixing the invalid linksSave the requirements document.
    Ignore the invalid linksClose the requirements document without saving it.

When Multiple Objects Have Links to the Same Requirement

When you link multiple objects to the same requirement, only one navigation object is inserted into the requirements document. When you double-click that navigation object, all of the linked model objects are highlighted.

If you check the requirements document using the 'checkdoc' option of the rmi function and the check detects a navigation object that points to multiple objects, the check stops and displays the following dialog box.

Dialog box indicating that a navigation object points to multiple objects in Simulink

You have two options:

  • If you click Yes, or you close this dialog box, Requirements Toolbox creates additional navigation objects, one for each model object that links to that requirement. The document check continues, but the RMI does not recheck that navigation; the report only shows one link for that requirement. To rerun the check so that all requirements are checked, at the top of the report, click Refresh.

  • If you click No, the document check continues, and the report identifies that navigation object as a broken link.

Fix Invalid Links in a Requirements Document

Using the report that the rmi function creates, you may be able to fix the invalid links in your requirements document.

In the following example, rmi cannot locate the model specified in two links.

Documents with links to an unresolved model

To fix invalid links:

  1. In the report, under Document content, click the hyperlink associated with the invalid requirement link.

    The requirements document opens with the requirement text highlighted.

  2. In the requirements document, depending on the document format, take these steps:

    • In DOORS:

      1. Select the navigation control for an invalid link.

      2. Select MATLAB > Select item.

    • In Microsoft Word, double-click the navigation control.

    A dialog box opens that allows you to fix, reset, or ignore all the invalid links with a given problem.

  3. Click one of the following options.

    To...Click...

    Navigate to and select a new target model or new target objects for these broken links.

    		Fix all

    Reset the navigation controls for these invalid links to their original state, the state before you checked the requirements document.

    		Reset all

    Make no changes to the requirements document. Any modifications rmi made to the navigation controls remain in the requirements document.

    		Cancel

  4. Save the requirements document to preserve the changes made by the rmi function.

Validation of Requirements Links

Requirements links in a model can become outdated when requirements change over time. Similarly, links in requirements documents may become invalid when your Simulink model changes, for example, when the model, or objects in the model, are renamed, moved, or deleted. The Requirements Toolbox software provides tools that allow you to detect and resolve these problems in the model or in the requirements document.

When to Check Links in a Requirements Document

When you enable Modify destination for bidirectional linking and create a link between a requirement and a Simulink model object, Requirements Toolbox inserts a navigation control into your requirements document. These links may become invalid if your model changes.

To check these links, the 'checkDoc' option of the rmi function reviews a requirements document to verify that all the navigation controls represent valid links to model objects. The checkDoc command can check the following types of requirements documents:

  • Microsoft Word

  • Microsoft Excel

  • IBM DOORS

The rmi function only checks requirements documents that contain navigation controls; to check links in your Simulink model, see Validate Requirements Links in a Model.

Note

For more information about inserting navigation controls in requirements documents, see:

How the rmi Function Checks a Requirements Document

rmi performs the following actions:

  • Locates all links to Simulink objects in the specified requirements document.

  • Checks each link to verify that the target object is present in a Simulink model. If the target object is present, rmi checks that the link label matches the target object.

  • Modifies the navigation controls in the requirements document to identify any detected problems. This allows you to see invalid links at a glance:

    • Valid link:

    • Invalid link:

Related Topics