Define Custom Document Interface for Direct Linking to Requirements

If you want to create a direct link to a requirement in a third-party application that Requirements Toolbox™ does not provide built-in support for, you can define a custom document interface. To define a custom document interface, you create a function that specifies the interface properties and callback functions to use when you create or navigate the direct link. For more information about direct linking, see Link Directly to Requirements in Third-Party Applications.

Note

If you want to use Requirements Toolbox analysis tools such as implementation status, verification status, change tracking, and traceability matrices, you must import your third-party requirements. For more information, see Differences Between Importing and Direct Linking. If Requirements Toolbox does not provide built-in import support for your third party application, you can import the requirements from a ReqIF™ file, or you can define a custom document interface to import those requirements. For more information, see Define Custom Document Interface for Importing Requirements.

Define Custom Document Interface

To define and use a custom document interface for direct linking:

Open the myCustomDocInterface.m file by executing this code at the MATLAB^® command line:
```
open(fullfile(matlabroot,"toolbox","slrequirements", ...
    "slrequirements","linktype_examples","myCustomDocInterface.m"))
```
The docInterface variable represents the document interface object.
```
function docInterface = myCustomDocInterface 
    docInterface = ReqMgr.LinkableType;
```
Save a copy of myCustomDocInterface.m on the MATLAB path. In MATLAB, in the Editor tab, click Save > Save Copy As. Save the file with your desired name in your desired location.

Define these properties for the document interface object:

Name	Description	Value Types	Example Value
`Registration`	Requirement document interface name, specified as a character vector. The value of this property must be the same as the document interface function name. You can use the `mfilename` function to specify the value.	Character vector	`mfilename`
`Label`	Label for the custom document type in the Outgoing Links Editor, specified as a character vector.	Character vector	`'My Custom Document Interface'`
`IsFile`	Indicator for the file-based requirement documents, specified as a `logical` `1` (true) or `0` (false). Set the value to `1` if your requirement document is file-based, or `0` if your requirement document is not file-based.	`Logical` `1` (true) or `0` (false)	`1`
`Extensions`	Allowed file type extensions for file-based requirement documents, specified as a cell array of character vectors. Leave this property empty for requirement documents that are not file-based.	Cell array of character vectors	`{'.ppt','.pptx'}`
`LocDelimeters`	Characters that specify the supported types of location identifiers in the requirement document, specified as a character array that is a combination of one or more of these characters: `?`: Used to search for text in the document `@`: Used as a named item such as a requirement ID `#`: Page number or item number `>`: Item number or line number `$`: Cell address in spreadsheet This property is optional.	Character array containing one or more of these characters: `?`, `@`, `#`, `>`, `$`	`'?@#'`
`SelectionLinkLabel`	Context menu label for creating direct links to selection. This property is required if you define a callback for `SelectionLinkFcn`, otherwise it is optional.	Character vector	`'Link to Selection in My Custom Document'`

Determine which callback functions your document interface object needs.

