Importing artifacts from ReqIF files to a requirements project or component

Edit online

You can import the data in a Requirements Interchange Format (ReqIF) file from your file system to a requirements project or component.

Before you begin

Before you import a ReqIF (.reqif or .reqifz) file, ensure that the file that you are importing is encoded in UTF-8.

To import a ReqIF file, you must have write access and the Import ReqIF permission.

About this task

When you import a ReqIF file (.reqif or .reqifz), you use a wizard in which you select the ReqIF file to upload and import. After you upload the file, you can either import the ReqIF data or close the wizard and import the ReqIF data at another time. After the import process is complete, a report is displayed that shows a list of the imported data. You can go to imported artifacts in the project or component by using the links that are generated in the report.

You can use the standard import option, where you can select the ReqIF file to import and follow the instructions. For more information, see Using the standard import option.

You can also use the advanced import option, where you can specify more import options. For more information, see Using the advanced import option.

Important: The first time that you import ReqIF data, types, and artifacts are created. If you import the same data later, all data is updated except for the view column information. During an import, system attributes and system data types are merged. If a mapping context is selected, then the importer attempts to match attributes and data types by their title. Artifact types, attributes, data types, and folders that were not already imported from a ReqIF file are created in the project or component that you are importing to. If an imported type resource has the same name as an existing type resource, then the incoming type is renamed by adding a suffix. "[DNG-Renamed-<X>]" where <X> is the next available number for the type name and suffix. For example, the file that you are importing and the project or component that you are importing to might both contain a Priority attribute. In that case, an attribute named Priority [DNG-Renamed-1] is created during the import.
You can import several types of data from a ReqIF file, including these types:
  • Textual artifacts
  • Graphical artifacts
  • Diagram artifacts
  • Attribute definitions
  • Data types
  • Folders and folder hierarchies
  • Links
  • Link types
  • Tags
  • Modules
  • Artifact types
  • Collections
  • View column information, which is imported during the first import only.
If you import the following types of items in a configuration-enabled environment, the import creates a new version of the resource. Also, it maps it to the import configuration if the resource was already imported into another configuration in the component or project.
  • Data types
  • Attributes
  • Artifact types
  • Modules
  • Artifacts
  • Folders
  • Links
  • View column information

For more information about ReqIF usage scenarios, see ReqIF Usage Scenarios.

Important:
  • If a resource was previously imported into a different stream or change set in a component or project, the import completes the following actions:
    1. Creates a version of the resource in the stream or change set at the import location.
    2. Updates the resource if it is already available at the import location.
  • If a resource was not previously imported into any of the streams or change sets in a component or project, the import creates the resource at its import location.
  • If a resource was previously imported into the stream or change set in a component or project, the import updates the resource if it was changed.
Note: If any items imported into the configuration are deleted, a new version of the deleted resource is created and mapped to the imported configuration.
The following types of data cannot be imported:
  • View filtering information
  • Comments
  • Reviews
  • Audit histories

You can import ReqIF files in XML format or a compressed file format. If a ReqIF file references external attachment files or embedded OLE files, which occur in some exports from IBM Engineering Requirements Management DOORS (DOORS), the ReqIF file, and the referenced external files must be in one compressed file to ensure that the correct associations are created in the requirements project or component. When you import a ReqIF file that contains embedded OLE objects from DOORS, the OLE objects are created as file resources in the requirements project or component.

When you import a ReqIF package, existing artifact types are updated and the attributes are retained: they are not removed.

For example, you have an existing artifact that is named Artifact Type A, with attributes A and B. You import a package that contains Artifact Type A, with attributes A and C, the updated artifact is Artifact Type A, with attributes A, B, and C.

If the package includes only portions of a module, when the package is imported, new artifacts are added to the existing module structure. Artifacts that are not included in the package but exist in the module structure are never deleted.

If child artifacts are moved to new parent artifacts as described in the imported package, the previous parent is also included in the package. If the previous parent is not included in the package, the child artifact is not moved. The following example shows that how a child artifact can move during the import process:

Table 1. Example of how the structure of artifacts can change during the import process
Existing package Package being imported Resulting structure (moved artifacts are in bold)
Parent artifact 1
  • Child artifact A
Parent artifact 2
  • Child artifact B
Parent artifact 3
  • Child artifact C
Parent artifact 1
  • Child artifact A
  • Child artifact B
  • Child artifact C

Parent artifact 2
Parent artifact 1
  • Child artifact A
  • Child artifact B

Parent artifact 2

Parent artifact 3
  • Child artifact C
If you import a ReqIF package that has only one link endpoint, and you later import another ReqIF package that has the other endpoint and the link. As a result, the link is created between the two endpoints. Incremental links are supported for the following imports:
  • Artifact to artifact
  • Artifact to module
  • Artifact to collection
  • Module to module
  • Module to collection
  • Collection to collection

Packages from IBM Engineering Requirements Management DOORS Next (DOORS Next) contain a link when either endpoint is exported. Packages from DOORS contain a link only when both endpoints are exported.

You can also import data by using ReqIF from DOORS to DOORS Next. You can create a ReqIF definition in DOORS and export the definition to a ReqIF package. You can then import the ReqIF package in DOORS Next to get the required data. For more information about exchanging requirements data that uses ReqIF, see Exchanging requirements with other databases and Migrating DOORS project data to DOORS Next.

Some ReqIF packages contain system properties. If the system property values are not usable, they are not displayed in the comparison wizard. This principle applies to packages from DOORS, DOORS Next, and tools in the ProSTEP ReqIF Implementation Guide. For more information, see prostep. The following attribute values are set only when, from an import, an artifact is created for the first time in a component:
  • ForeignID
  • ForeignCreatedOn
  • ForeignCreatedBy
