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
- Work item history
- Approval history
- 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:
- For the QM application:
- For the RM application:
About this task
- Click .Alternatively, in the Team Artifacts view, you can right-click a query and select Export Work Items. To export work items in a query, you must be assigned a role that has permission to export a query. To configure permissions, open the project area and click the Process Configuration tab. Expand Team Configuration and click Permissions. In the Permitted actions pane, expand Work Items and select Export Query (server). Click Save.Restriction: In a version earlier than 7.0.3, the lack of Export permission is ignored. You can export query result even if you don't have the permission.
- 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
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
- URI-based links
- 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
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.
- 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.
- Click Finish to generate the report.
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.