How to Import Linked Issues into Jira from CSV

Have you read Atlassian's documentation but are still confused by how to import linked issues? If yes, this article is for you!

Using the External System Importer, Jira admins can import CSV spreadsheets into Jira to create new issues or update existing ones. This guide is an overview of 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

Subtasks and Parents

To create a subtask/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:

When mapping the CSV columns to the fields:

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 the 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. 

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

Creating Portfolio for Jira Parent Links

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. 

Once imported, the issues appear in the Portfolio like this:

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. 

At Praecipio, our team of accredited and certified Atlassian experts can help your organization meet its goals efficiently and succinctly. To learn more about how we can partner with your team, visit our Atlassian Services page to explore some of the solutions we can help implement, or contact us directly.