Callback	Summary	Required or Optional?	Function Syntax and Description
`NavigateFcn`	Function that navigates from the linked item in MATLAB or Simulink^® to requirement in third-party application	Required	`NavigateFcn(document,id)` opens the requirement document specified by `document` to the requirement specified by `id` in the third-party application.
`ContentsFcn`	Function that gets the table of contents of the requirement document or requirements collection in the third-party application. The function displays the table of contents in the Document Index tab of the Outgoing Links Editor.	Optional	`[labels,depths,ids] = ContentsFcn(document)` returns requirements information as cell arrays for the requirement document specified by `document`. `labels` contains one line requirement summaries, `ids` contains requirements identifiers, and `depths` contains the level of the requirement in the hierarchy.
`BrowseFcn`	Function that executes when you click the Browse button in the Outgoing Links Editor. This function is not required for file-based requirements domains.	Optional for non-file-based requirement documents, but if you do not define this function you have to manually enter the name of the document in the Outgoing Links Editor. Not needed if the `IsFile` property is set to `1`.	`BrowseFcn` opens the browser for requirement documents.
`SelectionLinkFcn`	Function that enables creating direct link to selection from context menu	Optional. If you define this function, you must define the `SelectionLinkLabel` property.	`linkTargetInfo = SelectionLinkFcn(callerObject,make2way)` returns a structure with information about the current selected requirement in the external requirement document. The input `callerObject` is the MATLAB or Simulink object for which the `SelectionLinkFcn` function was called. The function gets the value of `rmipref("BiDirectionalLinking")` and uses it as the `make2way` argument. If `make2way` is `true`, the call instructs the callback function to insert a backlink to navigate from the current selected requirement in the external requirement document to the object specified by `callerObject` in MATLAB or Simulink. For compatibility with interfaces for linking to requirements in third-party application that were developed prior to R2017b, the fields for the `linkTargetInfo` structure must be: `doc` `id` `linked` `description` `keywords` `reqsys` Use the `rmi("createempty")` function to create the structure with the required fields, then fill in the values according to current selection in your custom document. Requirements Toolbox stores the value of the `doc` and `id` fields as the link destination and passes the values to the `NavigateFcn` callback function when you use the link to navigate from MATLAB or Simulink to the requirement in the external requirement document.
`DetailsFcn`	Function that gets requirements content to include in requirements reports for specified requirement	Optional. Not required for link creation and navigation.	`[depths,info] = DetailsFcn(document,location,level)` returns related requirement contents for the location `location` from the requirement document `document`. The function gets the value of `rmipref("ReportDocDetails")` and uses it as the `level` argument to allow control for the amount of requirements content returned. For example, you may choose for this method to return only the label if `level` is 0, return the first lines when `level` is 1, and return the entire content when `level` is 2. The `info` output returns information about the requirement as a cell array. The `depths` output returns information about how to display the requirement information in the hierarchy.
`CreateURLFcn`	Function that gets hyperlink to navigate to linked requirement in requirements reports	Optional. Not required for link creation and navigation.	`url = CreateURLFcn(document,documentURL,id)` returns the URL for the requirement specified by the identifier `id` in the external requirement document specified by `document` or the document URL `documentURL`.
`UrlLabelFcn`	Function that gets the hyperlink text for the requirement navigation URL in requirements reports	Required if you define a callback for `CreateURLFcn`	`label = UrlLabelFcn(document,id)` returns a label for the requirement specified by the identifier `id` in the external requirement document specified by `document`.
`IsValidDocFcn`	Function that checks that the requirement document exists. Use this function for consistency checking.	Optional	`tf = IsValidDocFcn(document,~)` returns `true` if the external requirement document specified by `document` exists and is valid for the document interface.
`IsValidIdFcn`	Function that checks that the ID of the linked requirement exists in the requirement document. Use this function for consistency checking.	Optional	`tf = IsValidIdFcn(document,id)` returns `true` if the requirement specified by the identifier `id` exists in the external requirement document specified by `document`.
`IsValidDescFcn`	Function that checks that the stored `Description` property of the direct link matches the current content in the requirement document. Use this function for consistency checking.	Optional	`[tf,newDesc] = IsValidDescFcn(document,id,currDesc)` checks if the current value of the `Description` property of the linked requirement, `currDesc`, matches the text found at the location of the external requirement specified by `id`, in the external requirement document specified by `document`.
`BacklinkCheckFcn`	Function that checks if backlink exists in external requirement document. For more information about backlinks, see Manage Navigation Backlinks in External Requirements Documents.	Optional	`[linkExists,newLinkURL] = BacklinkCheckFcn(mwArtifactName,mwItemId,extDoc,extReq)` checks whether the external requirement `extReq` in the external requirement document `extDoc` has a backlink to the linkable item in MATLAB or Simulink specified by `mwItemId` in the artifact `mwArtifactName`. If the backlink exists, `linkExists` returns `true` and `newLinkURL` returns empty. If the backlink does not exist, `linkExists` returns `false` and `newLinkURL` contains the URL to insert as a backlink.
`BacklinkInsertFcn`	Function that inserts backlinks in external requirement document. For more information about backlinks, see Manage Navigation Backlinks in External Requirements Documents.	Required if you define a callback function for `BacklinkCheckFcn`	`[navCmd,dispText] = BacklinkInsertFcn(extDoc,extReq,mwSourceArtifact,mwItemId,mwDomain)` inserts a backlink from the external requirement specified by `extReq` in the external requirement document `extDoc` to the linkable item in MATLAB or Simulink specified by `mwItemId` in the artifact specified by `mwSourceArtifact` with the artifact document interface `mwDomain`. The function returns the navigation command that the backlink uses, `navCmd`, and the displayed hyperlink text for the backlink, `dispText`.
`BacklinksCleanupFcn`	Function that checks for stale backlinks in external requirement document. For more information about backlinks, see Manage Navigation Backlinks in External Requirements Documents.	Optional, but if this function is not defined, the Update Backlinks context menu option in the Requirements Editor cannot check for and delete stale backlinks	`[countRemoved,countChecked] = BacklinksCleanupFcn(extDoc,mwSourceArtifact,mwLinksDataMap)` checks the backlinks in the external requirement document `extDoc` that point to linkable items in the MATLAB or Simulink artifact `mwSourceArtifact` and deletes backlinks that do not have a corresponding forward link in the Requirements Toolbox link map specified by `mwLinksDataMap`. `[countRemoved,countChecked] = BacklinksCleanupFcn(extDoc,mwSourceArtifact,mwLinksDataMap,saveBeforeCleanup)` saves the requirement document before deleting the backlinks.
`BacklinkDeleteFcn`	Function that deletes backlinks in external requirement document. For more information about backlinks, see Manage Navigation Backlinks in External Requirements Documents.	Optional	`success = BacklinkDeleteFcn(extDoc,extReq,mwSourceArtifact,mwItemId)` deletes the backlink from the external requirement specified by `extReq` in the external requirement document `extDoc` that points to the linkable item in MATLAB or Simulink specified by `mwItemId` in the artifact specified by `mwSourceArtifact`.
`GetResultFcn`	Function that gets test results for the verification status when you link to external test cases or test results. Use this function to verify requirements that have outgoing links with the `Confirm` link type.	Optional	`result = GetResultFcn(link)` returns the verification status result for the test case or test result that is linked to by `link`. The `result` output is a structure that contains these fields: `status` (required): Verification status (`Passed`, `Failed`, `Unexecuted`) `timestamp` (optional): Date and time of most recent verification status. Value must be a `datetime` object.

