How to import issues into JIRA


Posted by
Aude DUSACRE

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.

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 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.

Conclusion

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.

  • Aude Dusacre

    Hi Deepak,

    AFAIK there is no workaround for this as Atlassian cannot import external links to JIRA yet …

    Maybe in few releases 😉
    Regards,
    Aude

  • Deepak

    Hi

    I want to bulk create jira’s with the csv uploader. I can link jira’s in the same instance, but I can’t link to ones in different instances.

    Is there a way around this?

  • 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!