CSV import Parent-child mapping

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform Notice: Cloud Only - This article only applies to Atlassian products on the cloud platform.


Importing parent-child relationship using CSV import in a Company-managed project.


In the Jira Cloud, whenever we import a CSV backup of issues to a production site that contains Epic->Stories/Task->Sub-tasks relationships, it becomes a maneuver task that consumes a lot of time and patience for customers and even for support engineers.

The purpose of this article is to simplify this process for the users for a seamless CSV import experience.


Whenever a CSV import is performed, we usually end up losing Parent-child relationships.  


This is due to improper mapping of the parent and child during the import process. 


  1. Firstly, make sure the exported CSV file contains at least the following columns for the parent-child mapping:

     Issue type, Issue key, Issue ID, Summary, Parent, Custom field (Epic Link), Custom field (Epic Name)

    Please make sure that the Issue types are always listed based on theirs hierarchy in rows. That is the topmost rows should list all the Epic's and then following the Standard issue types  and then the Sub-tasks. 

  2. Make sure to add a value for the column 'Custom field (Epic Name)' against the Epic issue type. 
  3. Now copy this value from the column 'Custom field (Epic Name)' of Epic issue type and paste it in the column of Custom field (Epic Link) against the Standard Issue types. This step will ensure that we are mapping the Epic issues with its child issues.
  4. For the Task→Subtask relationship to work, copy the 'Issue ID' of the Task issue type and paste it in the 'Parent' column against the Subt-task issue type.
  5. After making the above changes, the Issuetype mappings should look as per the below sample screenshot.

  • In the above table, we have used the "Issue Key" column only for a better visual understanding of the table. When the issues are imported into the destination project, they will be taking a new issue number (based on the issue counter on the destination project) and the destination project key. For example, if we import the above issues to a destination project which has the project key "PK", then these newly imported issues will have the issue key as PK-1,  PK-2, etc.

The CSV file is now ready for import. 

Now follow the below steps to import the CSV file.

  1. Under the Jira admin settings, navigate to External system import.
  2. Upload this CSV file.
  3. Select the destination project where you want the issues to be imported from the CSV file.
  4. Map the CSV fields with the corresponding Jira fields as shown in the below sample screenshot and checkmark the Map field value columns and click on Next.
  5. Verify the target value mappings. Sample screenshot below for reference.


       6. Click on Begin import.

  • After a successful import, the Epic->Standard issue type relation should look like this as per the below screenshot.


  • And the Task→Subtask relation should look like this as per the below screenshot.

Similarly, you can include any other custom field columns in the exported CSV file and import it in one go along with the correct parent-child mapping as we discussed in the above steps.

Last modified on Dec 8, 2021

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.