Importing artifacts from ReqIF files to a requirements project or component

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 additional 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, only system-defined attributes and types are merged. 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 a type resource being imported has the same name as an existing type resource, then the incoming type will be 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 and 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 performs one of the following actions:
    1. Creates a new 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 has changed.
Note: If any items imported into the configuration were deleted, a new version of the deleted resource is created and mapped to the import 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 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, if you have an existing artifact named Artifact Type A, with attributes A and B, and 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 parents 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 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, 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 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 using 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 only set 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 have defined module hierarchy in the specified module, select the Place new artifacts with no module hierarchy in a module check box.
      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 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 check box. Use one of the following option:
      • 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.

      The Import Tagging Options feature enables you to determine 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.

    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 Type Mapping.
  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

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) check box and then click Next.
    Note: You can upload a package (.zip 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. 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 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 check box 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 check box.
    3. To restrict the creation of artifacts, clear the Allow artifact creation check box 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) check box.
    5. To prevent modifications to artifact types, clear the Allow modification of existing artifact types check box. This option prevents changes to the title, description, and RDF URI of all the artifact types.
    6. To prevent modifications to attribute definitions, clear the Allow modification of existing attribute definitions check box. 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 check box.
  6. Select the specifications to import to the current project or component. 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. Select the attributes to import. 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.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki