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 !
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)”.
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).
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 :
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
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).
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.
- 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.
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.