Blogs

8 min read

Guide to Import Linked Issues into Jira from CSV

Nov 6, 2018 6:24:00 PM

This resource is for you if you've read Atlassian's documentation but are still confused on how to import linked issues.

Using the external system importer, Jira admins are able to import CSV spreadsheets into Jira to create new issues or update existing ones. This guide is an overview on how to use the External System Importer to create issue links. Note: This is not a comprehensive guide. Before reviewing this information you should understand Atlassian's guide on importing data from CSV. 

Requirements

Your file must meet the basic requirements described in the above-mentioned Atlassian reference material. For the different link types, any additional prerequisites are outlined below. 

How it works

When importing, each issue is assigned a unique ID, which is used when creating links. This ID can be the Issue Key, the Issue Id, or any Unique Identifier that you choose. Once the issues have been identified, you can link them in a variety of ways. 

What should I use for an ID?

  • Issue Key - Use this if the issue already exists in Jira. This is easiest if you are using data exported from Jira, as links export with Issue Key.
  • Other Unique Identifier - If the issue you're referencing doesn't exist in Jira yet, this is your option, which is particularly useful if you're importing linked data from another system that already has an ID assigned.

Examples

Sub-tasks and Parents

To create a sub-task/parent link, you use the Issue Id and Parent Id fields. Issue Id and Parent Id should each have their own columns in the spreadsheet. You can use whichever ID type you have decided on. In the below example, the issues are assigned consecutive numbers as IDs. This will work with any sub-task type issue types.

The spreadsheet should look something like this:

Issue Key
Issue Type
Summary
Issue ID
Parent ID
SCRUM-1 Story Ability to reserve an item for 2 hrs and return to it later 1  
SCRUM-2 Sub-task Create unit tests 2 1

When mapping the CSV columns to the fields:

Sub task and parent mapping in Jira

Importing Standard Link Types

If all of the issues in the spreadsheet are new (i.e., they do not exist in JIRA yet), you do not need to include an Issue Key. 

When importing issues using standard issue links (Epics, blocks, duplicates, etc.), you will follow a similar structure as before. You will still map Issue ID to a unique identifier, but instead of using Parent Id, you will use the specific link type. Each link type requires its own column, as shown below, allowing you to import multiple types of links at once. 

If any of the issues already exist in Jira, be sure to enter a value into the Issue Key field. You can import issues in any combination: whether all, some, or none of the issues already existing in Jira. 

Issue Key
Issue Type
Summary
Issue ID
Link "blocks"
Link "relates"
  Story As an admin, I'd like to import issues into Jira 123 456  
  Story As an admin, I'd like to link Jira issues 456   123

When mapping the CSV columns to the fields:

Importing standard link types in Jira

Here's an example of what one of the newly imported issues above looks like:

It is important to note that Portfolio for Jira's parent linking functions differently than the standard issue links. Portfolio for Jira uses a custom field "Parent Link" to create the connection, and for this reason, it has different requirements for importing. 

For these links, you'll need to use the Issue Key, otherwise the field will not recognize any other IDs, which means that the issues must exist in Jira before you can create a Portfolio parent link via import. In this case, there needs to be a column with Issue Keys mapped to the Parent Link field. Note that all hierarchy levels above Epic use this same field, so you can have only one column. However, the Portfolio hierarchy must be respected; if you try to link an Initiative directly to a Story, for example, you will receive an error on import. 

The example below shows what it might look like if your hierarchy was configured as: Initiative - Epic - Story. The Epic would be linked to the initiative using the Parent Link field, but the Story is linked to the Epic through the Epic link. 

Issue Key
Issue Type
Summary
Link "Epic"
Parent Link
SCRUM-1 Story Make the server more efficient SCRUM-2  
SCRUM-2 Epic Blazing-fast server   SCRUM-3
SCRUM-3 Initiative World Class Product Experience    

 

Once imported, the issues appear in Portfolio like this:

Imported issues in Jira Portfolio

Now it's your turn to Import and Link!

Once you have your file prepped as described above, you can import issue links into Jira. If you run into any trouble, be sure to check:

  1. Your mappings -  Are the correct columns mapped to the right fields?
  2. Field values - Do I have the right values?
  3. IDs - Have I used the right type of ID mapping? 

As always, before importing large files, be sure to start with small amounts of data and test regularly. 

 

Now that you have your imported issues linked, feel free to check praecipio.com for other helpful tips on using the Atlassian tools.

Written by Morgan Folsom

Webinars

Case Studies

Blog