Exporting work items

You can export data from work items to an HTML or comma-separated values (CSV) file. You define the scope of the export operation by specifying a query. After you export work items to a CSV file, you can import them into another project area.

Before you begin

Important: The following data is not preserved when you use the Export Work Items wizard to export item data to a CSV file:

Work item history
Approval history
Attachments
All Open Services for Lifecycle Collaboration (OSLC) Uniform Resource Identifier (URI) reference links. For example, Contributes To, Tracks, Affects Plan Item, Affected By Defect, Related Change Request, Tracks Requirement. As a result, while you can use the Import Work Items wizard to import work items in CSV files that include URI reference links, the import operation does not automatically create the backlinks in the referenced items.
In contrast, standard reference links, such as Parent, Children, Duplicated By, and Depends On, are preserved when you export data to a CSV file.
Tip: The list of OSLC link types varies depending on project association definitions and the OSLC integrations that are configured. For a list of OSLC link types for the Change and Configuration Management (CCM), Quality Management (QM), and Requirements Management (RM) applications, see the following topics:
- For the CCM application:
  - Linking between artifacts in the Eclipse client
  - Linking between artifacts in the web client
- For the QM application:
  - Linking work items to test artifacts in the Eclipse client
  - Linking work items to test artifacts in the web client
- For the RM application:
  - Linking work items to requirements in the Eclipse client
  - Linking work items to requirements in the web client

About this task

In the Export Work Items wizard, you select the work item attributes, including custom attributes and link types, to include as columns in the CSV file.

Procedure

Click File > Export.
Alternatively, in the Team Artifacts view, you can right-click a query and select Export Work Items.
In the Export wizard, expand Team and select Work Items. Click Next.
In the Query field, click Browse and locate the query that returns the work items to export.
Important: By default, the wizard uses the work item attributes that are specified on the query editor Column Display page in the output file. If you intend to use the Import wizard to create or update work items from the output file, ensure that the Column Display page selects the attributes that you want to map to new work items during the import operation.
For the output format, select either HTML File (.html) or Spreadsheet (.csv).
Remember: By default, the values in the exported CSV file are tab-separated, not comma-separated. When you use the work item importer, if you use a CSV file with this format, remember to specify that the values are separated by tabs.
In the Destination field, click Browse to go to the directory in which to store the file that is created by the export operation. Click Next.
Select the work item attributes to display as column headings in the output. By default, the columns that are specified on the query editor Column Display page are used. You can modify the default selections to customize the resulting output.
Important: If you intend to use the Import wizard to update existing work items, be sure to include the ID attribute in the exported CVS file and set its Show column setting to use the internal representation (Internal Value). The Import wizard uses the IDs to find the work items to update.
- In the Show column setting, specify whether to use the internal (Internal Value) or external (Label) representation of each attribute value. Change the Show column value by clicking the value and selecting the option from the menu that opens. The external representation is how the value is displayed in the work item editor. The internal representation is a value that can be processed by the spreadsheet. This value might be less readable for users. For example, the external value of the Estimate attribute is in hours or days. The internal representation is in milliseconds.
  Important: If you intend to export, and then import the work items into another project area, to provide accurate mapping on import, it is a best practice to use the internal (Internal Value) representation of the attributes for the export. At a minimum, use the internal representation for the following attributes:
  - Planned For
  - Comments
  - URI-based links
  - Subscribers
  - Contributors list
  - Project Area
  - Project Area list
  - Team Area
  - Team Area list
  - Process Area
  - Process Area list
  - Work Item
  - Work Item list
- To add columns, click Add Columns; to remove columns, click Remove.
  In the Add Columns window, you can select Show custom to see available custom attributes, and select Show built-in to see the predefined attributes. You can also select Show links to see available links types that you can choose to include in the export. Link types indicate relationships that work items have with other work items. For example: Parent, Child, Duplicated By, Depends On.
- To adjust the order of columns in the output, click Move Up and Move Down.
Click Finish to generate the report.

Results

If you did not clear the Open automatically after download option, the exported file opens. If the file does not open, to open it, go to the location that you specified in the Destination field.

When you export work items by using the Export Work Items wizard, the first row of the CSV file contains attribute names. The Import wizard uses this first row to map the column values to attributes.

What to do next

If you want to import work items into a project area by using the generated CSV file, see Importing work items from a .CSV file in the Eclipse client.