How to import issues into JIRA

Posted by

February 14, 2017

The JIRA Importers add-on not only makes JIRA compatibile with applications such as Bugzilla or Mantis, it also enables you to import CSV files. Easy to use, it turns out to be quite handy when it comes to creating and/or modifying JIRA issues from a file. In this blog, I’ll present the CSV feature and some best practices surrounding its use.

Let’s get started!

Configuring your import

You can find the importer in the JIRA Administration menu, in “System“, and then in “Import from an external system“. Then, select “Comma-separated values (CSV)”.

external import csv

We must then indicate which CSV to import. The maximum size is limited to 10 mo by default, but you can increase capacity in the administration menu by selecting the “System” section, then “Attachments”.

Warning: importing heavy files can take time and decrease JIRA’s performance – we recommend splitting heavy files into several files and starting the operation out of working hours.

The file encryption is, by default, UTF-8. Accents might not be recognised (this is common when the CSV is generated by Excel). One solution is to use the ISO-8859-1 norm.

If you want to regularly import files, at the end of the first one you can save the configuration and re-apply it using “Use an existing configuration file”.

Building the import file

I am going to create two issues: one issue with “Bug” type and the second one with “Task” type.

For our example we are going to create an Excel sheet. The header line, in yellow, shows the fields to map in JIRA (1 column = 1 field in JIRA).

excel screenshot 1


The “summary” and “issue type” fields are mandatory during the import – they have to exist in your file.

Specific configuration if you have sub-tasks

This principle is identical, except that we will add parent and child notions. This is necessary in order to create links between the task and sub-task:
excel screenshot 2

Compared to the first configuration, we added the blue columns.

Issues with parent ID 1 will be sub-tasks of the task associated with the issue ID 1. The same way, the issue with parent ID 2 will be a sub-task of the task associated with the issue ID 2.

Setting up the import

JIRA import Setup

Depending on your file, you can define a specific project to import/modify issues, or you can define it directly as a column in your file.

The e-mail suffix will be used for the email address of new JIRA users (if the username doesn’t match with an existing one), i.e. if I set my user as Jefferson in my file but the user doesn’t exist in JIRA, then a new user will be created with the email address “jefferson@”, belonging to the group jira-users.

The date format is how you format it in your file (NOT how it is in JIRA).

Mapping fields

import mapping fields

For every column in your file, you can choose whether you define a matching field in JIRA. You can also map values at the next step.


  • You have to set the username of the user (and NOT the full name)
  • Check that Date, Number or Select list fields type have the right format, and the same one
  • Map field value for Select list (to avoid creating new values for them during the import) and fields you have doubts about
  • Open the CSV with a classic text editor such as notepad to check the data format
  • At the end of the import, save the logs and the configuration file in order to identify anomalies (if there are any) and to re-use your configuration file for future imports.


As we’ve seen, importing issues via CSV is not that complicated, but it requires special attention, with file conception and data checking key steps. We highly recommend to make your first imports on a development environment before reproducing them in a production environment, so you can identify potential blockers and/or anomalies. And now, it’s your turn!

Share you experiences with me in the column below.