Importing work items from a CSV file

You can import work items from a comma-separated values (CSV) file into a project area. 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

  1. Click File > Import. In the Import window, click Team > Work Items from CSV. Click Next.
  2. 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.
  3. Select the project area in which to create or update the work items based on the contents of the CSV file.
  4. Select to create or update work items. You can also select to create work items when there is no match.

    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.

    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.
  5. 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.
  6. 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.
      • If necessary, when the import process creates new work items, it can create Jazz user accounts to populate the user ID fields. For the import process to create user accounts, you must have JazzAdmins repository group permissions.
        Note: If you import into a repository that uses LDAP, import the users from LDAP before you import work items.
      • If the user ID in the imported CSV file is either "Unassigned" or a case-insensitive variant of this spelling, for example, "unassigned" or "UnAssigneD", the target user ID is mapped to "Unassigned".
      • If the user ID in the imported CSV file is an empty string ("") and the update is to an existing work item, the target user ID is not updated.
      • If the user ID in the imported CSV file is an empty string ("") and a new work item is created, the target user ID is mapped to "Unassigned".
    • 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.

  7. Import the work items by clicking Finish.

video icon Watch videos

CLM playlist
Jazz.net channel
User Education channel

learn icon Learn more

CLM learning circle
Agile learning circle
Learning circles

ask icon Ask questions

Jazz.net forum
developerWorks forums

support icon Get support

Support Portal
Deployment wiki
Support blog