Importing Work Items

Work Items defined externally can be imported into Polarion and subsequently managed throughout the application lifecycle. This capability is particularly useful when you have existing document-based assets containing artifacts (requirements, test cases, etc.) that you need to leverage quickly and easily when adopting Polarion. You can import from the following sources to create new Work Items in Polarion:

Importing from Word

For information, please consult the following topics:

Importing from Excel

Microsoft Excel workbooks containing artifacts such as requirements, test cases, defects, etc. can be imported to Polarion to create tracked and managed Work Items of the respective type. During import you have the option to create Work Items in a Document, or as items in the project's tracker. After import into a Document, you have the option to use Word Round-trip to collaborate with external stakeholders who use Microsoft Word. After import to the tracker, you have the option to use Excel Round-trip to collaborate with external stakeholders who use Excel.

Preparing to Import

Before beginning the import from Excel process, there are several things you should do or check:

  • Make sure the configuration of the project into which you will import defines a Work Item type that corresponds to the type of artifact you will be importing. If necessary, customize the configuration to define a corresponding Work Item type. For example, if the Excel document contains test cases, the target project's configuration should define a Work Item type corresponding to test cases.

    Work Item types are defined in Administration: Work Items: Types. If you don't have access to Administration, you can see the currently configured types by opening the project and expanding the Work Items node in Navigation.

  • Familiarize yourself with the data fields of the Work Item type you will be importing, including any custom fields that may be configured for project Work Items in general, and/or for the type of Work Item you will import. Look at an existing item of the type, or if none exist yet, create a new one in the Table view of the Work Items topic. Review the fields but don't save the new item.

  • In the Excel workbook review the Excel worksheet containing the artifacts you will be importing. Rows should correspond to individual Work Items. For example, if the sheet defines requirements, each requirement should occupy one row. (The worksheet can contain a header row.) Columns should correspond to Polarion Work Item fields. Import of multivalued data is supported for some Polarion multivalued fields. See User Reference topic Import from Excel:Multivalued Data and Fields for more information.

    Decide which Excel columns should map to which Polarion Work Item fields. If some columns have no corresponding Work Item fields, and you want to store their data in Polarion, it will be necessary for a Polarion or project administrator to add custom fields to the project configuration before importing. You will be able to specify field mapping during the import process. For information on which Work Item fields are supported for Excel import, see the User Reference topic Import from Excel: Supported Work Item Fields.

    Identify the cell at which the import process should begin. You will need to specify it in the import wizard. Normally this is the leftmost cell on the first row after the header row, if a header row exists. However, it can be any cell. For example, if you have previously imported artifacts from a worksheet, and new ones have been added which you now want to import, you will need to specify the first cell on the first row containing the added items.

  • If the worksheet to be imported contains images, make sure they are in .gif or .png or .bmp or .jpg format if you want them to appear in-line with other content. Images in other formats (.tiff for example) may still import, but will be attachments (rather than appearing in-line) and they will not appear in the import preview.

  • Creating Work Items with links to Work Items from another Polarion Project, is done Before importing. See Linking Work Items Across Projects for details.

Importing to a Document

If your team prefers a document-centered approach to artifact management, you can import artifacts from Excel and store them in a LiveDoc Document. This would be the preferred approach if you will subsequently need to collaborate on artifact content with external stakeholders who use Microsoft Word... your team will be able to use the Word Round-trip feature.

