Importing requirements artifacts from CSV and spreadsheet files

You can import data from comma-separated values (CSV) and spreadsheet files into folders and modules in an RM project.

You can import and export CSV files or spreadsheets in Microsoft Excel (XLS) and Office Open XML (XLSX) format. When you import requirements that were previously exported from IBM Rational DOORS Next Generation, they can include markup text for links and embedded artifacts. During the import process, this markup text is used to create or update the links and embedded artifacts.

Prerequisites for importing CSV and spreadsheet files

  • Review the limitations described in the Importing and exporting CSV and spreadsheet files topic.
  • Read the CSV file format and examples topic.
    Note: Spreadsheet files must conform to the same content rules as CSV files.
  • Make sure that the file to import is encoded in UTF-8. If you are working with data in an external application, make sure that the application supports UTF-8.
  • Make sure that the project has an artifact type that is defined for each unique type name in the Type column. If type errors occur when you import a CSV file, limit the file to only one artifact type at a time. Also, you might want to divide large CSV files into smaller chunks. If other errors occur, make sure that special characters are escaped, as described in the RFC 4180 document.
  • If you created the CSV file in another application, remove extra spaces or unsupported fields from the file before you import it.
  • Escape any apostrophes or quotation marks in the file, as described in the RFC 4180 document.
  • Depending on your needs, you might assess and create custom attributes. For more information, see Managing project properties in requirements projects.
  • To import a CSV file that has attribute values of the enumeration type, verify that those values are defined for the corresponding attribute type in the target project. Otherwise, the import fails.

Import process

To build a correctly formed CSV file for import, export from a view that contains columns that correspond to the content to import. If you export from a view, the exported file contains unsupported system-maintained fields. However, these fields are ignored if they are included in an import operation. For more information about exporting from a view, see Exporting requirements artifacts to CSV and spreadsheet files.

If you export the hierarchy of artifacts in a module, remove a parent artifact, but not the associated child artifacts, and then try to import the file, the import fails. You can prevent this by either removing the child artifacts from the parent artifact, or promoting the child artifacts to the nearest parent artifacts.

To start an import, open the Artifacts page and at the Create or More Actions menu, click Import Artifact. Click Import requirements from a CSV file or spreadsheet. After you select a CSV file or spreadsheet, you can choose to import requirements into a folder or into a module. You can choose to update artifacts that match the imported requirements, or create new artifacts. When you update existing artifacts, you can ignore imported requirements that do not match existing artifacts or create new artifacts from the new imported content. After you make your selections, click Finish.

You can import artifacts in a hierarchical import by using special fields in the CSV file.

Example 1

The following sample CSV file represent the module artifacts, Feature 1, Feature 11, and Feature 12:
Identifier,Artifact Type,Name,parentBinding
100,Feature,Feature1,""
101,Feature,Feature11,100
102,Feature,Feature12,100
The Identifier column is required for module related imports. The identifier is used to establish a parent relationship between the CSV records representing the module artifacts. The identifier is also used to group the module artifacts with their modules.

The parentBinding column is also used for module related imports in conjunction with Identifier.

The module column is used for module related imports and dictates which modules defined in the CSV file are the intended target for the records representing module artifacts. The module column can be ignored when there are no modules defined in the CSV file.

When imported, Feature 11 and Feature 12 are placed under Feature 1 and the artifacts are hierarchically arranged in a module:

Screen capture of artifacts in module

Example 2

The following sample CSV file defines two modules, Module 1 and Module 2. The module artifacts Feature 1, Feature 11, and Feature 12 belongs to Module 1. The module artifacts Feature 2 and Feature 4 belongs to Module 2.

Identifier, Artifact Type, Name, parentBinding
99, Module, Module1, ""
100, Feature, Feature1, ""
101, Feature, Feature11, 100
102, Feature, Feature12, 100
103, Module, Module2, ""
104, Feature, Feature2, ""
105, Feature, Feature4, ""

After the import, the Feature 11 and Feature 12 will be placed under Feature 1. If the order of CSV record is changed, the import result will be different. For example, if the modules are defined first, the Feature 1, Feature 11, Feature 12, Feature 2, and Feature 4 will be imported in the Module 2. In this case, to obtain desired result, the module column can be used:

Identifier, Artifact Type, Name, parentBinding, module
98, Module, Module1, "", ""
99, Module, Module2, "", ""
100, Feature, Feature1, "", 98
101, Feature, Feature11, 100, 98
102, Feature, Feature12, 100, 98
104, Feature, Feature2, "", 99
105, Feature, Feature4, "", 99
For information about the special fields and setting up a CSV file before you import data into a module, see Importing and exporting using the CSV format on Jazz.net. Content on Jazz.net is governed by the Jazz.net Terms of Use and is provided as-is without warranties of any kind.
Warning: When importing a CVS file, if there is an error in any row or column, then the entire import will fail and no data will be imported.