Import Requirements from ReqIF Files

You can import requirements and links from third-party requirements management tools that use Requirements Interchange Format (ReqIF™) files. Requirements Toolbox™ maps ReqIF requirement and link types and attributes to Requirements Toolbox requirement and link types and properties and custom attributes. You can manage the requirements in the third-party tool or migrate the requirements to Requirements Toolbox. If you manage the requirements in the third-party tool, you can also navigate between imported referenced requirements and the original requirements in the tool.

Choose an Import Mapping

When you import requirements and links from ReqIF files, you must choose an import mapping that maps the ReqIF requirement and link types and attributes to Requirements Toolbox requirement and link types, properties, and custom attributes.

Tip

Instead of using a built-in or generic mapping, you can create a profile during import to map the ReqIF requirement and link types and attributes. Requirements Toolbox maps each ReqIF requirement and link type to a new stereotype in the profile and maps the requirement and link attributes to stereotype properties. For more information, see Use Stereotypes when Importing from ReqIF Files.

Requirements Toolbox includes import mappings for these third-party tools:

• IBM^® DOORS^®

• IBM DOORS Next

• Polarion™

• PREEvision

• Jama

Requirements Toolbox also includes a generic mapping, which you can use if there is no import mapping for your third-party tool.

When you import ReqIF files, the software maps the requirement and link types and attributes depending on the import mapping you choose.

Import Mapping	Description
IBM DOORS IBM DOORS Next Polarion PREEvision Jama	Requirements import with Type set to Functional. Requirement attributes map to built-in requirements properties, including Custom ID or ID, Summary, Description, CreatedBy, CreateOn, ModifiedBy, and ModifiedOn, or to new custom attributes. The import mapping for each tool maps the requirement attributes differently. Links import with Type set to the types described in the mapping file for that tool, or to Relate. The link attribute Text maps to the link property Description. Other link attributes do not import.
Generic	Requirements import with Type set to Functional. Requirement attributes map to built-in requirements properties, including Custom ID or ID, Summary, and Description, or to new custom attributes. Links import with Type set to Relate. The link attribute Text maps to the link property Description. Other link attributes do not import.

After you import the requirements, you can edit the type and attribute mapping. For more information, see Map ReqIF Types and Attributes.

Define Alternative Mappings

You can also define a custom import mapping for your tool that specifies how to map the requirement and link types and attributes.

To define a custom import mapping, create an XML file that uses a structure similar to the mapping files defined in the directory fullfile(matlabroot,"toolbox","slrequirements","slrequirements","attribute_maps"). In the XML file, set the name attribute of the datamodel.MappingOptions element to the same name that your third-party tool specifies in generated ReqIF files for the REQ-IF-TOOL-ID element.

To use a custom import mapping, register the folder that contains the mapping by using the ReqifMappingFilePath name-value argument for the rmipref function. When you import the ReqIF file, Requirements Toolbox selects the import mapping that matches your third-party tool if the name in the custom import mapping XML file matches the name in the ReqIF file. Otherwise, you can select the custom mapping from the list. For more information, see Import Requirements.

To refresh the registered custom import mappings, use the slreq.updateReqIfMappings function. To unregister the custom import mappings, set the reqifMappingFilePath name-value argument of rmipref to an empty string, then refresh the registered custom import mappings.

Import Requirements

To import requirements from ReqIF files:

1. Open the Requirements Editor by using 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.

2. In the Requirements Editor, click Import.

3. In the Importing Requirements dialog, set Document type to ReqIF file (*.reqif or *.reqifz).

4. Next to Document location, click Browse and select the ReqIF file.

   

5. Under Attribute mapping, set Source tool to your desired import mapping. See Choose an Import Mapping.

6. Under Destination(s), click Browse. Enter the file name, select the location to save the new requirement set, and click Save.

7. Select whether to allow updates to the imported requirements. If you want to manage your imported requirements in a 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.

8. Click Import to import the requirements.

The imported requirements maintain the requirement hierarchy.

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.

Note

When you import ReqIF files whose requirements have multivalued enumeration attributes, Requirements Toolbox sets the attribute value to a single value.

Import Requirements from ReqIF Files with Multiple Specifications

Requirements in ReqIF files belong to specifications. If you import a ReqIF file that contains multiple source specifications, you can select these specifications 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 imports 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 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 Import Links and Considerations for ReqIF Files with Multiple Specifications.

Import 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.

Import Links from ReqIF Files 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 links that link requirements 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.

Import Links from ReqIF Files 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 link proxy object for the linked item into the ReqIF file. Requirements Toolbox sets the type name for the link proxy object to a name that describes the object for some link objects. For more information, see Export Links.

When you re-import this ReqIF file, the software reconstructs the links that relate the link proxy objects and requirements only for link proxy objects that have type names other than Requirement. Links to link proxy objects that have their type name set to Requirement cannot be reconstructed.

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

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

2. Under Source links, select Import Links.

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

Map ReqIF Types and Attributes

After you import the requirements, you can edit how the ReqIF requirement types map to Requirements Toolbox requirement types. Select the Import node 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 Requirement Types

To map the ReqIF requirement types:

1. Open the Requirements Editor. If you imported the ReqIF requirements as referenced requirements, select the Import node. If you imported the ReqIF requirements as requirements, select the top-level requirement.

2. In the right pane, under Attribute Mapping, click Map Object Types.

   

3. In the Map Object Types dialog, Imported (external) type lists the ReqIF requirement types and Internal (built-in or custom) type lists the available Requirements Toolbox requirement types. Select 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.

   

4. Click OK to map the types. A dialog lists the number of updated items.

Navigate from Imported Requirements to Original Requirements

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

1. 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.

2. Register the navigation callback function for the application that generated the ReqIF file 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.

   Note

   When you register the navigation callback function and specify the name of a third-party application, Requirements Toolbox associates the callback function with all requirements that you import from ReqIF files generated by the specified application.

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.

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/