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.

You must have Save Work Item permission. To set this permission, open the Manage Project Area for your project, and select Permissions. Select Show Roles In the Roles field, select the role you want to assign permissions to, and in the Permissions field, select Work Items > Save Work Item > Import a work item, and click Save.

Import csv file web

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.


  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 Data tab, 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)
    • If you want to override any permissions requirements or preconditions for saving work items, click Overrule any permissions or preconditions for saving work items (Requires JazzAdmin privileges). You need to have JazzAdmin privileges to override saving work item restrictions. When the option is unchecked, the save operation enforces preconditions like required attributes and prevents the save if preconditions are not satisfied.
    • 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
    Important: Make sure that the file you are importing is encoded in UTF-8. If you are working with data in an external application, make sure that the application supports UTF-8.
  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:
    Once the import is finished successfully, you can see the finished import message:
    successful import
    Important: When you import work items using the .CVS file, the import ignores any permissions restrictions that have been set in the project settings. For example, if the user importing the work items does not have permission to trigger a workflow action (set in the project area configuration), then the updates to the work item fields from the .CSV field are applied nonetheless.
    Click View results to see the work items that you have imported:
    Import results

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki