Skip to main content
System StatusContact Support Agility Community

Importing Stories, Defects, and Other Data from Excel

This feature is available in Catalyst, Enterprise, and Ultimate editions.



This article provides instructions on how to bulk import data into Agility from a Microsoft® Excel spreadsheet.

Downloading the Import Template

To ensure that your data is properly formatted, start with one of our import templates. These templates are pre-configured with the correct column names for the the most commonly used attributes.

  1. On the navigation bar at the top, click Product Import.

  2. Click on the Download Basic Excel Template or Download Advanced Excel Template button, and select one of the following templates:

    • Basic Excel Template
      Use this template to import common assets, such as backlog items, tasks, defects, tests, etc.

    • Advanced Excel Template
      Use this template to import more complex system assets, such as projects, iteration schedules, change sets, requests, etc.

  3. ​Save the file to your computer.

    • The import file must be saved in a Microsoft Excel 97-2003 (or higher) workbook with the .xls file extension.

Populating the Import Template

Although the import templates include the default column structure and system names for many common assets and attributes, you can add data beyond what is available in the templates by following these specifications.

The import templates contain helpful comments in the column header fields. To see them, hover your mouse over any cell with a red comment indicator in the corner. The required fields are highlighted in red text.

Note: Excel installation is required to be able to use the Excel Import process. 

Formatting the Excel Worksheet

  • First Column Title
    The first column in each worksheet should be titled "AssetType" and should contain the system name for the asset type. See Import File Column Titles by Asset Type, for a partial list of asset types. 

  • Remaining Column Titles
    The remaining columns must contain asset attributes and must be titled with the system name for the attribute.  A column and value must be included for all required attributes. See Import File Column Titles by Asset Type, for a partial list of column titles.  For a complete list of attributes (and including whether or not they are required), run a meta query. Running a meta query is an additional way of discovering attributes and their system names, including custom fields.

  • Column Cells
    The cells in each column should contain the corresponding attribute value for the attribute specified in the title.

    • Line Breaks Within a Cell
      The Agility import tool treats Excel data as HTML and does not recognize line breaks. As a result, any line breaks in your source file are "lost" during the import process. To retain you line breaks (<CR><LF>), replace them in your spreadsheet with "<br>" tags before you import the file.

  • Unique Values
    References to values in the system must be unique. If referencing a non-unique project, you can make it unique by pre-pending the parent project title. For example, the original value, "Release 1.0", could be uniquely referenced as, "Project ABC\Release 1.0". Sprint references must also be unique. You can also use a project identifier to make them unique.

Worksheets (or Tabs)

  • Each worksheet in the workbook should correspond to a separate asset. 

  • Worksheets are processed in alphabetical order by worksheet name.

  • You can reference assets in other worksheets in the same file. For example, to create a project and stories within the project, add the project in the first worksheet, and then add the stories in the project in the second worksheet.

Additional Attributes

  • Entering Multiple Values for an attribute
    To enter multiple values (e.g., multiple owners) in a cell, insert a duplicate column with the same title. To add two owners to a task, for example, add a second column called "Owners" to the "Task" worksheet in the template.

  • Adding Owners
    Use any of these attributes to specify an owner or owners for workitems.  Enter one value per column.  Values are matched according to the hierarchy below.

    1. Name

    2. Short Name

    3. Username

    4. Email

  • Adding fields not in the template
    You can add fields that are not in the template by adding a new column for each field you want to add. The column title should be the same as the system name for the field.  You can run a meta query to discover the system name for a field or ask your system administrator to do so.

  • Adding Custom Fields
    You can also add custom fields to the template by adding a new column for each field you want to add. Ask your system administrator to look up the corresponding Agility system name for each custom field you would like to add. The column name should be the same as the system name for the custom field.  You can also run a meta query to discover the system name for a custom field.

  • Adding Checkbox values
    Enter "TRUE" for checked or "FALSE" for not checked as the value.

  • Deleting Columns
    To remove the columns you don't want to import, simply delete them from the worksheet.  You can also leave empty columns in the worksheet with no adverse effects.

Import Limits

  • To maintain data integrity, each import file is processed in a single transaction. For this reason, we recommend limiting your import to 500 items per import file.

Importing Your Backlog from the Excel Template

  1. On the navigation bar at the top, click Product > Import.

  2. Click the Upload A Completed Excel Template File button

  3. Click Choose File to select your import file.

  4. Click the Import button.

    • The data is validated to ensure that the import file does not contain errors. If so, you will be prompted to fix the errors and retry the import. See Troubleshooting Excel File Import Errors for solutions to common errors.

  5. If the import was successful, navigate to your backlog to review and fill in any missing information.