Have you read Atlassian's documentation but are still confused by how to import linked issues? If yes, this resource is for you! Using the external system importer,Jira admins are able to import CSV spreadsheets intoJira 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 understandAtlassian'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? To create a subtask/parent link, you use the Issue IdandParent Idfields. 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 When mapping the CSV columns to the fields: 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" When mapping the CSV columns to the fields: Here's an example of what one of the newly imported issues above looks like:Examples
Subtasks and Parents
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 Importing Standard Link Types
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
Creating Portfolio forJira 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 inJira 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:
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:
- Your mappings -Are the correct columns mapped to the right fields?
- Field values -Do I have the right values?
- 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.
Put Your Atlassian Tools to Work
Optimize Your Atlassian Stack with Praecipio
Get Started