Import data from a CSV file

When migrating from another issue tracker, you can export data to a comma-separated value (CSV) file and then import that file into your Jira Cloud applications. CSV files are text files representing tabulated data and are supported by most applications that handle tabulated data. 

Recommended data size

When importing large projects, we recommend splitting your data to reduce performance issues and ensure optimal speed of the import.

Preparing your CSV file

When creating a CSV file that can be imported to Jira, make sure that:

• All fields are separated by commas

• Any piece of content (including commas and new lines) is enclosed in quotes.

CSV file requirements

Each CSV file must possess a heading row with a Summary column

The CSV file import wizard uses the CSV file header row to determine how to map data from the file's 2nd row and beyond to fields in Jira.

The header row should avoid containing any punctuation (apart from the commas separating each column) or the importer may not work correctly.

The header row must contain a column for Summary data.

Commas (as column/field separators) cannot be omitted

For example, this is valid:

... but this is not valid:

CSV file structure

Capturing data that spans multiple lines

Use double-quote marks (") in your CSV file to capture data that spans multiple lines. For example, Jira will treat the following as a valid CSV file with a single record:

Treating special characters literally

Use double-quote marks (") around a section of text to treat any special characters in that section literally. Once this data is imported, these special characters will be stored as part of Jira's field data. Examples of special characters include carriage returns/enter characters, commas, etc.

To treat a double quote mark literally, you can add another double quote mark character:

...which, once imported, will be stored in Jira as:

Aggregating multiple values into single fields

You can import multiple values into a single Jira field that accepts multiple values (e.g. Fix (for) Version, Affects Version, Component, Labels). To do this, your CSV file must specify the same column name for each value you wish to import to the same field. The number of column names specified must match the maximum number of values to be aggregated into the mapped field.

For example:

In the above example, the Component field of the second issue and the Fix Version field of the third issue will generate multiple values in the relevant field after importing.

Importing attachments

You can attach files to issues created from your CSV file. To do this, specify the URL of your attachment in an Attachments column within your CSV file.

Note that URLs for attachments support the HTTP and HTTPS protocols and can be located anywhere that your Jira Cloud site can access.

If you aren’t sure of your Atlassian account ID, you can log in to your Jira Could site, click on your avatar on the top-right corner of the page, and go to Profile. The last part of the URL of the Profile page is your Atlassian account ID.

For eg:https://<yoursitename>.atlassian.net/jira/people/<Your Atlassian account ID>

Creating parent / child relationships

You can create a hierarchy of imported issues by specifying their parent / child relationships:

• Add three columns to you CSV file with the headings: “Issue ID”, “Issue type”, and “Parent”

• Ensure each issue in your CSV is given a unique (sequential) number in the "Issue ID" column

• Reference the unique "Issue ID" number of an issue in the “Parent” column

• The parent issues must exist above the child issues in the file

Refer to CSV import parent-child mapping for more details and examples of the required mappings.

In the following example, the fourth issue will be a child of the second issue if you match the "Issue ID" and “Parent” fields in your CSV file to the corresponding Issue and Parent fields in Jira. Similarly, the second issue will be the child of the fifth issue as the “Issue ID” and “Parent” fields are matched.

Importing issues into multiple Jira projects

You can import issues from your CSV file into different Jira projects by:

• Adding two columns to your CSV file with the headings "Project Name" and "Project Key"

• Ensuring that every issue represented in your CSV file contains the name and key in these columns for the corresponding Jira projects

The project name and key data is the minimum Jira project data required for importing issues from a CSV file into specific Jira projects.

In this example, the first and second issues will be imported into the "Sample" project (with project key "SAMP") and the third issue will be imported into the "Example" project (with project key "EXAM") if you match the "Project Name" and "Project Key" fields in your CSV file to the corresponding Project name and Project key fields in Jira:

How to handle unresolved issues

For fields mapping to Resolution, Priority, and Issue Type, you'll see a list with the available values in Jira. Create values that do not exist in Jira by clicking the green plus symbol.

You'll also see a list with available values for fields mapping to Status; however, you will not be able to create new status values.

For the Resolution, Priority, Issue Type, and Status fields, you can choose the following:

• Import as blank — this causes the Jira value to be blank for that field. If you are importing unresolved issues, you should create a field mapping for the Resolution field and change the value from "Unresolved" to "Import as blank".

• No mapping — this attempts to import the value in the CSV file as is. Note that the import will fail if a field value is mapped to a Jira field that doesn't support that value. Fields mapping to Status and Issue Type will use the default value when "Import as blank" is also selected.

Importing worklog entries

Your CSV file can contain worklog entries. For example:

Note that you need to use seconds in order to track time spent.

Importing to multi select custom fields

Your CSV file can contain multiple entries for the one Multi Select Custom Field. For example:

This will populate the Multi Select Custom Field with multiple values.

Importing cascading choice custom fields

You can import values to a cascading choice custom field using the following syntax:

The '->' separator allows you to import the hierarchy.

Updating existing issues

To update existing issues, your CSV file needs to contain a column that maps to Issue Key. If an issue exists for a given key, it will be updated.

In this example, the second row will create issue TT-1, while the third row will set the number of votes to 7 and add two labels, and the fourth row will change the issue summary. In the next row, issue TT-2 will be created with two labels. The last row removes labels with the <<!clear!>> special marker:

Importing your CSV file

Once your CSV file has been prepared, log into your Jira Cloud site as a Jira administrator to start the import process.

Upload your file

1. Choose > System.

2. In the Import and Export section, click External System Import and then click CSV.

   1. If you see the new import experience, select switch to the old experience to go to the CSV file import wizard.

3. Choose your CSV source file. 

4. Leave the Use an existing configuration file option unchecked if you do not have a configuration file or if you want to create a new one. Configuration files specify a mapping between column names in your CSV file's header row and fields in your Jira site. At the end of the CSV import process, Jira will create a configuration file that you can use for subsequent CSV imports. 

5. Expand the Advanced section to change the file encoding (UTF-8 by default) and CSV delimiter. If your CSV file uses a separator character other than a comma, specify that character in the CSV Delimiter field.

6. Click Next.

Set up project mappings

1. Choose to import all issues into one (new or existing) Jira project or into multiple Jira projects. To complete this step, fill in the following:

   1. Import to Jira Project - You can choose Select a project if you're importing all issues into a single Jira project. Start typing the name or key of a project that already exists in Jira, or select Create New from the dropdown to add a new project. Note that new projects require a name, key, and lead.
      
      If you want to import issues into multiple Jira projects, choose Defined in CSV. Make sure that every issue in your CSV file includes project name and key data.

   2. Email Suffix for New Users - Enter the email address domain for any new users specified in the CSV file who will be added to Jira during the import.

      • Date format in import file - Specify the date format used in your CSV file using syntax that complies with the Java SimpleDateFormat.

2. Click Next.

Set up field mappings

1. In the Import column, check each CSV Field (determined by your CSV file's header row) that you want to import into your chosen Jira project. Note that at least one of the selected fields must contain data for the Summary field. If your CSV file contains more than one of the same field name in its header row, the CSV import process will combine these into a single field marked with .

2. In the Jira field column, select the Jira fields you want to match to fields defined in your CSV file (i.e. each CSV field you selected in the previous step). You must select the Summary field in order to proceed to the next step. For CSV fields that have been aggregated during the import process, you will only be able to select Jira fields that support multiple values. 

3. To modify the values of any field in the CSV file before importing into Jira, select the Map field value checkboxes next to the appropriate fields. 

4. Click Next.

Set up field value mappings

1. Specify the Jira field values for each CSV file field value you selected in the previous step. Leave a field blank if you want to import the value as is. 

2. To create new Priority or Resolution values in Jira, click Add new... next to the appropriate field. 

3. Click Begin Import when you are ready to begin importing your CSV data into Jira. 

4. During the import, you can download a detailed log to reveal more information about the process. You can also save the configuration of this import if you need to import another CSV file with similar settings. 

Tips for importing CSV data into Jira fields

Below are some helpful tips when importing data from your CSV file into specific Jira fields: