Importing data from CSV

Often you will need to import data from other systems into JIRA. For example, you might want to migrate data from an older bug tracking system, or if you have data coming out of other systems, you may want to use this output to populate your project.

As systems often have their own data structure, it is often not this straightforward to do a data migration. However, the good news is that most systems can export data in the CSV format (or Excel, which can be easily transformed into CSV); we will look at using CSV as a way to import data into JIRA in this recipe.

Getting ready

When importing data into JIRA, the most important thing is to prepare your input data file and make sure it is formatted correctly and contains all the necessary information. To help the importer, keep the following in mind:

• Remove any non-data-related content, especially if you created your CSV file from a spreadsheet.
• If your file contains users that need to be imported into fields such as Assignee, make sure you use either their usernames or e-mail addresses for JIRA to match them up with the actual users in the system.
• If your file contains dates that need to be imported into fields, such as Due date, make sure they are all formatted with a single date format. This is so that JIRA can process the date values consistently.

How to do it...

To import data from other systems:

1. Log into JIRA as an administrator.
2. Select the Projects menu from the top and select the Import External Project option.
3. Then, select the system from the list that comes out of the box with JIRA. If your system is not listed, select the CSV option.
4. Select the CSV file for the CSV Source File field. If you are performing an import for the first time, do not select the Use an existing configuration option. We will generate the configuration at the end of the import, and you will be able to use this to fast-track future imports.
5. Expand the Advanced option if your file uses a different file encoding or uses a character other than comma (,) as its separators. Click on the Next button to go to Step 2 of the wizard.
   
6. Select the project to import your data into. If you do not have the project, you can select the Select New option and create a project on the spot.

   Tip

   Generally, it is best to have the project created beforehand to ensure that it is set up with the correct configuration schemes, such as the workflow and fields.

7. Varify the E-mail Suffix for New Users and Date format values used in your CSV file. This will ensure that data such as dates will be correctly parsed during import and saved in JIRA's date fields, such as Due dates.
   
8. Select and map the CSV columns to JIRA fields. Certain fields, such as the Summary field, must have a corresponding column in the file. Otherwise, JIRA will not allow you to proceed. If you do not want to map a column, you can select the Don't map this field option.
9. Select the Map field value option for any columns mapping to a select list style field. This will allow you to map individual values from the CSV file column to the options available in JIRA. Unless you are sure that your file contents can be mapped to the JIRA field options exactly, it is best to manually verify this; otherwise, you would end up with duplicated values due to things such as case sensitivity.
   
10. If you select to map field values, review each of the listed values and map them to their corresponding field options in JIRA. If a value does not have an option, you can type in the desired option for JIRA to create.
11. Click on the Begin Import button to start importing your data into JIRA.
    
12. After the import process is completed, review the import result. You can click on the download a detailed log link to get a full log of the process if the import fails. You can also click on the save the configuration link to get a copy of the mapping files so that next time, you do not have to remap everything from scratch.

There's more...

Using the CSV file to import custom data into JIRA is the most versatile approach as many systems can export its data into CSV. However, as you would have noted already, JIRA comes with a number of specialized importers for various systems. These importers often have additional features to help with data import. The Atlassian Marketplace website https://marketplace.atlassian.com also has a number of importers created by third parties. If you do not see your system listed in the out-of-the-box importers, make sure you do a search in the marketplace and check whether someone has already created an importer for it.