To import Work Items from Excel into a Polarion Document:

  1. Open the project into which you want to import Work Items and in Navigation, select Work Items.

  2. In the Table view, click the Operations button and choose Import to launch the Import Work Items dialog.

  3. In the Format field of the dialog, select xlsx: Microsoft Excel Workbook.

    In the Configuration field, optionally select an import configuration. (Import configurations contain rules that govern how artifacts are imported and mapped.)

    In the File field, specify the locally stored Excel worksheet file you want to import and click Start. The first page of the Import Excel Workbook wizard appears.

  4. In the Import rows from sheet field, select the worksheet that contains the artifacts you want to import in this operation. The list shows all worksheets in the specified workbook. You can only import one worksheet at a time. For example, if a workbook contains requirements in one sheet and test cases in a different sheet, you must do a separate import operation for each type.

    In the Begin import at cell field, specify the cell at which the importer should begin importing artifact data. The importer examines the worksheet and suggests a cell. The cell you specify in this field should not be part of a header row. If the first column is some kind of artifact identifier, you can begin importing from the second column, as Polarion assigns its own IDs to Work Items created during the import process (see figure below).

    Review the Table contains header field. The importer examines the worksheet and checks this field if the sheet appears to contain a header row. (See figure below for an example of a header row.)

    Figure 6.10. Example Excel Sheet

    Example Excel Sheet

    Excel worksheet showing a header row and import start cell

  5. Click the as new Document link to indicate that Work Items should be imported into a new Document. Two editing fields appear.

    In the drop-down list control, select the space where Polarion should create the new Document, and then enter a name for the new Document in the field provided. Note that the Document name must be unique within the specified space. If your project is configured to support Document Types, specify which type the new Document will be.

  6. Click the Next button when you are ready to continue. The field mapping page of the import wizard appears.

  7. Map the worksheet columns to appropriate Work Item data fields. Use the Preview button to check what the import result will be and modify mapping, and/or create more import rules as needed, optionally saving the rules you define for reuse with subsequent Excel imports.

  8. Use the Preview button to preview how the Work Items will look in the Document after importing. Click the Import button to import the Excel artifacts and create Polarion Work Items in the specified space and Document.

Importing to the Tracker

If your team prefers a tool-based approach to artifact management, you can import artifacts into Polarion storing them in the integrated tracker rather than in a Document.

To import Work Items from Excel into the tracker:

  1. Open the target project and in Navigation, select Work Items. The Table view should be the current view when the page loads.

  2. In the Table view, on the toolbar, click the Operations button and choose Import to launch the Import Work Items dialog.

  3. In the Format field of the dialog, select xlsx: Microsoft Excel Workbook.

    In the Configuration field, optionally select an import configuration. (Import configurations contain rules that govern how artifacts are imported and mapped.)

    In the File field, specify the locally stored Excel worksheet file you want to import and click Start. The first page of the Import Excel Workbook wizard appears.

  4. In the Import rows from sheet field, select the worksheet that contains the artifacts you want to import in this operation. The list shows all worksheets in the specified workbook. You can only import one worksheet at a time. For example, if a workbook contains requirements in one sheet and test cases in a different sheet, you must do a separate import operation for each type.

    In the Begin import at cell field, specify the cell at which the importer should begin importing artifact data. The importer examines the worksheet and suggests a cell. The cell you specify in this field should not be part of a header row. If the first column is some kind of artifact identifier, you can begin importing from the second column, as Polarion assigns its own IDs to Work Items created during the import process (see figure in the previous section).

    Review the Table contains header field. The importer examines the worksheet and checks this field if the sheet appears to contain a header row.

    Click the Next button when you are ready to continue. The field mapping page of the import wizard appears.

  5. Map the worksheet columns to appropriate Work Item data fields. Use the Preview button to check what the import result will be and modify mapping, and/or create more import rules as needed, optionally saving the rules you define for reuse with subsequent Excel imports.

  6. Click the Import button to import the Excel artifacts and create Polarion Work Items in the project tracker.

Field Mapping and Import Rules

REMINDER: See Linking Work Items Across Projects to create Work Items with links to Work Items from another Polarion Project Before importing.

