How to import CSV files into JIRA

Posted by:


It is sometimes quicker to import stories from a spreadsheet, especially when an existing project is migrated to JIRA. JIRA allows importing from a number of sources, one of which is from a Comma Separated Values (CSV) file. This is arguably one of the more useful import options. This tutorial discusses how to import CSV files into JIRA.

Other options include a direct import from one of the following applications:

[list_icon color=”blue” type=”icon_arrow”]
  • FogBugz
  • Pivotal Tracker
  • Trac

Import from a Json file is also an option.

Preparing to import CSV files into JIRA

The online documentation (see link below) is fairly comprehensive, but some important aspects are not highlighted, for instance, the Reporter field is required. Also add as many fields as possible when importing a large number of stories, otherwise stories would have to be modified manually after the import if incorrect default values are assigned. Some of the more obvious fields to include:

[list_icon color=”blue” type=”icon_arrow”]
  • Summary (also a required field)
  • Reporter
  • Assignee (if known at the time of doing the import)
  • Priority
  • Issue Type
  • Labels
  • Status
  • Description

In addition to being ‘well-formed’, CSV files have the following requirements.

[list_icon color=”blue” type=”icon_arrow”]
  • Each CSV file must possess a heading row with a Summary column.
  • The header row should avoid containing any punctuation (apart from the commas separating each column) or the importer may not work correctly.
  • The header row must contain a column for ‘Summary’ data.
  • The Reporter column is also mandatory.

For example, this is valid:

Summary, Assignee, Reporter, Issue Type, Description, Priority
“Test issue”, admin, admin, 1, ,

 Also note the following:

[list_icon color=”blue” type=”icon_arrow”]
  • Use double-quote marks (“) in your CSV file to capture data that spans multiple lines.
  • Use double-quote marks (“) around a section of text to treat any special characters in that section literally.

You can import multiple values into a JIRA field that accepts multiple values (e.g. Fix (for) Version, Affects Version, Component, Labels). To do this, your CSV file must specify the same column name for each value you wish to aggregate into the mapped JIRA field. The number of column names specified must match the maximum number of values to be aggregated into the mapped field. For example:

IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component
bug, “First issue”, v1, , , Component1,
bug, “Second issue”, v2, , , Component1, Component2
bug, “Third issue”, v1, v2, v3, Component1,

You can attach files to issues created from your CSV file. To do this, specify the URL of your attachment in an ‘Attachments’ column within your CSV file.  Sub tasks can also be created via the CSV import, and tasks can be linked to more than one project.  The project name and key data is the minimum JIRA project data required for importing issues from a CSV file into specific JIRA projects. When generating the CSV file from Excel or any other spreadsheet application, ensure that a comma is used as the field separator.

Import the CSV file into JIRA

Once logged into JIRA, go to ‘JIRA Admin’ and then click on the ‘External System Import’ link (underneath the System / Import & Export section).

Locate the option for CSV import:  Import projects and issues from a Comma Separated Values (CSV) file into JIRA.       

Import & Export

Click on the Import button to be taken through a 5-step wizard.

During the first step, the project can either be specified in the CSV file as mentioned, or you can select a project from a list of available projects. There is also an option to set an email address for new users (to be created as part of the import if need be), and the date format used in the CSV file.

import CSV file into JIRA_1_of_5

import CSV file into JIRA_2_of_5

The next screen (step 3 of 5) allows you to map fields/columns from the CSV file to JIRA fields. Custom fields can be selected, as well as fields such as Reporter, Assignee, Issue Type, etc.

import CSV file into JIRA_3_of_5

Unless fields were selected for mapping, step 4 of 5 simply allows you to start the actual import:

import CSV file into JIRA_4_of_5

A summary is then displayed on the next screen (step 5 of 5), showing the progress and allowing you to stop the import:

import CSV file into JIRA_5_of_5

And finally, once the import has been completed, a summary of the number of issues that could be imported, are shown with links to a detailed report and the option to save the import configuration:

import CSV file into JIRA completed

Post import checks

Once the import has been completed, and the report has been studied, open the project and insect the issues for any obvious errors.

Happy importing!


More information can be found in the online documentation section:



Interesting Infoware Studios Bookmarks


About the Author:

  Related Posts