Exporting Work Items

You can export a set of Work Items to various formats:

You can select a subset of all existing items for export using a search query in the Table, Live Plan, or Road Map views. Supported Microsoft Office versions are listed in the installation guide documentation bundled with Polarion distributions.

Basic Export Procedure

To export Work Items to a document or other supported format:

  1. In the Table view of the Work Items topic or a Document, use an appropriate query to retrieve the set of Work Items you want to export. (Depending on your license, it may be possible to do the above in other views. The Table view is present with every license.)

  2. Click and choose Export to display the Export Work Items dialog.

  3. In the Format field, select the target file format for the export output.

    The dialog presents different export options depending on the content being exported and your selection in the Format field:

    • Template: If shown, you may choose the template to be used to format the export output.

      Your choice of an export template may be overridden by a custom plugin implemented by your organization (See note below).

    • Available/Selected Columns: If shown, you can select from a list of available data fields (columns in tabular formats), and add them to a list of selected fields/columns which will then have values from the selected fields included in the export output.

    • If the csv: Comma separated values Format is selected, you're given an option to Remember this selection. When selected, Polarion will remember the fields and columns you chose for future csv: Comma separated values exports.

  4. If the Advanced options link appears for the selected format, it leads to additional format-specific export options such as the Charset. Check the settings to be sure no changes are needed.

  5. Click OK to begin exporting. You will be prompted to specify a location for storing the exported file locally.

Note About Export Template Override

Organizations can optionally implement restrictions via the plugin API to influence the template used for export to Microsoft Word and Excel, with restrictions on individual exports by individual users, to include a watermark in the exported documents and/or to conform to other required policies.

If such a plugin is in use, the Export Work Items dialog shows a message under the Template field when Word or Excel is selected as the target format: "The selected template may be substituted with one that complies with company policy."

Linked Work Items in Exports

When you export Work Items to CSV or Excel Round-trip format, Work Items linked to and from the exported items can optionally be included in the exported document. Items linked via derived links, items cited in Subversion commit messages for example, can also be included in the export to CSV or Excel Round-trip.

You include linked Work Items in the export by adding one or more of the following from the Available Columns to the Selected Columns list in the Export Work Items dialog:

  • Externally Linked Work Items

  • Linked Work Items

  • Linked Work Items Derived

Repository Revisions in Exports

When you export Work Items to CSV or Excel Round-trip format, you can optionally include revision numbers of any linked repository revisions in the output. Revisions linked to linked Work Items will also be included. Revision numbers in the exported document are formatted as hyperlinks which lead to the revision in your Polarion portal, displayed in the Repository Browser.

You include linked revisions in the export by adding Linked Revisions, from the Available Columns, to the Selected Columns list in the Export Work Items dialog.

Exporting the Hierarchical Table

When the Tree presentation option is selected in the Table view, then when exporting to MS Word the tree structure appears in the exported Word document. Hierarchy is indicated in the document using heading level paragraph styles HeadingN for paragraphs containing the titles of the Work Items. After export, you can generate a Table of Contents in MS Word, and it will display the same hierarchy as the table in the Tree display mode.

Before exporting items when viewing them using the Tree presentation option, you should specify the sorting of the Work Items, including child levels. Remember that you can customize the fields that appear in the table using the Customize Table option on the Refresh menu of the Work Items Table toolbar. If the existing fields are not sufficient for the sort order you want, you can add one or more Custom Fields and include them in the sort.

The Tree presentation of Work Items in the Table view may be exported only to these formats:

  • csv: Comma separated values

  • doc: Microsoft Word template

  • xlsx: Microsoft Excel

Exporting the Matrix View

There are 2 report options for exporting data from the Matrix view:

The following sections describe each option

Excel Table

You can export data from the Matrix view as a table to MS Excel (normal document, not Excel Round-trip). The export format is XML for MS Excel 2003. Exported are rows and columns visible in the page, and only links with roles visible in the page are exported. A maximum of 256 columns (255 column Work Items or Revisions) can be exported due to limitations of Excel. If the number of columns found is greater, you will see a massage and you should formulate a query to return a smaller column count.

When the Matrix view is current, the Export item appears on the Operations menu. Once you have used the search controls to obtain the data you want to export, use this menu command to launch the Export process. In the Export dialog, choose xls: Excel Table in the Format field. You have the following additional options:

  • Export link roles - whether or not to display the link role in the Excel cells. yes makes sense only if links of all roles are displayed. When links of all roles are exported, but role names are not exported, then only one link from all links between two Work Items in the same direction is displayed.

  • Export Work Item titles - If checked, Work Item titles are exported. Otherwise, only Work Item IDs are exported.

  • Export Revision messages (Revision matrix only) - If checked, both revision names and messages are exported. Otherwise, only revision names are exported.

