How to import issues into JIRA


Posted by
Aude DUSACRE

June 30, 2015

The JIRA importers plugin doesn’t only enables JIRA’s compatibility with applications such as Bugzilla or Mantis, it also enables import of CSV files. Easy to use, it turns out to be quite handy to create and/or modify JIRA issues from a file. In this blog, I’ll present the CSV feature and the best practices surrounding its use. Let’s get started !

Import Configuration

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: select the “System” section, then “Attachments”.

Warning: importing heavy files can take time and decrease JIRA performance.

We recommend to split heavy files into several files and to start the operation out of working hours.

The file encryption is by default UTF-8. Accents might not be recognised (this is frequent 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

The 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. 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@” and will belong to the group jira-users.

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

Mapping fields

import mapping fields

For every columns in your file, you can define (or not) a matching field in JIRA. You can also map values at the next step.

Tips

  • 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 a doubt about
  • Open the CSV with a classic text editor such as notepad to check on data format
  • At the end of the import, save the logs and the configuration file in order to identify anomalies if there are some and to re-use your configuration file for future imports.

Conclusion

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

For more tips and best practices on JIRA, you can consult our other blogs about the tool.

  • Mark Biro

    Hi there,

    Great article. A little addition to it:
    With JExcel, you can import issues from Excel to JIRA.

    And it’s free. Feel free to try it: https://marketplace.atlassian.com/plugins/com.moresimp.jexcel/server/overview

    Best Regards, Mark

  • Importing test Cases works fine, but when I add sub-test cases
    and include Issue ID and Parent ID as in your sample I could not load the sub-test cases.
    In the Documentation I have found:
    “remember to match the Issue ID and Parent ID fields in JIRA to those in your CSV file.” – but I never got this JIRA fields.
    Need I admin rights for these ?

  • Hi there,

    With add-on JExcel, you can import issues from Excel to JIRA by copy and pasting! And its free.

    Feel free to give it a try:
    https://marketplace.atlassian.com/plugins/com.moresimp.jexcel/server/overview

    Hope it will help you, too.

    Best Regards, Mark

  • Nice blog, Very useful to me… thanks

  • Aude Dusacre

    Hi Pierre,

    During the import, JIRA is giving you a link to the import log so you can watch it live and at the end of it you can also save it.

    If you lost the page and the links, everything is still log in the default log file of JIRA (JIRA home directory /log/atlassian-jira.log)

    Regards,
    Aude

  • Aude Dusacre

    Hi Madhava,
    If you’re not adding manually the Issue Key to your CSV file, JIRA will add new issues after the one already created on your project.
    To be simple you have to remember those two keys :
    – To create new issues : summary (+ project) + status + reporter must be in your CSV
    – To update existing issues : issuekey must be in your CSV.

    If you want to create subtasks with Issue Id + Parent ID, those two values are mandatory only during import so I would suggest to keep somewhere (a JIRA issue ?) the latest issue id you used during your import so you can start with it for you next import.

    If you forgot to write it down, you can find it back in the database.

    Hope that helps,
    regards,
    Aude

  • Nice tutorial.
    Where could the log files be found when errors happen?

  • Good question, I was wondering the same. We are on issue 10k in our system and I would not want to create a conflict with other issue numbers.

  • what happens to the existing issues when I import CSV into JIRA? are they going to be replaced? how the issue number going to be generated?

  • By far the most practical, effective tutorial on importing Excel data into Jira as issues. Keep up the great format of the tutorials!