Import objects via Excel overview

You can use the Excel spreadsheet to import objects from other applications to Jira Align to work with the application more effectively and save time.

• Prepare the import file
• Update the import file

Important notes:

• The best practice is to start with the template attachment provided at the end of this article. If your Excel spreadsheet is formatted incorrectly, the import may fail. For Mac OS users, see the Prepare the import file section for information on how to format the template.
• Do not change the column headers in the import template. The header is the name of the item in the data store. Note that the names for Jira Align objects in the column headers have default terminology setup. If you are using custom platform terminology, the names of the objects you are about to fill in may be different from what you are used to.
• If you have troubles downloading the import template, disable or uninstall the Office Online extension in your browser.
• Your Jira Align Administrator must turn on a specific permission toggle for each system role that needs the ability to import work items. Administrators must turn on the following toggle switch: Administration > Roles > [select role] > ADDITIONAL OPTIONS > Import Stories/Tasks/Features.
• Objective imports are currently disabled while we work on some enhancements to objectives and related functionality. 

Prepare the import file

Tips to ensure good performance during the import:

• The data in each column is text-based, so it is important to type the exact name of the object.
• Duplicated rows are highlighted during the validation. If your import includes a duplicated name, the row is not imported.
• The fields on the template are the only fields that can be updated by import. Other fields, such as custom fields, must be manually updated on the individual work item or updated via API.
• Tabs are processed in order within the spreadsheet, so within the Excel file you can reference a work item that was created in an earlier tab. For example, you can assign a task to a story that was created in a preceding tab.
• Limit your import to 1000 items for one import file.
• The current size limit is 4 MB per file, but you can upload multiple files. So, if a file is too big, it can be split into pieces and imported that way.
• Pay attention to these Excel maximum limits for good performance during the import process. You can find more information on Excel specifications and limits here.

  • Column width – 255 characters

  • Total number of characters that a cell can contain – 32,767 characters

  • Maximum number of line feeds per cell – 253

• Your work items’ titles should not exceed the following character length:
  • For themes, epics, capabilities, features, objectives, defects, tasks, and test cases - 250 characters
  • For stories - 300 characters
• For story acceptance criteria, use two tilde signs (~) with a number or ID between them before each acceptance criterion to differentiate between them. For example:

~1~ Acceptance criterion #1.

~2~ Acceptance criterion #2.

~3~ Acceptance criterion #3.

Note: Acceptance criteria fields for epics and features are read-only, and can't be imported. For capabilities, the acceptance criteria field is not included in the import template file, and can't be imported. 

• Upload multiple entry values using comma separation in a cell. This works for:
• the Additional Programs column for epics, capabilities, and features.
• the Program Increments, Customers, Approvers, Sponsors, Personas Affected, and Forecast Years (maximum 10 values) columns on the Epics tab.
• the Release Vehicle, Affected Countries, Customers, Test Categories, Forecast Years, and Tags columns on the Features tab.
• the Release Vehicle column on the Stories tab.
• When you import an item that is in the portfolio with enabled association of process steps with item states, the process steps have priority over states and the state is set based on the process step. If you do not set the process step for an item during import, it is set based on the process steps mapped to states.
• Invalid lookup values result in a null entry. If you put a not valid point total in the story points column, the total will be null in the database.
• Do not change the read-only columns (marked as R/O) in the exported file. Your changes will not be uploaded back.
• You can upload the file with any non-required fields removed, only those fields which are present in the file will be updated. If the spreadsheet lacks required fields (those which are marked as bold), the entities will not be imported.
• Always check the validation for each object before you import the file.
• Ensure that all parent objects and programs for imported work items already exist within Jira Align.
• For work items for which sprint and PI associations will be imported, ensure that the sprint belongs to the specified PI.
• Epic, capability, and feature guidance:

• For Mac OS users only, when you save the file to import your items back to the system, save the file as a .xml (Excel 2004 XML spreadsheet) file. Then, locate the updated file in your file directory and manually change its extension to .xls. This will format the file so that Jira Align can import it.
• For Windows users, the file type should be an Excel 2003 XML spreadsheet and the extension should be .xls.

Update the import file

You can update items by importing them back to the system. If trying to update existing items, we do recommend exporting those items, and then copying that data into the import file.

The mapping is done based on an ID and/or name:

• If you enter an ID of an item, the item gets updated.
• If the item with the name already exists and the ID was not provided, this item is still updated.
• If you provide an invalid ID, the item will not upload.
• When you provide an ID from one item and existing name from another, it will not be updated.
• Blank cells do not override the values. 

See also

10X: Import Objects Via Excel

Import template file: