Import Requirements from ReqIF Files

Many third-party requirements management applications can export and import requirements using the ReqIF™ format. You can import requirements from a ReqIF file as references to a third-party source called referenced requirements, which are represented as slreq.Reference objects, or as requirements in new requirement sets, which are represented as slreq.Requirement objects. For more information about choosing which import mode to use, see Select an Import Mode.

Choosing an Import Mapping

Before you import requirements and links from ReqIF files, decide which mapping to use. The mapping determines how ReqIF requirement and link data maps to Requirements Toolbox™ requirement and link data. Alternatively, you can map ReqIF data to stereotypes. For more information, see Use Stereotypes when Importing from ReqIF Files.

ReqIF represents requirements as SpecObject objects and links as SpecRelation objects that relate SpecObject objects. Each SpecObjectType object specifies the associated SpecObject object and the SpecRelationType objects classify each SpecRelation object. The SpecObjectType and SpecRelationType objects define attributes to store requirements and link information. The SpecObject and SpecRelation objects contain values for these attributes.

This table shows the relationship between requirements and links in Requirements Toolbox and their ReqIF counterparts.

Item	Representation in Requirements Toolbox	Representation in ReqIF
Requirement	`slreq.Requirement` object `slreq.Reference` object	`SpecObject` object
Requirement type	`Type` property of `slreq.Requirement` object `Type` property of `slreq.Reference` object	`longName` attribute of the `SpecObjectType` object
Requirement attributes	`slreq.Requirement` properties `slreq.Reference` properties Custom attributes for requirement sets	`SpecObjectType` objects define attributes `SpecObject` objects define attribute values
Link	`slreq.Link` object	`SpecRelation` object
Link type	`Type` property of `slreq.Link` object	`longName` attribute of the `SpecRelationType` object
Link attributes	`slreq.Link` properties and custom attributes	`SpecRelationType` objects define attributes `SpecRelation` objects define attribute values

For more information about ReqIF data organization, see the Exchange Document Content section in Requirements Interchange Format (ReqIF) Version 1.2lo.

When you import requirements and links from a ReqIF file, you can choose the import mode that you use based on how the import process maps the requirements from ReqIF to Requirements Toolbox. The import process maps the SpecObject objects to slreq.Requirement objects or slreq.Reference objects, depending on the import mode, and SpecRelation objects to slreq.Link objects. The imported requirement type, properties, and imported link type depend on the import mapping that you choose.

Requirements Toolbox provides built-in import mappings for some third-party applications that use ReqIF:

IBM^® Rational^® DOORS^®
IBM DOORS Next
Polarion^®
PREEvision
Jama

When you import requirements from ReqIF files generated by other requirements management applications, you can use a generic attribute mapping.

After you import requirements, you can edit the attribute mappings. See Mapping ReqIF Attributes in Requirements Toolbox.

Note

If you experience problems navigating from requirements in Polarion to items in MATLAB^® or Simulink^® due to changes to navigation URLs enforced by Polarion, you may need to apply a configuration change. Open the polarion.properties file found in the <polarion_installation>/polarion/configuration/ folder and modify these lines by replacing localhost with the externally known name for your server:

repo=http://localhost:80/repo/
base.url=http://localhost:80/

Using the Built-In Mapping During Import

When you import a ReqIF file and use the built-in mapping for the third-party tool that generated the file, Requirements Toolbox imports the SpecObject objects as requirements with Type set to Functional regardless of the associated SpecObjectType object. If the SpecObjectType objects define additional attributes in the third-party tool, the attributes map to built-in requirements properties, including Custom ID or ID, Summary, Description and revision information. The remaining attributes map to new custom attributes. For more information about requirement custom attributes, see Add Custom Attributes to Requirements.

After you import the requirements, you can map the SpecObjectType objects to requirement types. You can also edit the SpecObjectType object attribute mappings to requirement properties. See Mapping ReqIF Attributes in Requirements Toolbox.

When you import links using the built-in mapping, Requirements Toolbox imports SpecRelation objects as links and maps the SpecRelationType objects to link types in Requirements Toolbox. If a SpecRelationType in the ReqIF file is not defined in the import mapping, then SpecRelation objects with that type import as links with Type set to Related to. For more information about link types, see Link Types.