Author the callback functions that your document interface needs as local functions in the main function. Comment out or delete callback functions that you do not need.
The myCustomDocInterface.m assigns the callback function handles to the corresponding properties of the custom document interface object. If there are callback functions that you did not use or deleted, comment out or delete the lines that assign those callback function handles to the custom document interface object properties.
Register the custom document interface by using the rmi function. Specify the custom document interface name as the second argument.
```
rmi register myCustomDocInterface
```

You can unregister the custom document interface by using the rmi function.

rmi unregister myCustomDocInterface

Tip

For examples of document interface definitions, you can view the built-in document interface definitions in the fullfile(matlabroot,"toolbox","slrequirements","slrequirements","linktype_examples") directory:

linktype_rmi_doors.m
linktype_rmi_excel.m
linktype_rmi_html.m
linktype_rmi_text.m

Link to Requirements in an ABC File

This example uses:

Open Live Script

This example shows how to define a custom document interface that enables direct linking to requirements in a text file with the extension .abc.

Define and Register the Custom Document Interface

The abcInterface function defines a custom document interface that enables linking to text files that have the extension .abc.

type abcInterface

function docInterface = abcInterface

% Define custom document interface
docInterface = ReqMgr.LinkableType;

% Define custom document interface properties
docInterface.Registration = mfilename;
docInterface.Label = 'ABC  file (for demonstration)';
docInterface.IsFile = 1;
docInterface.Extensions = {'.abc'};
docInterface.LocDelimiters = '>@';
% docInterface.Version = '';             % not required

% Assign custom document interface callback functions
docInterface.NavigateFcn = @NavigateFcn;
docInterface.ContentsFcn = @ContentsFcn;
end

%% Define callback functions
function NavigateFcn(filename,locationStr)
if ~isempty(locationStr)
    findId=0;
    switch(locationStr(1))
        case '>'
            lineNum = str2num(locationStr(2:end));
            openFileToLine(filename, lineNum);
        case '@'
            openFileToItem(filename,locationStr(2:end));
        otherwise
            openFileToLine(filename, 1);
    end
end
end

function openFileToLine(fileName, lineNum)
if lineNum > 0
    if matlab.desktop.editor.isEditorAvailable
        matlab.desktop.editor.openAndGoToLine(fileName, lineNum);
    end
else
    edit(fileName);
end
end

function openFileToItem(fileName, itemName)
reqStr = ['Requirement:: "' itemName '"'];
lineNum = 0;
fid = fopen(fileName);
i   = 1;
while lineNum == 0
    lineStr = fgetl(fid);
    if ~isempty(strfind(lineStr, reqStr))
        lineNum = i;
    end;
    if ~ischar(lineStr), break, end;
    i = i + 1;
end;
fclose(fid);
openFileToLine(fileName, lineNum);
end

