Importing work items from a CSV file in the web client

Sometimes you want to import a number of work item definitions from a spreadsheet or text file into your collaboration tool. The work item importer feature allows you to import a group of work items from a file into your repositiory.

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.

Within the project area where you import the work items, you must be assigned to a role that has permission to create these objects.

About this task

The work item importer feature work item importer allows you to create a number of work items from a spreadsheet or text file. You can import from
  • An Excel file
  • A CSV file

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. First, you must create a CSV file that includes the work items you want to import. The first row of the file must list the attribute names. They are mapped to work item attributes. Here is an example of a CSV file created in excel:
    CSV file sample
    Here is an example of a plain text, comma-separated file:
    Type,Status,Priority,Severity,Summary,Description,Owned by,Planned for,Tags,Due Date
Task,New,Medium,Normal,"Create and publish the release schedule","Create and publish the release schedule to be used by all team members","Frank Lee",1.1 M2,planning,Jan 10, 2016, 4:00 PM
Task,New,Medium,Normal,"Review release schedule","Review releases chedule for approval","Ernest Lee",1.1 M2,planning,Jan 20, 2016, 4:00 PM
  2. On your project page, click CREATE > Import from CSV File.
    import work items
  3. In the Import work items from CSV files page, in the Datatab, click Browse. Note that your project must be in the form of an excel or CSV format. Here are your configuration options:
    • In the Values in this file are separated by: field, select:
      1. Comma
      2. Tab
      3. Other (and specify)
    • In the For each entry in the selected CSV file: field, select:
      1. Create a new work item
      2. Update existing work item
        1. Create a new work item if no match found
        2. Replace existing links with new imported values. (In order to find work items to update, a column with the identifier "Id" must exist in the selected CSV file.)
    import options
  4. Alternatively, click MAPPING to use your own mapping file:
    Custom mapping file
    Click Browse to locate your mapping file, and then click IMPORT.
  5. You can customize your mapping file on this page as well. Click Define custom mapping, and the attributes from you <mapping>.xml file appear. You can now customize the values in your file to create a customized mapping file. Select a work item attribute, and you can modify the value. For example, Owned by = <name>, Status = <value> and so forth.
    Note: If you do not want to import invalid work items, for example, work items that do not include a Filed against attribute, click Don't save invalid work items. If, however, you want to import incomplete or invalid work items, clear Don't save invalid work items.
  6. To import your work items, click IMPORT. If you want to preview the results before doing the final import, click Preview.
    Import preview
    The prospective work items are listed and you can ensure that the results are what you expect. If not, click CANCEL, and update mapping file. After you click IMPORT, you can see the import message:
    importing
    Once the import is finished successfully, you can see the finished import message:
    successful import
    Click View results to see the work items that you have imported:
    Import results

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