You can import work items from a comma-separated values (CSV) file into a project area in
the Eclipse client. You can use the Import Work Items wizard to create work items or update work
items.
Before you begin
Before you can import work items into a project area from
a CSV file, you must generate the file, making sure to include all
the attributes and links that you want to import. You can use the
Export Work Items wizard in the Eclipse client to export data from
work items to a CSV file. For more information, see
Exporting work items.
You
can also use the ClearQuest® Import
wizard to export data from ClearQuest records
to a CSV file. For more information, see Migrating Rational ClearQuest records to work items.
You
must have at least a Contributor Client Access License (CAL). To create
categories, iterations, or releases when you create work items, you
also need a Developer CAL. Within the project area where you import
the work items, you must be assigned to a role that has permission
to create these objects. If the import process creates Jazz user accounts to populate work item fields
such as Creator and Owner, you must have JazzAdmins repository group
permissions.
About this task
If the first row of the CSV file contains attribute
names, the Import Work Items wizard maps the columns in the CSV file
to the work item attributes. If you did not use the Export Work Items
wizard to create the CSV file, make sure that the first row contains
the attribute names. Otherwise, the Import Work Items wizard does
not map columns to attributes.
The Import Work Items wizard
uses an XML mapping file to map attributes from the CSV file to the
work items that it creates or updates. The wizard provides a default
mapping file, which you can modify to customize the mapping. You can
also generate a mapping file from the CSV file that you provide.
Perform
the initial import operation in a test repository. After you are confident
that the mapping is configured correctly, it is a good idea to back
up your production repository. Then, start the import operation.
Procedure
- In the Eclipse client, click . In the Import window, click . Click Next.
- Click Browse and select the CSV
file to import. Select to separate the values in the CSV file by tabs,
commas, or something else. If you use a separator other than tabs
or commas, click Other and enter the separator
in the adjacent field.
- Select the project area in which to create or update the
work items based on the contents of the CSV file.
- Select to create or update work items.
- To create work items, select Create a new Work Item.
- To update existing work items, select Update matched Work Item. To be
able to update existing work items, the CSV file must contain a column for the work item ID (usually
Id). The Import Work Items wizard uses the IDs to find matching work items.
To
create work items for records that do not have matching existing work items, select
Create a new work item for unmatched entry.
To update links in existing
work items with the links in the records in the CSV file, select Replace existing links
with newly imported values.
Note: For links between work items to be created, all of the linked records must be included in the
imported CSV file. For example, if Record A is a duplicate of Record B, but Record B is not
imported, the duplicate link is not created. Instead, a custom attribute that contains the duplicate
information is created. If you update existing work items, be sure to import the full set of records
that you imported originally.
- To save the default mapping file, click Save
Default As. The default mapping file contains entries
for all attributes in the project area that you select.
- To generate a mapping file from the CSV file, click Compute
From Data. The generated mapping file contains entries
for all of the attributes in the CSV file. Edit the mapping file to
customize attribute mapping. The generated mapping file
contains mapping information for attributes and attribute types. The sourceID identifies
the element name in the CSV file. The targetID identifies
the work item attribute ID that the values should be mapped to in
the target project area. Within each attribute mapping section, the value tags
map each of the attribute values. For example,
<attribute sourceId="Severity" targetId="com.ibm.team.workitem.attribute.severity"
<value sourceId="Minor" targetId="2"/>
<value sourceId="Normal" targetId="3"/>
<value sourceId="Major" targetId="4"/>
</attribute
Customize the mappings as follows:
- State/Resolution: If the target project
area uses an unsupported process (not one of the predefined process
templates), look up the state and resolution IDs of the workflow that
is used for defects in the project area editor's Process
Configuration Source tab. Search for com.ibm.team.workitem.configuration.workflow.
For historical reasons, state IDs of the form s1 and
resolution IDs of the form r3 need to be added
to the mapping file without their respective s and r prefixes.
- Planned For: The values of the Planned
For attribute come from the project area iterations. Look
up these identifiers in the properties dialogs of timelines and iterations
on the project area editor's Overview tab.
Replace each target ID with a path by using forward slashes as separators.
Start with a slash followed by the timeline's ID as the first segment,
followed by segments of iteration IDs. For example, /main_dev/milestone_3/stable.
Tip: If a source value is not mapped to a target value, the
import operation creates new iterations or timelines for these source
values. To prevent the import operation from creating these iterations
and timelines, you can complete the operation while logged on as a
user who does not have the Modify the iteration structure permission
in the target project area. Also, this user must not have JazzAdmins
repository group permissions.
- Release: The attribute type's ID is deliverable.
A value mapping's target ID is a release name, which can be found
on the Releases tab of the project area editor.
If necessary, the import operation creates releases.
- Contributor: The target ID is a Rational Team Concert™ user
ID.
The following mapping rules apply when you use the Import Work
Items wizard.
- Priority/Severity: If the target project
area uses an unsupported process, look up the target IDs from the
Priority and Severity enumerations on the project area editor's Process
Configuration Source page (search for com.ibm.team.workitem.configuration.enumerations).
A value mapping can use * as the
source ID to match all values that are not mapped explicitly. Values
without any mapping are copied to the target work item, and if necessary,
repository items are created. By default, the import operation does
not create workflow states and resolutions and enumeration literals;
to create these items, you must customize the target project area's
process configuration. If a source value is mapped to an empty target
value, the import operation uses the work item attribute's default
value.
To have the wizard use the customized mapping file, click Use
custom data mapping; then, click Browse and
select the file.
- Import the work items by clicking Finish.