Using the Generic Mapping During Import

When you import a ReqIF file and use the generic mapping, Requirements Toolbox imports the SpecObject objects as requirements with Type set to Functional. The SpecObjectType object attributes map to the CustomID or ID, Description, and Summary requirement properties, and to new custom attributes. For more information about requirement custom attributes, see Add Custom Attributes to Requirements.

After you import the requirements, you can map the SpecObjectType objects to requirement types. You can also edit the SpecObjectType object attribute mappings to match your desired requirement properties. See Mapping ReqIF Attributes in Requirements Toolbox.

When you import links by using the generic mapping, the SpecRelation objects import as links with Type set to Related to. For more information about link types, see Link Types.

Importing Requirements

You can import requirements in the Requirements Editor. Requirements in ReqIF files belong to specifications.

Tip

To import images associated with requirements, use the third-party tool to export the requirements as a .reqifz file and then import the file to Requirements Toolbox.

Open the Requirements Editor with one of these approaches:
- At the MATLAB command line, enter:
  slreq.editor
- In the MATLAB Apps tab, under Verification, Validation, and Test, click the Requirements Editor app.
- In the Simulink Apps tab, under Model Verification, Validation, and Test, click the Requirements Editor app.
In the Requirements Editor, click Import.
In the Importing Requirements dialog, set Document type, to ReqIF file (*.reqif or *.reqifz).
Next to Document location, click Browse and select the ReqIF file.
Under Attribute mapping, in the Source tool drop-down, select the desired attribute mapping. See Choosing an Import Mapping.
Under Destination(s), click Browse. Enter the file name, select the location to save the new requirement set, and click Save.
Select whether to allow updates to the imported requirements. If you want to continue to manage your imported requirements in the third-party tool, select Allow updates from external source, which imports the requirements as referenced requirements. If you want to migrate your requirements to Requirements Toolbox, clear Allow updates from external source. For more information about import options, see Select an Import Mode.
Click Import to import the requirements.

The imported requirements maintain the requirement hierarchy.

Importing Requirements from a ReqIF File with Multiple Specifications

If you import a ReqIF file that contains multiple source specifications, you can select options in the Source specifications section in the Importing Requirements dialog. You can:

Select a single ReqIF source specification to import into a requirement set. In the Importing Requirements dialog, under Source specifications, select Import a single specification and choose a specification from the list.
Combine ReqIF source specifications into one requirement set. In the Importing Requirements dialog, under Source specifications, select Combine all specifications into one Requirement Set.
If you select Allow updates from external source, then each specification is imported into a separate Import node. You can update each Import node independently. Otherwise, each source specification imports as a parent requirement and all requirements in the specification import as its children.
Import each ReqIF source specification into a separate requirement set. In the Importing Requirements dialog, under Source specifications, select Import each specification into a separate Requirement Set. Under Destination(s), next to Folder, click Browse and select a destination folder location to save the requirement sets in.

The resulting requirement set file names are the same as the source specification name. If you have an existing requirement set file with the same name as one of the source specifications in the selected destination, it is overwritten.

Tip

For large ReqIF files, consider importing each source specification into a separate requirement set. This can help reduce file conflicts and help you track differences in individual requirement sets.

When deciding which import method to use for a ReqIF file that contains multiple source specifications, consider if you are importing links and if you plan to export back to ReqIF. For more information, see Importing Links and Considerations for ReqIF Files with Multiple Specifications.

Importing Links

When you import a ReqIF file to a requirement set, you can import links as well. To import links, in the Importing Requirements dialog, under Source links, select Import links to preserve the links from the ReqIF file. After the import, the Requirements Toolbox link set files contain links between requirements and other Model-Based Design items.

ReqIF files represent links as a SpecRelation object that relates two SpecObject objects. You can only import links if the ReqIF file contains at least one SpecRelation object.

Importing Links from a ReqIF File with Multiple Source Specifications

When you import links from a ReqIF file with multiple source specifications, how you import the source specifications affects the link import. If you:

Import a single specification into a requirement set, Requirements Toolbox only imports the SpecRelation objects that link SpecObject objects within that specification. This import might omit some links from the ReqIF file during import.
Combine multiple ReqIF source specifications into one requirement set, the resolved links import into one link set.
Import each ReqIF source specification into a separate requirement set, the resolved links import into separate link sets.

Importing Links from a ReqIF File Generated by Requirements Toolbox

If you link a requirement in Requirements Toolbox to an item that is not contained in the requirement set, such as a Simulink block, and then export the requirement and associated links to a ReqIF file, the export process inserts a SpecObject object into the ReqIF file that serves as a proxy object for the linked item. If the linked item is one of the supported types, the proxy object has a SpecObjectType longName value that describes the linked object type. For more information, see Exporting Links.

When you re-import this ReqIF file, the software reconstructs the links that relate the proxy SpecObject objects and requirements for proxy objects of the supported types. Links between the proxy SpecObject objects that have the SpecObjectType longName attribute set to Requirement cannot be reconstructed.

To reconstruct the links when you import a ReqIF file, in the Importing Requirements dialog:

Under Source specifications, select either Combine all Specifications into one Requirement Set or Import each specification into a separate Requirement Set.
Under Source links, select Import Links.

The reconstructed links use the Requirements Toolbox default link storage. For more information, see Requirements Link Storage. The reconstructed links are appended to the link set for the artifact that contains the link source. If the link set is not available, it is created with the same base file name as the artifact and stored in the same folder as the artifact.

Mapping ReqIF Attributes in Requirements Toolbox

ReqIF represents a requirement as a SpecObject object with a SpecObjectType object that defines requirement attributes. When you import requirements from a ReqIF file, the attributes map to requirement properties or custom attributes according to the import mapping that you choose. See Choosing an Import Mapping.

After you import the requirements, you can edit the SpecObjectType object attribute mapping. Select the Import node, which is denoted by , or the top-level requirement, depending on how you imported the requirements. In the right pane, under Attribute Mapping, you can edit the attribute mappings. You can save the current mapping by clicking Save mapping. You can load a saved mapping by clicking Load mapping. For more information, see Edit the Attribute Mapping for Imported Requirements.

Map `SpecObjectTypes` to Requirement Types

After you import the requirements, you can map the SpecObjectType objects to requirement types in Requirements Toolbox.

In the Requirements Editor, select the Import node, which is denoted by , or the top-level requirement, depending on if you imported the ReqIF requirements as referenced requirements or requirements.
In the right pane, under Attribute Mapping, click Map Object Types.
The Map Object Types dialog appears. Imported (external) type lists the SpecObjectType objects and Internal (built-in or custom) type lists the available Requirements Toolbox requirement types. Map each SpecObjectType object by selecting a requirement type from the list. For more information about requirement types, see Requirement Types. You can also select <Add custom subtype> to add a custom requirement type that is a subtype of a built-in type. For more information about custom requirement types, see Define Custom Requirement and Link Types by Using sl_customization Files.

To add a custom requirement type:
1. In the Add Subtype for Requirements dialog, set Parent type name to extend to the built-in requirement type that you want the custom requirement type to inherit from.
2. Next to New subtype name, enter the name for your new custom requirement type.
3. Next to Description, enter a description for your new custom requirement type.
4. Click OK to create the custom requirement type.
Click OK to map the SpecObjectType objects to requirement types. A dialog lists the number of items updated.

Navigate from Referenced Requirements to Requirements in Third-Party Applications

To navigate from a referenced requirement to the original requirement in the third-party application, create a navigation callback function and register the function in MATLAB.

Create a navigation callback function. Optionally, you can use the Requirements Toolbox template to develop your navigation callback function. To generate the template:
1. Import your requirements to Requirements Toolbox.
2. In the Requirements Editor, select a referenced requirement and, in the right pane, under Properties, click Show in document.
3. In the Requirement Navigation Error dialog box, click Go to Editor. The generated template opens in the MATLAB Editor and is saved in the current folder. Add your navigation callback function to the template.
Register the navigation callback function by using slreq.registerNavigationFcn. Enter the name of the application that generated the ReqIF file, which is specified in the Domain property of the Import node. Use slreq.getNavigationFcn to confirm that you registered the callback.

To navigate from a referenced requirement in Requirements Toolbox to the original requirement in the third-party application, in the Requirements Editor, select a referenced requirement and, in the right pane, under Properties, click Show in document.