function [labels, depths, locations] = ContentsFcn(filePath)
% Read the entire file into a variable
fid = fopen(filePath,'r');
contents = char(fread(fid)');
fclose(fid);

% Find all ok, reviewed by ngabriel 13a  the requirement items
fList1 = regexpi(contents,'\nRequirement:: "(.*?)"','tokens');

% Combine and sort the list
items = [fList1{:}]';
items = sort(items);
items = strcat('@',items);

if (~iscell(items) && length(items)>0)
    locations = {items};
    labels = {items};
else
    locations = [items];
    labels = [items];
end

depths = [];
end
%  Copyright 2024 The MathWorks, Inc.

rmi register abcInterface

Link Requirements Directly to Simulink Blocks

The AutopilotRequirements.abc file contains requirements for the autopilot system of the aero_dap3dof Simulink® model.

type AutopilotRequirements.abc

Requirement:: "Altitude Climb Control"

Altitude climb control is entered whenever:
|Actual Altitude- Desired Altitude | > 1500 

Units:
Actual Altitude - feet
Desired Altitude - feet

Description:

When the autopilot is in altitude climb 
control mode, the controller maintains a 
constant user-selectable target climb rate.  

The user-selectable climb rate is always a 
positive number if the current altitude is 
above the target altitude.  The actual target 
climb rate is the negative of the user 
setting. 

End of "Altitude Climb Control">


Requirement:: "Altitude Hold"

Altitude hold mode is entered whenever:
|Actual Altitude- Desired Altitude | < 
  30*Sample Period*(Pilot Climb Rate / 60) 

Units:
Actual Altitude - feet
Desired Altitude - feet
Sample Period - seconds
Pilot Climb Rate - feet/minute

Description:

The transition from climb mode to altitude 
hold is based on a threshold that is 
proportional to the Pilot Climb Rate.  

At higher climb rates the transition occurs 
sooner to prevent excessive overshoot. 

End of "Altitude Hold"


Requirement:: "Autopilot Disable"

Altitude hold control and altitude climb 
control are disabled when autopilot enable 
is false.

Description:

Both control modes of the autopilot 
can be disabled with a pilot setting.

ENd of "Autopilot Disable"


Requirement:: "Glide Slope Armed"

Glide Slope Control is armed when Glide 
Slope Enable and Glide Slope Signal 
are both true. 

Units:
Glide Slope Enable - Logical
Glide Slope Signal - Logical

Description:

ILS Glide Slope Control of altitude is only 
enabled when the pilot has enabled this mode 
and the Glide Slope Signal is true.  This indicates 
the Glide Slope broadcast signal has been 
validated by the on board receiver. 

End of "Glide Slope Armed"


Requirement:: "Glide Slope Coupled"

Glide Slope control becomes coupled when the control 
is armed and (Glide Slope Angle Error > 0) and 
 Distance < 10000 

Units:
Glide Slope Angle Error - Logical
Distance - feet

Description:

When the autopilot is in altitude climb control 
mode the controller maintains a constant user 
selectable target climb rate.  

The user-selectable climb rate is always a positive 
number if the current altitude is above the target 
altitude the actual target climb rate is the 
negative of the user setting. 

End of "Glide Slope Coupled"

Open the aero_dap3dof model.

open_system("aero_dap3dof.slx")

Warning: Simulink 3D Animation Viewer has been removed so vrfigure does not open the virtual world. Use sim3d classes to create and view a 3D environment instead. See <a href="matlab:helpview('sl3d','sim3d_transition')">Transition Virtual Reality World to Unreal Engine 3D Environment</a>.

Warning: Simulink 3D Animation Viewer has been removed so VR Sink (aero_dap3dof/Simulink 3D Animation/VR Sink) does not open the virtual world. See <a href="matlab:helpview('sl3d','sim3d_transition')">Transition Virtual Reality World to Unreal Engine 3D Environment</a>.

Close the Apollo Lunar Module Descent Animation window. In the aero_dap3dof model, right-click the Reaction Jet Control subsystem and select Requirements > Open Outgoing Links dialog. The Outgoing Links Editor opens. Add a new requirement link by clicking New.

Set Document type to ABC file (for demonstration).

Next to Document, click Browse and select the AutopilotRequirements.abc file. Select the Document Index tab and double-click @Altitude Hold. Create the link by clicking OK. Verify that the link works as expected by right-clicking the Reaction Jet Control subsystem and selecting Requirements > 1. “Altitude Hold”.

Unregister the custom document interface.

rmi unregister abcInterface

References

[1] USGS Astrogeology Science Center. (2009). Moon Clementine UVVIS Global Mosaic 118m. Retrieved from https://astrogeology.usgs.gov/search/map/moon_clementine_uvvis_global_mosaic_118m

Define Custom Document Interface for Direct Linking to Requirements

Define Custom Document Interface

Link to Requirements in an ABC File

See Also

Topics