Define Custom Document Interface for Importing Requirements

Since R2023a

You can define custom document interfaces to import requirements from third-party applications that Requirements Toolbox™ does not provide built-in support for. To define a custom document interface, create a function that specifies the interface properties and callback functions to use during the import process. You can also create a custom version of a built-in Requirements Toolbox document interface for a supported products, such as Microsoft^® Word. Your custom version of a built-in document interface can have different properties or callback functions than the built-in type.

Alternatively, you can import requirements from third-party applications that Requirements Toolbox does not support by importing ReqIF™ files. For more information, see Import Requirements from ReqIF Files.

Note

You can also define a custom document interface to link directly to requirements from third-party applications that Requirements Toolbox does not support. For more information, see Define Custom Document Interface for Direct Linking to Requirements.

Define Custom Document Interface

To define a custom document interface for importing requirements:

1. Author a function that defines and returns an instance of the document interface object, ReqMgr.LinkableType. Your function must take this form:

   function docDomain = myDomainType
       docDomain = ReqMgr.LinkableType;
   end

   The docDomain variable represents the document interface object.

2. Define these properties for the document interface object:

   Name	Description	Value Types	Example Value
   Registration	Requirement document interface name, specified as a string scalar or character vector. The value of this property must be the same as the document interface definition function name.	String Character vector	custom_word
   Label	Label for the custom document type in the Importing Requirements Dialog, specified as a string scalar or character vector.	String 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 empty for requirement documents that are not file based.	Cell array of character vectors	{'.doc','.docx'}
   LocDelimeters	Characters that are used to specify the supported types of location identifiers in the requirement document, specified as a string scalar or 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 $: Cell address in spreadsheet This property is optional.	Character array containing one or more of these characters: ?, @, #, >, $	'?@#'

3. Determine which callback functions your document interface object needs:

   Callback	Description	Required or Optional?	Function Syntax and Description
   NavigateFcn	Function to navigate from imported requirement to original requirement in external document using Show In Document in the Requirements Editor	Optional, but if you do not define this function, Show In Document button does not work	NavigateFcn(document,id) opens the external requirement document specified by document to the requirement specified by id.
   ContentsFcn	Function to get the table of contents of the external requirement document or server	Required	[labels,depths,ids] = ContentsFcn(document) returns requirements information as cell arrays for the external document specified by document. labels contains requirements text, ids contains requirements identifiers, and depths contains the level of the requirement in the hierarchy.
   BrowseFcn	Function to execute when you click the Browse button in the Importing Requirements dialog box for requirement documents that are not file-based. This function is not required for file-based requirements domains.	Optional	BrowseFcn opens the browser for requirement documents in the non-file-based requirements application.
   SummaryFcn	Function to get text for the Summary property of the imported requirements	Optional, but if you do not define this function, you have to manually map an imported attribute to the Summary property. For more information, see Create and Edit Attribute Mappings.	summary = SummaryFcn(document,id) returns the summary for the requirement specified by the identifier id in the external requirement document specified by document.
   HtmlViewFcn	Function to get the HTML view of the requirements content for rich text import and assign it to the Description property of the imported requirements	Optional, but if you do not define this function or TextViewFcn, you have to manually map an imported attribute to the Description property. For more information, see Create and Edit Attribute Mappings.	html = HtmlViewFcn(document,id) returns the HTML content of the requirement specified by the identifier id in the external requirement document specified by document.
   TextViewFcn	Function to get the plain text view of the requirements content for plain text import	Optional, but if you do not define this function or HtmlViewFcn, you have to manually map an imported attribute to the Description property. For more information, see Create and Edit Attribute Mappings.	text = TextViewFcn(document,id) returns the plain text content of the requirement specified by the identifier id in the external requirement document specified by document.
   AttributeNamesFcn	Function to get the names of the requirement attributes to import	Optional, but if you do not define this function, your imported requirements do not have custom attributes or properties except for those imported by SummaryFcn, HtmlViewFcn, or TextViewFcn. For more information about custom attributes, see Create and Edit Attribute Mappings.	[attributes,datatype] = AttributeNamesFcn(document,id) returns the attribute names, attributes, and details about the attribute data type, datatype, for the requirement specified by the identifier id in the external requirement document specified by document. If the attribute type is a Boolean, the datatype output is the default Boolean value, true or false. If the attribute type is numeric, the datatype output is the default numeric value. If the attribute is an enumeration, the datatype output is a cell array of character vectors of the possible enumeration values.
   GetAttributeFcn	Function to get value of the requirement attributes to import	Required if you define a callback function for AttributeNamesFcn	value = GetAttributeFcn(document,id,attrName) returns the attribute value of the attribute attrName for the requirement specified by the identifier id in the external requirement document specified by document.
   CreateURLFcn	Function to get hyperlink to navigate to linked requirement in requirements reports	Optional	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 to get 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.
   BacklinkCheckFcn	Function to check if backlink exists in external requirement documents. 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 to insert backlinks in external requirement documents. 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 to check for stale backlinks in external requirement documents. 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 to delete 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.

4. Author the callback functions that your document interface needs as local functions in the main function.

5. Assign the callback function handles to the corresponding properties of the document interface object.

For an example of a custom document interface, see the custom_jira function.

open(fullfile(matlabroot,"toolbox","slrequirements", ...
    "slrequirements","linktype_examples","custom_jira.m"))

Define Custom Version of Built-In Document Interface

To define a custom version of a built-in document interface:

1. Author a function that defines and returns an instance of one of the built-in document interfaces:

   • Microsoft Word: linktypes.linktype_rmi_word

   • Microsoft Excel^®: linktypes.linktype_rmi_excel

   • IBM^® DOORS^®: linktypes.linktype_rmi_doors

   Your function must take this form:

   function docDomain = custom_word
       docDomain = linktypes.linktype_rmi_word;
   end

2. Overwrite the Registration and Label properties of the document interface object by setting them to custom values. You can also overwrite other properties. For more information, see Define Custom Document Interface.

3. Determine which callback functions to overwrite. For more information, see Define Custom Document Interface.

4. Author new callback functions as local functions in the main function.

5. Assign the callback function handles to the corresponding properties of the document interface object.

   For example, this code sets the NavigateFcn property of the document interface object to a local function called myNavigateFcn.

   function docDomain = custom_word
       docDomain = linktypes.linktype_rmi_word;
       docDomain.NavigateFcn = @myNavigateFcn;
   end
   
   function myNavigateFcn(document,id)
   
   end

For an example of a custom version of a built-in document interface, see the custom_word function.

open(fullfile(matlabroot,"toolbox","slrequirements", ...
    "slrequirements","linktype_examples","custom_word.m"))

Use Custom Document Interface During Import

To use the custom document interface during import:

1. Register the custom document interface.

   rmi register myDomainType

2. Open the Requirements Editor. For more information, see Open the Requirements Editor App.

3. Click Import.

4. In the Importing Requirements dialog, set Document type to the custom document interface.

   

For more information about importing requirements, see Import Requirements from Third-Party Applications.

The custom domain interface registration persists between MATLAB sessions. To unregister the document interface, enter:

rmi unregister myDomainType