After you specify the scope of the data to import, the second page of the import wizard presents an interface enabling you to:

  • Map columns in the worksheet to Work Item fields

  • Specify one or more conditional rules that control how the data is imported.

  • Reuse a previously saved import configuration (i.e. a combination of field mapping and conditional rules).

  • Preview the result of the import with the current mapping and import rules.

  • Save the current field mapping and rules as a reusable import configuration.

  • Import the worksheet data and create Work Items from worksheet artifacts.

The page initially presents a new import rule with field mapping:

Figure 6.11. Excel Import Rule

Excel Import Rule

Import rule for a Requirement, showing mapping from example Excel columns to Work Item fields.

Start by specifying what type of artifact you are importing from the Excel worksheet. Select from the list of currently configured Work Item types. Next, specify the condition(s) for importing data as the selected type. You can add more conditions by clicking the icon.

Next, specify how Excel columns should be mapped to Work Item fields. Proceed from left to right. Column headers are worksheet column names. Cells contain drop-down lists from which you can select a field name. It is not required to specify a field for every column. For example, if the worksheet contains a column with some sort of ID for an artifact, you can skip mapping it because Polarion will assign IDs to all Work Items created by the importer.

When you select some fields, they dynamically display fields for mapping date values in the worksheet to Work Item field values. For example, suppose your Excel sheet has a column "Priority" with numeric values, 1, 2, or 3 which actually corresponds to your Polarion project's "Severity" field, configured with values "Must have", "Should have", "Nice to have". When you select "Severity" in the "Priority" column, the importer detects the data values in the worksheet and presents a drop-down list for each value in which you can specify the corresponding "Severity" field value.

In many cases, a single import rule will give the desired import result. (Remember that you can use the Preview button at any time to preview the result of the import without actually importing. Preview shows only the first 100 matching items found in the sheet.) If a single rule is not robust enough for your needs, you can add more rules. To begin, click the icon labeled Add Work Item Rule. Another set of condition rule plus field mapping is added to the page. Use it to add more parameters to the import configuration.

After Preview shows the import result you want, but before you click Import to trigger the import, consider whether you or other team members might need to import another Excel worksheet using the same rules and mappings you currently have specified. If so, click the gear icon in the header, choose Save, and specify the name and scope of the import configuration.

Creating and Reusing Import Configurations

An "Import Configuration" is a saved import rule or set of import rules. Import Configurations can save significant time and effort when there is a need to import multiple similar Excel worksheets. Import Configurations can be saved in the global scope to make them available across projects, or in the project scope to confine their availability to a single relevant project.

To create a new Import Configuration:

  1. Begin importing an Excel workbook as describe earlier in this chapter.

  2. Define the import rule(s) for an imported worksheet, using preview to verify the import result. When you have the result you want in the preview, but before you click Import, click the drop-down icon (next to the workbook file name on page 2 of the wizard), and choose Save on the menu. This launches the Save Import Configuration dialog with the Create new configuration option selected by default.

  3. In the Scope field, specify the scope of the new Import Configuration (Global or Project).

  4. In the Name field, specify a meaningful name for the new Import Configuration. This name will appear to users in the specified scope in the Configuration field when they import Excel workbooks.

  5. Click Save to create the Import Configuration.

To reuse an existing Import Configuration:

  1. Begin importing an Excel workbook as describe earlier in this chapter.

  2. In the Import Work Items dialog, in the Configuration field, select the Import Configuration to use for the current workbook import.

  3. Select the Excel file to import and click Start.

Note that you can modify the import rules loaded from the saved Import Configuration. You can optionally save the modified import rule as a new Import Configuration, as describe earlier in this topic, or you can overwrite the existing Import Configuration with your changes (select the Update existing configuration option in the Save Import Configurationdialog).

See also: Administrator's Guide: Advanced Administration: Removing Unused Excel Import Configurations.

Importing from Microsoft Project

Past versions of Polarion have supported Work Item import from certain versions of Microsoft Project. This is considered a legacy feature, and later versions of Microsoft Project are not supported. For information see User Guide: Appendix: Importing from Microsoft Project.