For example, when you import a new artifact, the ForeignModifiedOn and ForeignModifiedBy attribute values are set. But, when you import an existing artifact, the ForeignModifiedOn and ForeignModifiedBy attribute values are only set when one or more values change.

For more information about the ReqIF format specification, see Requirements Interchange Format.

When you export ReqIF data from DOORS to DOORS Next, you must map system attributes to URIs in DOORS. For more information, see System attributes and Mapping attributes to URIs for external applications.

Procedure

  1. Open a requirements project or component.
  2. On the Artifacts page, click Create and click Import Artifact.
  3. In the Import wizard, select Import requirements from a ReqIF file and click Next.
    You can use this standard import option where you can select the ReqIF file to import and follow the instructions.
    Tip: You can also use the advanced import option with extended options to configure the import. For more information, see Using the advanced import option.
  4. Browse the file to import and click Import.
  5. After the file is fully uploaded, complete one of the following steps:
    • To close the Import wizard and continue the import later, click Close. When you are ready to continue the import, start the Import wizard and click Import requirements from a ReqIF file in this component or project.
    • To continue the import, click Next and follow the prompts in the wizard.
  6. Optional: Specify the import options for the import:
    1. Specify the folder or module where you want to import the ReqIF file. To place new artifacts that do not define module hierarchy in the specified module, select the Place new artifacts with no module hierarchy in a module checkbox.
      Important: When you select the folder or module to place the new artifacts in, that folder or module is used only for artifacts that do not have a defined folder or module hierarchy. If a ReqIF file was exported with the Include Folders option that is selected, that folder hierarchy is used starting from the root folder, regardless of the folder that you specify. This premise also applies to ReqIF files exported by DOORS because they always include the folder structure.
    2. To tag the existing artifacts that are not present in the ReqIF package, under the Import Tagging Options section, select the Tag artifacts that are present in repository modules being updated, but are not present in the package checkbox. Use one of the following options:
      • To define a new tag for the artifacts, select Create new tag. Specify the new tag.
      • To use an existing tag, select Use Existing tag. Click Pick Tag. In the Select Tag window, type the name of the tag or select an existing tag from the list and then click OK.
      Note:
      • The Import Tagging Options feature determines whether an artifact that was previously imported in a module is absent in a subsequent import. The most common reason for an artifact to be absent in subsequent import is that the artifact is deleted on the sender side of the ReqIF exchange.
      • Tagging Options work on artifacts only and you cannot apply them to any modules that are deleted.
    3. To apply mapping context to an imported package, under the Apply Mapping Context section, select Select Context. Select an existing context from the Available Contexts list and then click OK.
      For more information about mapping contexts, see Mapping Contexts.
  7. Optional: Select the attributes to import. You can select either all attributes or specific attributes.
  8. Optional: To see a list of the data that is imported, click Show Report.
    The report includes the name, ReqIF ID, and URI of the data, and other information. You can access the report at any time from the project or component properties ReqIF page.

Using the advanced import option

Edit online

About this task

You can use the advanced import option to import artifacts from ReqIF files to your requirements project or component. The following steps describe the procedure of using the advance import option.

Procedure

  1. Open a requirements project or component.
  2. On the Artifacts page, click Create and click Import Artifact.
  3. In the Import wizard, select the Import requirements from a ReqIF file (Advanced) checkbox and then click Next.
    Note: You can upload a package (compressed file) that contains multiple .reqifz files. If you use the Import requirements from a ReqIF file (Advanced) option wizard to import the package, the import settings apply to all files in the package.
  4. Select the file to import and click Upload. After the file is uploaded, detailed information for each uploaded ReqIF file is available. You can see a summary of the package and ReqIF files, and view how many specifications, artifacts, types, and attributes are in the uploaded package. Click Next to continue the import. To view the import report, click Analysis Results. The analysis report shows information about these types of errors if they occur in an incoming ReqIF package:
    • A specification hierarchy in a specification points to a specification object that isn't in the package.
    • An attribute definition points to a data type that doesn't exist in the package, or the types of both are mismatched.
    • A specification object value points to an attribute definition that doesn't exist in the package, or the types of both are mismatched.
  5. Optional: Specify the following import options for the import:
    1. To select the location to which to import the new module files, select the Choose location for new modules checkbox and specify the location.
    2. To add new artifacts that are not in a module hierarchy in the selected module, select the Place new artifacts with no module hierarchy in a module checkbox.
    3. To restrict the creation of artifacts, clear the Allow artifact creation checkbox in the Advanced Import Options section of the page.
    4. To prevent artifacts in modules from being moved to other modules, clear the Allow artifact move (within modules) checkbox.
    5. To prevent modifications to artifact types, clear the Allow modification of existing artifact types checkbox. This option prevents changes to the title, description, and RDF URI of all the artifact types.
    6. To prevent modifications to attribute definitions, clear Allow modification of existing attribute definitions checkbox. This option prevents changes to the title, description, and RDF URI of all the attribute definitions.
    7. To prevent changes to the title, description, and RDF URI of all the data types, clear the Allow modification of existing data types checkbox.
    8. Click Next.
  6. Select the specifications to import to the current project or component and click Next. If you hover over a specification in the import wizard, a preview window shows the details of the specification and the artifact types in it.
  7. If mapping context is not specified, select the attributes to import and click Next. You can select either all attributes or specific attributes. After you specify the advanced import options, the ReqIF file is imported. You can view the status of the import on the Importing Requirements page.

Results

Artifacts get successfully imported from ReqIF files from your system to a requirements project or component.

You can watch the below video, to learn more about Data migration from DOORS to the RM application: