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 perform data migration. However, the good news is that most systems can export data in CSV (or Excel, which can be easily transformed into CSV format); 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, which will help to keep the file size down.
• If your file contains users who need to be imported into fields such as Assignee, make sure you use either their usernames or email addresses that can be matched against corresponding accounts in Jira.
• If your file contains dates that need to be imported into fields, such as Due date, make sure they are all formatted using the same date format. This is so that Jira can process date values consistently.

How to do it...

To import data from other systems, perform the following steps:

1. Log in to Jira as an administrator.
2. Select the Projects menu from the top and select the Import External Project option.
3. Select the CSV option. If, however, you see your system in the list, you can choose that instead. The process of using a system-specific importer will be mostly the same as the CSV importer, with some minor differences.

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 a comma (,) as its separators. Click on the Next button to proceed to step 2 of the wizard:

6. Select the project to import your data into. If you do not have a project, you can select the Select New option and create a project on-the-fly.

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. Verify 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 while being imported 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 selected list style field. This will allow you to map individual values from the CSV file column to 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 will end up with duplicated values due to, for example, case sensitivity:

10. If you opt to map field values, review all 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 and Jira will create it.
11. Click on the Begin Import button to start importing your data into Jira:

12. After the import process is completed, review the 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 CSV files to import custom data into Jira is the most versatile approach since many systems can export their data into CSV. However, as you will 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.