Import or update work items in bulk by using CSV files in Azure Boards

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

You can import and export work items in bulk using a CSV formatted file. While you can continue to use Excel for bulk import and updates, you can use the native import/export feature that doesn't require Excel. To learn more about using Excel, see Bulk add or modify work items with Excel.

You can export of work items in bulk using a CSV formatted file. While you continue to use Excel for bulk import and updates, you can use the native export feature from Queries that doesn't require Excel. To learn more about using Excel, see Bulk add or modify work items with Excel.

Note

The export feature is available with Azure DevOps Server 2019 Update 1 and later versions. The import feature is available with Azure DevOps Server 2020 and Azure DevOps Services.

Import new work items

All work items you import are created in a new state. This rule means that you can't specify field values that don't meet the field rules for the new state. For example, when you create a new user story with the Agile process, the State=New and the Reason=New. No other values can be specified.

  1. Create a local import.csv file and open it in Visual Studio Code or Excel.

  2. The file must contain the Work Item Type and the Title fields. You can include other fields as needed. For a list of default fields, see Work item field index.

    In the following example, we include the Priority field.

    Work Item Type,Title,Priority
    Issue,Fix issues with code,1
    Issue,Merge testing modules,3
    Issue,Open private preview for select customers,2
    Issue,Enable feature for customer champs,2
    Issue,Remove old test code,2
    
  3. From the web portal for your project, open Boards>Queries and choose the Import Work Items option.

    Boards>Queries, Import Work Items

  4. Select your CSV file and then choose Import.

    Import Work Items Button Image

  5. The import process loads the imported work items into the queries view in an unsaved state. No IDs are assigned. Verify the results are what you want. Then, choose Save Items to save the work items.

    Save imported work items

    Note

    Make sure you don't assign IDs to new work items that you're adding. You'll receive an error message similar to the following if you do so.

    Error message of work item ID.

  6. The system highlights those work items with data issues. Resolve the data issues before you save the work items. In this example, an invalid value has been entered into the Priority field. Fix the data by opening the work item directly. Instead, use bulk edit to fix several work items with the same issue.

    Fix work items with data issues.

Tip

You can add parent-child links between work items you import by indenting the title columns as shown in the example later in this article, Can I import a CSV file that have parent-child links?. However, you can't specify any other link types when importing or updating work items.

Update existing work items

  1. To update work items, create a query that contains all the columns you want to export and possibly edit. Save your query and select Export to CSV to save the data.csv file to your local machine.

    Export work items, CSV

    The exported file should look similar to the following syntax:

     ID,Work Item Type,State,Assigned To,Title,Tags
     "1043","Issue","To Do",,"Fix issues with code",
     "1044","Issue","To Do",,"Merge testing modules",
     "1045","Issue","To Do",,"Open private preview for select customers",
     "1046","Issue","To Do",,"Enable feature for customer champs",
     "1047","Issue","To Do",,"Remove old test code",
    
  2. Make the edits to your work items. Your CSV file must contain the ID, Work Item Type, Title, and State fields. Any other fields you want to include are optional.

    Note

    When importing identity fields, the name and email must be entered in the following format "Display Name <email>". For example, to assign work to Jamal Hartnett, specify "Jamal Hartnett <fabrikamfiber4@hotmail.com>". If you specify a value that isn't recognized as a valid user to the system, you may encounter problems with the import.

    In the following example, we change several values on existing working items.

     ID,Work Item Type,State,Assigned To,Title,Tags
     "1043","Issue","To Do","Jamal Hartnett <fabrikamfiber4@hotmail.com>","Fix issues with code",architecture
     "1044","Issue","To Do","Jamal Hartnett <fabrikamfiber4@hotmail.com>","Merge testing modules",testing
     "1045","Issue","To Do","Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>","Open private preview for select customers","customer focus"
     "1046","Issue","To Do","Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>","Enable feature for customer champs","customer focus"
     "1047","Issue","To Do","Christie Church <fabrikamfiber1@hotmail.com>","Remove old test code",architecture
    
  3. Save the file and import (see steps 4-6 from the previous import section.)

  4. The results list with work items that contain value changes appear highlighted in bold. Choose Save Items to apply the changes.

    Import Work Items Save Items.

  5. Work items with data issues are highlighted in red and need to be resolved before you can save them. In this example, an invalid value appears in the Assigned To field. Fix the data by opening the work item directly. Instead, you can use bulk edit if you have many work items with the same issue.

    Invalid value appears in the Assigned To field.

Export list as a CSV file

From any query, you can export a list of work items as a comma-delimited list. Open the query, choose the actions icon, and choose Export to CSV.

Note

Requires Azure DevOps Server 2019 Update 1 or later version.

Export a query as CSV

Export and import work items to a different project

You can use this feature to export work items from one project and import them to another project. However, before importing them to another project, you must remove the work item ID. You come across an error if you attempt to import new work items to a project with an ID specified.

Import or update rich-text fields

You can update or import rich-text fields such as the Description or Acceptance Criteria fields. Rich-text fields are HTML formatted fields. Replace lines ending in CRLF by surrounding sentences with <p>... </p>.

For example, you can import the following work item, which includes three lines of text in the Description field.

Work Item Type,Title,Description
"Product Backlog Item","Hello World Web Site - 8","<p><strong>&nbsp;You can include bold text</strong></p><p><em>&nbsp;And italic text</em></p><p><u>&nbsp;Underline text</u></p>"

Q & A

Can I import new items and update existing items in the same CSV file?

Absolutely! Leave the ID field empty for any new work items. In the following example, the last entry for an Epic doesn't specify an ID.

ID,Work Item Type,Title,Assigned To,State,Priority,Tags
"16504","Issue","Fix issues with code",,"To Do","1",
"16505","Issue","Merge testing modules",,"To Do","3",
"16506","Issue","Open private preview for select customers",,"To Do","2",
"16507","Issue","Enable feature for customer champs",,"To Do","2",
"16508","Issue","Remove old test code",,"To Do","2",
,"Epic","Track Telementry for data imports",,"To Do","2",

Yes, you can add child work items by indenting title columns. The following example adds three child Issues under the already defined Epic.

ID,Work Item Type,Title 1,Title 2,Assigned To,State,Priority,Tags
"165","Epic","Track Telementry for data imports",,,"To Do","2",
,"Issue",,"Fix issues with code",,"To Do","1",
,"Issue",,"Open private preview for select customers",,"To Do","2",
,"Issue",,"Enable feature for customer champs",,"To Do","2",

Here's a better visual in Excel.

Excel view image

How do I know if my imported file has errors?

Any problems with the formatting of your CSV file appear in the Results page of the import view. You can't import the work items until the formatting and syntax is correct.

CSV Error image

The work items' results always lists the data errors found for individual work items. Fix each error either from the web portal, or in the CSV file and import again.