How to import stories linked to epics in jira

[Matthew Cowling]

We have an externally supplied set of user stories, grouped as Epics, which we wish to import into JIRA (CSV).  I can easily import the stories, but how can we import both simultaneously so that the stories are automatically linked to the various EPIC.  I do not want to have to create the EPICs first, we would like to import all at once.

[pborkowski · Accepted solution]

That shouldn't be a problem when using JIRA CSV Importer. Simply specify Epic Link mapping in your stories example:

Issue Type,Epic Name,Summary        ,Epic Link
Epic      ,  my-epic,Build a car    ,
Story     ,         ,Build an engine,  my-epic
Story     ,         ,Buy some tires ,  my-epic

The example above will create an epic and link stories to that epic.

[Matthew Cowling]

Thanks, greatly appreciated. (your user documentation is not so clear on this!)

[Gil Groman]

What is the REST parameters needed to set this 'Epic Link' field? is it a custom field in JIRA? what's is value?

[Michael Green]

Hi, 

I tried this and its not working.  My CSV data looks like this :

Project,Issue Type,Epic Name,Summary,Epic Link,Description,Labels,Priority,Original Estimate,Story Points
DTPSID,Epic,Additional Feeds,Additional Feeds,,Additional Feeds,,,,
DTPSID,Story,,DT Go Live|Additional Feeds|ACT Spatial|,Additional Feeds,DT Go Live|Additional Feeds|ACT Spatial|,,,57600,2
DTPSID,Story,,DT Go Live|Additional Feeds|ACT UCV|,Additional Feeds,DT Go Live|Additional Feeds|ACT UCV|,,,57600,2
DTPSID,Story,,DT Go Live|Additional Feeds|Australia Post postcodes|,Additional Feeds,DT Go Live|Additional Feeds|Australia Post postcodes|,,,57600,2
DTPSID,Story,,DT Go Live|Additional Feeds|PSMA Postcodes|,Additional Feeds,DT Go Live|Additional Feeds|PSMA Postcodes|,,,57600,2
DTPSID,Story,,DT Go Live|Additional Feeds|TAS (the List)|,Additional Feeds,DT Go Live|Additional Feeds|TAS (the List)|,,,57600,2
DTPSID,Epic,DAS Integration,DAS Integration,,DAS Integration,,,,

ERROR LOG SHOWS :

16-05-25 16:40:33,544 INFO - Reindexing took 41 ms.
2016-05-25 16:40:33,544 INFO - Importing issue: [externalId='autoid-4020395359902999763', summary='DT Go Live|Additional Feeds|ACT Spatial|']
2016-05-25 16:40:33,554 WARN - Cannot add value [ [Additional Feeds] ] to CustomField Epic Link in Issue with summary 'DT Go Live|Additional Feeds|ACT Spatial|'. Exception Message: null
java.lang.NullPointerException
	at com.atlassian.jira.issue.search.parameters.lucene.DefaultPermissionQueryFactory.collectProjectTerms(DefaultPermissionQueryFactory.java:133)
	at com.atlassian.jira.issue.search.parameters.lucene.DefaultPermissionQueryFactory.getQuery(DefaultPermissionQueryFactory.java:63)
	at com.atlassian.jira.issue.search.parameters.lucene.PermissionsFilterGeneratorImpl.getQuery(PermissionsFilterGeneratorImpl.java:28)
	at com.atlassian.jira.issue.search.providers.LuceneSearchProvider.getPermissionsFilter(LuceneSearchProvider.java:373)
	at com.atlassian.jira.issue.search.providers.LuceneSearchProvider.getHits(LuceneSearchProvider.java:185)
	at com.atlassian.jira.issue.search.providers.LuceneSearchProvider.search(LuceneSearchProvider.java:279)
	at com.atlassian.jira.issue.search.providers.LuceneSearchProvider.search(LuceneSearchProvider.java:91)
	at com.atlassian.jira.issue.search.providers.LuceneSearchProvider.search(LuceneSearchProvider.java:87)
	at com.atlassian.jira.issue.search.providers.DualSearchProvider.lambda$search$0(DualSearchProvider.java:78)
	at com.atlassian.jira.issue.search.providers.DualSearchProvider.performSearch(DualSearchProvider.java:140)
	at com.atlassian.jira.issue.search.providers.DualSearchProvider.search(DualSearchProvider.java:78)
	at sun.reflect.GeneratedMethodAccessor485.invoke(Unknown Source)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at com.atlassian.plugin.util.ContextClassLoaderSettingInvocationHandler.invoke(ContextClassLoaderSettingInvocationHandler.java:26)
	at com.sun.proxy.$Proxy98.search(Unknown Source)
	at sun.reflect.GeneratedMethodAccessor485.invoke(Unknown Source)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at org.springframework.aop.support.AopUtils.invokeJoinpointUsingReflection(AopUtils.java:317)
	at org.eclipse.gemini.blueprint.service.importer.support.internal.aop.ServiceInvoker.doInvoke(ServiceInvoker.java:56)
	at org.eclipse.gemini.blueprint.service.importer.support.internal.aop.ServiceInvoker.invoke(ServiceInvoker.java:60)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:179)
	at org.springframework.aop.support.DelegatingIntroductionInterceptor.doProceed(DelegatingIntroductionInterceptor.java:133)
	at org.springframework.aop.support.DelegatingIntroductionInterceptor.invoke(DelegatingIntroductionInterceptor.java:121)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:179)
	at org.eclipse.gemini.blueprint.service.util.internal.aop.ServiceTCCLInterceptor.invokeUnprivileged(ServiceTCCLInterceptor.java:70)
	at org.eclipse.gemini.blueprint.service.util.internal.aop.ServiceTCCLInterceptor.invoke(ServiceTCCLInterceptor.java:53)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:179)
	at org.eclipse.gemini.blueprint.service.importer.support.LocalBundleContextAdvice.invoke(LocalBundleContextAdvice.java:57)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:179)
	at org.springframework.aop.support.DelegatingIntroductionInterceptor.doProceed(DelegatingIntroductionInterceptor.java:133)
	at org.springframework.aop.support.DelegatingIntroductionInterceptor.invoke(DelegatingIntroductionInterceptor.java:121)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:179)
	at org.springframework.aop.framework.JdkDynamicAopProxy.invoke(JdkDynamicAopProxy.java:207)
	at com.sun.proxy.$Proxy1202.search(Unknown Source)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.customfields.CFValueHandlerEpicLink.findSingleIssueOrNull(CFValueHandlerEpicLink.java:112)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.customfields.CFValueHandlerEpicLink.prepareCustomFieldValue(CFValueHandlerEpicLink.java:54)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.customfields.CustomFieldValueFactory.prepareRawValueForCustomField(CustomFieldValueFactory.java:69)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.customfields.CustomFieldValueFactory.prepareValueForCustomField(CustomFieldValueFactory.java:53)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.customfields.CustomFieldsUtil.setCustomFieldValueForIssue(CustomFieldsUtil.java:202)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.DefaultJiraDataImporter.importExternalCustomFields(DefaultJiraDataImporter.java:1305)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.DefaultJiraDataImporter.createIssue(DefaultJiraDataImporter.java:922)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.DefaultJiraDataImporter.importIssues(DefaultJiraDataImporter.java:798)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.DefaultJiraDataImporter.doImport(DefaultJiraDataImporter.java:414)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.ImporterCallable.call(ImporterCallable.java:26)
	at com.atlassian.jira.plugins.importer.imports.importer.impl.ImporterCallable.call(ImporterCallable.java:15)
	at com.atlassian.jira.task.TaskManagerImpl$TaskCallableDecorator.call(TaskManagerImpl.java:453)
	at com.atlassian.jira.task.TaskManagerImpl$TaskCallableDecorator.call(TaskManagerImpl.java:421)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at com.atlassian.jira.task.ForkedThreadExecutor$ForkedRunnableDecorator.run(ForkedThreadExecutor.java:216)
	at java.lang.Thread.run(Thread.java:745)
2016-05-25 16:40:33,736 INFO - Importing issue: [externalId='autoid-3986760313411359137', summary='DT Go Live|Additional Feeds|ACT UCV|']

[Michael Green]

Even your example comes up with errors :

Your example CSV input file :

Issue Type,Epic Name,Summary ,Epic Link
Epic , my-epic,Build a car ,
Story , ,Build an engine, my-epic
Story , ,Buy some tires , my-epic

ERRORS:

Import completed with 2 warnings:

• Cannot add value [ [my-epic] ] to CustomField Epic Link in Issue with summary 'Build an engine'. Exception Message: null
• Cannot add value [ [my-epic] ] to CustomField Epic Link in Issue with summary 'Buy some tires'. Exception Message: null

[Michael Green]

• Atlassian JIRA Project Management Software (v7.1.4#71008-sha1:eaa0661)

[dth prepago]

i have the same problem any solution?

[John Schultz]

Same issue here - found this JSW-7604 which says it's closed, but I don't think the tech actually tried it.  Does not work the way it is explained.

[Iris Schmid]

I have the same Problem, it worked fine to import stories linked to epics about a months ago, now it seem to be impossible. I'm using the same csv file that I used some time ago and it doesn't work any more. It will create the Epic but not link any story or task to it.

[The Finn Group]

Same issue as @Iris Schmid described, used to work previously but not anymore. Epic is created, so is task but not linked.

[Ruth Struck]

I can't get this to work either. What is the status to get this working again?

[Katey Berg]

I just tried this again and it is still not working; any updates on a fix?

[Dave F]

In short, for each Issue row the name of it's related Epic needs to map to the Epic Link field in Jira. I repeat, map its Epic's name to the Epic Link field.

The fact that there are existing fields called Epic Link and Epic Name makes it all very confusing, and whichever developer coded the import it like this needs a swift kick in the dandenongs, daily.

[Cecilia Little]

We are using the Epic Link for uploading the Stories and our error message keeps telling us that the "my epic name" must be if type if 'Epic' which it is, but was in 'Draft' status.  We  updated it to 'Ready'.  Is there a waiting period for the refresh?

[mfabris]

This seems to be pretty actual still in 2020, especially with the new functionalities of cloud and the next-gen projects.

We had the same problem with next-gen projects on JIRA and found a solution that seems to work.

The step by step solution would be:

1. Export the data in CSV from the project you want to export (choose "all fields")

2. Open the CSV and add two columns; call the columns "Epic Name" and "Epic Link"

3. Optional: if your stories have sub tasks, filter by the column "Issue Type" and deselect all the sub-tasks in your CSV file.

4. Copy the values for the entire column "Issue Id" into the column "Epic Name"

5. Copy the values for the "Parent Id" column into the column "Epic Link"

6. Save your CSV. Have a look at which separator you have (if it is "," or ";" for example)

7. Start the import. Make sure you choose the right separator. Map all relevant fields. Important: map "Issue Type" field to itself. Make sure you map "Epic Link" and "Epic Name" to themselves.

I hope this helps somebody, let us know if you find any flaw!

[Brant Witzel]

I just wanted to add a couple of details to Mirco's answer for those using JIRA Cloud:

1.) Ensure your Epics are listed before anything that links to them in the CSV file... i.e, put them at the top of the file (under the field names).

2.) Ensure the target project was set up as a Classic project (not a Next-Gen).  As of 1/31/2020, Next-Gen projects do not import Epics correctly in my experience.

3) The values in "Epic Name" should be the same as the values from "Summary" for your Epics.  Epic Name values are only valid for Epics.  Your Tasks should have blank Epic Name values.

4) For all of your Tasks that should be linked to an Epic, put the value of the linked Epic's Epic Name in the Task's Epic Link column.

Example CSV file (spaces added for visual alignment only):

Issue Type,Summary        ,Epic Link  ,Epic Name
Epic      ,Build a car    ,           ,Build a car
Story     ,Build an engine,Build a car,
Story     ,Buy some tires ,Build a car,

  The end result of your import will look like this (in a Kanban board):

[Ranjit Nair]

This import mechanism continues to work only for Classic projects and not for Next-Gen projects in Jira Cloud. However there is a workaround for that.

• Create a temporary classic project and import using the CSV template described by Mirco.
• Create a next-gen project.
• Use the "Bulk change" action under Filters  --> Advanced issue search. You'll find the action when you click on the three dots on the top right part of the page.
• Run through the wizard to map the issue types and move the Epics and Stories to the Next-Gen project. 
• Delete the temporary Classic project.

It's convoluted but it works. 

[Vishal Vashishta]

Where we define or select what type of project we are going to create, Next Gen or Classic. 

I do not find any such prompt

[Roland Di Gregorio]

Hi Vishal, naming has changed, also is not so easy to select when you create, in the project overview you see the type of project it is:

• Team-managed projects (formerly next-gen) 
• Company-managed projects (formerly classic projects)

[Vishal Vashishta]

Thank you for writing!

Yes I got this option while creating project. <Team Managed> and <Company Managed>..

Right now I am using template 'Team Managed' and now let me try with 'Company Managed' template.

[Roland Di Gregorio]

you find my step-by-step description somewhere below, also with a file-example.
good luck

[Vishal Vashishta]

Hey Ronald, it worked after selecting the project type as 'Company Managed' and Epic link as the Epic Name

In Addition to this, Issue ID of EPIC has to be the Parent ID of Story.

Cheers!!

My Template for everyone's ref.

Issue Type	Epic Name	Summary	Epic Link	Issue ID	Parent ID	Priorty	Asignee	Reporter	Description
Epic	EPIC1	EPIC 1 Summary		1		Normal			Migration 2
Story		Story 1 Summary	EPIC1	2	1	Normal			US 1

[Fernando Candia]

Hey @Vishal Vashishta, need to mention that it's not possible to do so on Team-Managed projects.

In Team Managed projects the Epic Issue Key is stored in the Parent field for its child stories, whereas in Company Managed projects it is stored in the Epic Link field.

Based on my experimentation with CSV import, when Parent is selected for the mapping field, the import process assumes that the issue being imported is a sub-task. If the Issue Type of the imported issue is not a sub-task issue type, then the import process reports this warning:

From: https://community.atlassian.com/t5/Jira-Software-questions/How-Do-I-Link-a-New-Task-to-an-Existing-Epic-when-doing-a-CSV/qaq-p/1811866

[Vitaliy Zapolskyy]

what works for me:

Issue Type,Key      ,Epic Name,Summary        ,Epic Link

Epic      ,AAA-1    ,  my-epic,Build a car    ,

Story     ,AAA-2    ,         ,Build an engine,  AAA-1

Story     ,AAA-3    ,         ,Buy some tires ,  AAA-1

Appears that Epics import routine is kind of smart, see the last comment here:

https://ecosystem.atlassian.net/browse/JIM-1269

Perhaps topic starter's troubles were related to https://confluence.atlassian.com/jirakb/cannot-import-epic-link-from-csv-due-to-incorrect-format-829030416.html

[Filip Pokorny]

That is interesting, your example doesn't work anymore. Instead of the issue id (Key field in your example), Epic Name must be present like this:

Issue Type,Key      ,Epic Name,Summary        ,Epic Link
Epic      ,AAA-1    ,  my-epic,Build a car    ,
Story     ,AAA-2    ,         ,Build an engine,  my-epic
Story     ,AAA-3    ,         ,Buy some tires ,  my-epic

 I'll have to search and replace all epic ID's linked to epic names linked by every story in the exported CSV. It's time for some regular expressions I guess. 

[Heath Dutton]

Did this work? I have 3k issues that got imported without links to epics and need a solution.

[Filip Pokorny]

my version worked for me

[Heath Dutton]

This doesn't appear to work at all for Next Gen projects. I've tried everything I can think of, and beyond.

[Luke Koops]

Worked for me.  Make sure the value in the Epic Name column is unique.  During my testing, I ended up reusing the name and the links weren't established.  when I made sure to use a unique value it worked.

[jayarjo]

I still get "Cannot add value ... to CustomField Epic Link in Issue with summary .... Probably value was in incorrect format" error. And same for "Epic Name" field. Are those fields pre-existing, or one need to create them?

[peter.casey]

Using Jira Cloud with Nex Gen project also seems to have no mapping to do this.

Trying to use the 'Parent ID' field to import issues with Type = Story throws error (see WARN in bold)

2020-01-09 01:10:55,915 INFO - Importer started!
2020-01-09 01:10:55,927 INFO - Engine is running in Import mode
2020-01-09 01:10:56,137 INFO - All issues will be imported to project: Viz One Upgrade 2019 (VOU)
2020-01-09 01:10:56,166 WARN - Issue 'Build an engine' doesn't have Subtask Issue Type, its Parent Id mapping will be ignored.
2020-01-09 01:10:56,174 INFO - Creating issue: [externalId='autoid--4590135095131978080', summary='Build an engine']
2020-01-09 01:10:56,523 INFO - Issue created successfully with Key [VOU-59], [externalId='autoid--4590135095131978080', summary='Build an engine']
2020-01-09 01:10:56,531 WARN - Issue 'Buy some tires' doesn't have Subtask Issue Type, its Parent Id mapping will be ignored.
2020-01-09 01:10:56,538 INFO - Creating issue: [externalId='autoid--178713755243894322', summary='Buy some tires']
2020-01-09 01:10:56,730 INFO - Issue created successfully with Key [VOU-60], [externalId='autoid--178713755243894322', summary='Buy some tires']

[Benoit]

Because Parent ID work only for Subtask type.

[peter.casey]

Yeah; I figured this out eventually.

Found a workaround of importing as Tasks or Stories, then selecting and demoting (move) all imported to sub-tasks.  At this point Jira Nexgen asks what parent you'd like and you can choose the relevant Story.

[James G.]

I'm working in Next Gen now, but previously worked in the older version. The process I used to use to import and link issues to an epic no longer works. The cards are created, but are not linked to the specified epic. 

I have tried using the steps listed in the post dated May 31, 2018, but they imported issues were not linked to an epic. I"m also not seeing "epic link" as an option in the import tool's mapping page.  Any advice? 

[Christine Meli]

I am experiencing same issue.    I have been unsuccessful trying to import stories into an existing epic.  

[Deleted user]

I'm having the same issues as well. Exceptionally frustrating. 

[RossH]

Epic Link is not an option in the importer for me.

Edit: Fixed - Wasn't in the screen config.

[J L]

For anyone still struggling with this in 2021, it has to be a 'company managed project' not a 'team managed project'. 

[Michael Thaney]

Can you link a bug to user story during the import?

[Benoit]

link are supported. use the same link name.

[Vladimir Abramov]

Hi @Roland Di Gregorio Thank you for the help. I realised that my file was pipe separated due to a local system setting.

I am now having an issue in loading the hierarchy of EPIC - Feature - Story - Task. I required for them all to be linked to each other. Is there a a basic structure you can recommend to bulk load the hierarchy?

I currently use the Epic Link for Features and Issue ID and Parent ID for Stories and Tasks and structure to link tem all together but received error on validation that Issue/Parent ID is only for sub tasks.

How do I create a linked hierarchy above. This is what it looks like below:

[Benoit]

You can look at my reply done on the  Oct 19 2020.

You have your answer there.

Parent ID is used only for Sub-task

[Rosa M Fossi]

Hi Vlad, glad Roland was able to assist with the delimiter issue, were you able to sort out what Benoit referenced?  If it helps, here's a screenshot (I colored the cells for this example so you can see the relationship)

[Roland Di Gregorio]

The import functionality works properly only for Classic Projects and not for Next Gen-Projects.

my workaround:
1.) import to classic projects

---example with link Tasks to Epic and Sub-Tasks to Tasks----

issue type;epic name;epic link;issue ID;parent id;summary;description;assignee;due date;status;reporter
epic;Holiday;;1;;Holiday;;test@mail.ch;26.11.2020;to do;test@mail.ch
Task;;Holiday;2;;Organize fly;;test@mail.ch;21.11.2020;to do;test@mail.ch
Task;;Holiday;3;;Packing;;test@mail.ch;22.11.2020;to do;test@mail.ch
sub-task;;;4;2;Check rates;go to website ;test@mail.ch;23.11.2020;to do;test@mail.ch
sub-task;;;5;2;Book;confirm;test@mail.ch;24.11.2020;in progress;test@mail.ch
-----

2.) convert (with multiple selection) all issues to Next Gen-project 

[Benoit]

This is what I use:Very convenient. I create a template where a lots of numbering is done automatically. I can give that to the product owner to plan his projet. Soon I will integrate standard components to allow synchronisation across multiple project for specific department.

[Benoit]

As you can notice, I do have advanced roadmap. Very useful when you want to plan at business level.

[Rosa M Fossi]

Hi @Roland Di Gregorio  Do you map all the fields? Epic Name and Epic Link 

[Roland Di Gregorio]

Dear Rosa, yes I mapped all fields.
note: import to a classic project and after convert to a next gen-project.
kind regards Roland

[Nadav]

How is this a valid answer... This is not simplifying the experience as I would expect in the next gen project.

It feels half baked in many ways... 

[Vladimir Abramov]

The above screenshot from @Rosa M Fossi looks nothing like mine when I try to map the fields. I have struggled for hours now thinking that the issue i in the CSV file and now I realise that the mapping wizard on my side just reflects the below and I am not able to actually map the fields in the CSV to the destination. Is there a way to resolve this???

[Roland Di Gregorio]

Hi Vladimir, this look in this way, when the csv-file devider is not correctly set (in my case I needed to change from "," to ";" ). kind regards Roland

[mladen_miljic]

Same here: next gen project, importing Stories/ Tasks does not support linking them to an EPIC. I have to do it manually? Really? 

On top of that, adding a Task to an EPIC is a click-nightmare it itself. One need to change the dialog for that, means it loads another page. 

Crazy....

[Claus Schneider (eficode)]

I have seen this issue with "permissions" and "null" on Server 7.3.4 and json importer. Snippet from above

2016-05-25 16:40:33,554 WARN - Cannot add value [ [Additional Feeds] ] to CustomField Epic Link in Issue with summary 'DT Go Live|Additional Feeds|ACT Spatial|'. Exception Message: null
java.lang.NullPointerException
 at com.atlassian.jira.issue.search.parameters.lucene.DefaultPermissionQueryFactory.collectProjectTerms(DefaultPermissionQueryFactory.java:133)
 at 

The root cause was this issue: 
https://confluence.atlassian.com/jirakb/blank-page-displayed-when-loading-permission-scheme-configuration-in-jira-server-297670208.html

The project permission scheme was "None" for some reason.

I tried to "save" it but the first option, but did not succeed. I could delete the project as it was test imports, so it was easy to fix that way. Not forced to go for second option of manipulating the database.

[Ruediger Beck]

Jira Server v7.13.2

For me it just has worked in the way, that I've used in the Epic-link column of the User Story the exact 'summary' content of the Epic.

[mark hardwick]

the above doesn't work for me.  
The epics are created, the stories are created, but the stories are not associated with the epics.

[Filip Pokorny]

What Jira version do you use and what importer? There are 2 (one for global admin, one for project admin)