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.

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:
   

   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.
   
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.)

   
4. Alternatively, click MAPPING to use your own 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.
   
   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:

   

   Click View results to see the work items that you have imported: