Summary

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

Previous versions of this KB made reference to using the "Epic Link" field.  However this KB has been updated as of April 2024 to reflect the changes in regards to the Deprecation of the Epic Link and Epic Name fields.  Going forward with Jira Cloud, the Parent field should be used instead.

Environment

In the Jira Cloud, whenever we import a CSV backup of issues to a production site that contains Epic->Stories/Task->Sub-tasks relationships the epic child relationship can be tricky to maintain.

The purpose of this article is to simplify this process for the users for a seamless CSV import experience when importing issues with mapped hierarchies.

Diagnosis

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

Cause

This is due to issue order in the CSV file and improper mapping of the parent and child during the import process. 

Solution

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

   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 Highest hierarchy issue types and then following the Standard issue types  and then the Sub-tasks. 

   ORDER of importance top to bottom layout:

   <TOP OF FILE>

   • Initiative and other higher levels 
   • Epics
   • Standard issue types (Story, Bug, task, etc...)
   • Sub-tasks

   </BOTTOM OF FILE>

2. For the parent→child relationship to work, copy the 'Issue ID' of the parent issue type and paste it in the 'Parent' column of the the Child  issue type.
3. After making the above changes, the Issue Type mappings should look as per the below sample screenshot.

Example CSV With the following layout:

• NOTE The ID's used are place holder numbers, they can be any number but MUST be unique per issue per csv import.

As Raw text in CSV formatting:

issue type,issue key,status,summary,issue id,parent
Theme,test-123,To Do,Example theme summary,1,
initiative,test-124,To Do,Example initiative summary,2,1
Epic,test-125,To Do,Epic with parent and no child story but 1 sub-task and parent Inititive,3,2
Epic,test-126,To Do,This is an epic with 1 story and 1 bug as child issues mapped,4,
Story,test-127,To Do,Example story 1 Summary no child issue mapped,5,
Story,test-128,To Do,"Example story with 1 child subt-ask mapped, and a parent epic is mapped",6,4
Bug,test-129,To Do,bug with 1 child sub-task ,106589,4
sub-task,test-130,To Do,subtask 1,7,6
sub-task,test-131,To Do,subtask 2,8,106589
sub-task,test-132,To Do,Subtask 3,9,3

The CSV file is now ready for import. 

Now follow the below steps to import the CSV file.

1. Under the Jira admin settings > Import and export > External system import
2. Select "Switch to the old experience"
3. Select CSV
4. Upload this CSV file by clicking on "Choose File" and navigating to the file via your local file explorer 
5. hit next once uploaded
6. Select the destination project where you want the issues to be imported from the CSV file.
   1. Leaving formatting as default unless you made customized changes to any additional date and time fields or email address fields
7. Map the CSV fields with the corresponding Jira fields as shown in the below sample screenshot.
   
8. Click on "Next"
9. Verify status mappings of fields text value in file "Value from Importer" to actual status in the Jira system "Target value in Jira"
   
10. Click "Begin import"

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

In the issue view:

• Example Theme→Initiative and Initiative→Epic relation should look like this as per the below screenshots.

• Example Epic→Story and Epic→Subtask relation should look like this as per the below screenshots.

• And the Story→Subtask and Bug →Subtask relation should look like this as per the below screenshots.

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.