What is the expected CSV file format to keep links/relationships between issues to import into JIRA? Edited


I am working on the ability to import a CSV file into JIRA. The file contains a set of issues that could be represented with Stories, Epics and Sub-Tasks/Tasks.

My goals are:

1) to create the set of issues into JIRA maintaining the issue types as defined in the CSV file,

2) to keep the relationships between the different issue types contained in the file:

  1. relationship between any issue type and epic
  2. relationship between n sub-tasks and their story parent

Could you please help me to understand how the file should be configured in order to keep those relationships listed above? Please see how my CSV file looks in order to confirm if this is the expected format: CSV file containing issue records to be imported.png

And this is configuration of file used to map the fields:

"config.version" : "2.0",
"config.project.from.csv" : "false",
"config.encoding" : "UTF-8",
"config.email.suffix" : "@",
"config.field.mappings" : {
"Issue Type" : {
"jira.field" : "issuetype"
"Sub-Tasks" : {
"jira.field" : "issuetype"
"Parent Link" : {
"jira.field" : "subtask-parent-id"
"Description" : {
"jira.field" : "description"
"Linked Issues" : {
"link.type" : "10000"
"Summary" : {
"jira.field" : "summary"
"Epic Name" : {
"existing.custom.field" : "10005"
"Key" : {
"jira.field" : "issue-id"
"Epic Link" : {
"existing.custom.field" : "10006"
"config.value.mappings" : {
"config.delimiter" : ",",
"config.project" : {
"project.type" : null,
"project.key" : "MVMTORISCR",
"project.description" : null,
"project.url" : null,
"project.name" : "MVMT Scrum",
"project.lead" : "mvmtori@ar.ibm.com"
"config.date.format" : "dd/MMM/yy h:mm a"

In addition, why should I use Tasks instead of Sub-Tasks in order to establish the "parent Story > children Sub-Tasks/Tasks" relationship? I tried with both Task and Sub-Task issue types but the parent-children relationship only worked with Sub-Tasks.


Look forward to any assistance.

Thanks in advance,


2 answers

Hi Victoria,

csv import example.PNG

First, the difference between Story, Task, and Sub-Task:
Story and Task are both at the standard level of JIRA issue type, while Sub-Task is at the sub-task level. The only issue types that can be sub-tasks to standard issue types are those set up as sub-task issue types. So you can have Story + sub-tasks or Task + sub-tasks, but not Story + tasks under it.

Second, to set up the parent-child relationship, you'll need two additional columns: Issue ID and Parent ID. Issue ID is a sequential numbering of your issues, starting with 1. Parent ID should be filled in on sub-task rows to identify which row's issue will be their parent.

Third, to set up the Epic Link, you'll need two additional columns: Epic Name and Epic Link. Epic Name must be filled in on the epic rows - it's a required field that is usually equivalent to the summary or a shortened version (e.g., Summary "Upgrade Wintel Servers" might have Epic Name "Wintel Upgrade"). The Epic Link field should be filled in on standard issue type rows (i.e., Story or Task) using either the epic's key or the epic's name.

Hope that helps!


In order to get epic links, your method is right, it should work.

To get sub-tasks linked, you need to have 2 more columns: Issue ID and Parent ID. The Issue ID column must contain sequential and unique numbers (1,2,3, etc for example) for all your issues. The Parent ID column will contain values for the subtasks. In that column, each subtask will have the value of the Issue ID of the parent task.


Issue type, Summary, Issue ID, Parent ID

Task, Do something, 1,,

Task, Do something else,2,,

Sub-Task, Do it, 3,1


You will create 2 tasks and a sub-task. The sub tasks will be linked to the "Do something" Task because the value of the parent id column is 1 which corresponds to the first task.

I hope this answers the question.


Suggest an answer

Log in or Sign up to answer
How to earn badges on the Atlassian Community

How to earn badges on the Atlassian Community

Badges are a great way to show off community activity, whether you’re a newbie or a Champion.

Learn more
Community showcase
Published Sunday in Agility

You asked for it, so we delivered: images on issues have arrived

A picture tells a thousand words. And agility boards have just released their latest feature: cover images on issues – so now your board can tell a story at first glance. Upload attachmen...

300 views 3 11
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you