The following notes apply to the exported data in Excel:

  • The exported document contains the export date, the queries used to obtain row and column Work Items or Revisions, and in the cases when one particular link role is selected, the role of the link.

  • Headers of rows and columns are hyperlinks to the Work Item or revision details in the Polarion portal.

  • Links are indicated by an arrow like character (possibly with a role name next to it).

  • Suspect links are marked by the ? character next to the link-indicator character.

  • Direction of a link between a Work Item and a Revision is always from the Revision to the Work Item, regardless of whether the link is created via a revision message or directly in a Work Item.

Excel Traceability Report

You can export traceability data from the Matrix view to MS Excel. The export format is XML for MS Excel 2003. Traceability report has two columns: the first represents rows of the matrix, the second contains list of all linked Work Items or Revisions that are present in a column of the matrix. Only links with the role selected in the control are exported.

Export is possible even when portal does not display the matrix due to a very large number of items retrieved by the search query. A message in the portal informs you if this is the case, and the Link Role combo box is filled with link roles defined for current project or for the global level.

When the Matrix view is current, the Export item appears on the Operations menu. Once you have used the search controls to obtain the data you want to export, use this menu command to launch the Export process. In the Export dialog, choose the xls: Excel traceability report in the Format field. The following additional options are presented:

  • Export link roles (Work Item matrix only): - If checked, link role is displayed in the report cells. Checking this option makes sense only if links of all roles are displayed. When links of all roles are exported, but role names are not exported, then only one link from all links between two Work Items in the same direction is displayed.

  • Export Work Item titles - If checked, Work Item titles are exported. Otherwise, only Work Item IDs are exported.

  • Export Revision messages (Revision matrix only) - If checked, revision commit messages are exported, otherwise only the revision names are exported. If the matrix does not retrieve revisions, this option is ignored.)

  • Include direct links (Work Item matrix only) - If checked, items linked by direct link are exported when the search parameters retrieve only Work Items. The option has no effect if the matrix retrieves revisions.

  • Include backlinks (Work Item matrix only) - If checked, backlinked items will also be exported when the search parameters retrieve only Work Items. The option has no effect if the matrix retrieves revisions.

Exporting to XML and Transformed Formats

You can export Work Items from your projects to an XML structure used as input for transformation to various file formats by means of XSL templates stored in the Polarion system. The procedure is the same as for export to other formats: you run some query to retrieve a set of Work Items for export, and invoke the Export Work Items dialog from the Operations menu in any Work Item view where Export is present on that menu.

In the Export Work Items dialog's Format field, select any option that begins with or contains xml or XML. If multiple templates are present, select the desired template in the Template field and click OK. Either save the exported XML document to your local file system, or opt to open it in whatever application is registered for the file format created by the selected template.

The Export Work Items dialog provides the following XML export options in the Format field. Some both export the selected Work Items to XML, and also invoke XSL transformation processing to transform the output to different file formats. The options are as follows:

  • html: XML Export: Content is exported to XML and transformed via XSL processor to HTML

  • pdf: XML-FO Export: Content is exported to XML and transformed via XSL and FO processors to PDF

  • rtf: XML-FO Export: Content is exported to XML and transformed via XSL and FO processor to RTF

  • txt: XML Export: Content is exported to XML and transformed via XSL processor to plain ASCII text

  • xml: XML Export: export to XML transformed via XSL processor to a different (or the same) XML structure

The above options are present when the Work Items table is in the "Flat" (table) presentation mode. If the Work Items table ins in "Tree" (hierarchical) presentation mode, a subset of these options is presented with only those options that are supported for the Tree mode.

Notes

Custom XSL Templates: You can develop custom XSL templates that transform exported Work Items according to your own requirements. For information, see Administrator's Guide: Advanced Administration: Customizing XML Export, and Administration Reference: XML Export Schema.

PDF and Non-English Characters: In order for PDF to be exported properly when Work Items contain non-English characters, the *-fo.xsl template that is used for the export (.polarion/tracker/export_templates) must explicitly name the font-family for all text in the resulting FO file. This is most easily done by setting the font-family attribute of the fo:root element. For example: font-family="Arial" (used in the default Sample-fo.xsl).

If this font-family specification is not provided, FOP replaces non-English characters with # in the resulting PDF output.

Exporting for Excel Round-trip

The export option xlsx: Microsoft Excel exports Work Items in a "round-trip" format for Microsoft Excel, enabling an external user to edit Work Item content in Excel. A Polarion user can then import the edited Excel sheet back to Polarion, updating the Work Item content from the externally edited Excel document, and/or creating new Work Items defined externally in the exported Excel document. If Work Items are exported from a Document, it is possible to allow changing of the Document structure externally in the exported Excel worksheet.

For information, see User Guide: Work Items Topic: Using Excel Round-trip.

Exporting to Microsoft Project

Polarion also supports export of Work Items to Microsoft Project enabling sharing of the current Polarion project plan with users of Microsoft Project. For information, please see the User Guide Appendix: Exporting Work Items to Microsoft Project.