How to Migrate a Jira Project from a Jira instance to another one

Step by step process of Exporting and Importing a Jira project between Jira instances with video

11 min readNov 1, 2020

Unfortunately, as of today, Nov 2020, Atlassian Jira doesn’t offer a fully working project export/import, including attachments, comments, and history. Suppose you need to carry over a full Atlassian Jira project. In that case, you can export a CSV of all the issues and then import first the Epics, User Stories, and then the Sub-tasks and update the exported CSV with the new IDs the import function will be able to link the children correctly.

You need to know that information like comments, attachments, and issue history will be lost in this process. Therefore I strongly advise you to review, update, and clean up the old Jira Project before starting any export/import.

Below is a step by step practical guide on how to export your Atlassian Jira Project into a new Jira instance.

My Circumstances

Recently I had to migrate a Jira Project from a Jira instance to a new one because we moved from a 3rd party managed Jira instance to our instance.

On the Old Jira instance, I had only project administrator rights, but not site-admin Jira rights, and I only wanted to export one project.

Options I considered

Options 1: Atlassian Jira offers the possibility to export a full Jira instance: Backup Manager.

Atlassian Jira Import and Export options

In my situation, when we tried to perform this action together with the site-admin, we realized that we could not back-up only 1 Jira project, but we have to do it for all the Jira projects from that Jira instance. Because of confidentiality reasons, this wasn’t an option.

Options 2: export to XML. This use to be an option some years ago, but when I checked the options for Import. There is no import from XML.

Option 3: Export all the Atlassian Jira issues as CVS.

Atlassian Jira Project Import steps

Go to
Filters > Advance issue search > remove anything in the search bar.
It will display all the Jira issues from that project.

Now, you’ll want to click on the … on the top right corner, and you want to click Export > Export Excel CSV (All fields)

Considerations

While doing the Export to CSV in Atlassian Jira, you need to know that Jira limits each export to 1000 (one thousand) Jira issues per Export to CSV.

If you export 2 CSV in Jira while merging the two files, make sure you match each column's right information. Here’s are the columns that you are interested in checking correctly: summary, issue key, issue id, parent id, issue type, status, parent, parent summary.

Suppose you want to keep a CSV with all the history of all the Jira issues. In that case, my advice is that if you have 1200 files, for example, instead of exporting 1 CSV file with 1000 Jira issues and the 2nd one with 200 Jira issues, better to have two files of 600 Jira issues because there is a higher chance that they’ll have the same amount of fields. Why? Because Jira creates one field for each comment, sprint number, and attachment. And suppose you have 20 Jira issues in 1 CSV and 1000 in another one. In that case, the chances are that the 20 Jira issues to have all been in just one sprint, have no attachments, and maybe no comments, but in the 1000 Jira issues export will, so merging the two files will be more challenging than just a copy/paste.

On the other hand, the import is limited to 250 Jira issues, so if you have 1000 Jira user stories, you’ll need to import four different files, one by one.

Atlassian Jira Project Import steps

The same as for the Export to CSV of all Jira issues, in the new Jira Instance, go to

Filters > Advance issues Search > Import Issues from CSV

Sounds so simple, right? Well, it is not. If you click on import, you’ll get so many errors and not import many of your Jira issues. Here are the steps for a successful import:

Step 1: Import the Epics (Level 1)

In Jira, there is an issue hierarchy, but each Jira issue contains only information n about the level above. And I can tell you that the cleaner is your Jira setup. The easiest will be to import it.

Here is the standard structure that I use:

Level 1: Epics
Level 2: User stories and Bugs and Tasks
Level 3: Sub-tasks

To obtain a CSV with only Jira Epics, you can either export only the epics from the previous Jira instance or filter the existing CSV by issue type = Epics.

To import the Epics is straight forward: Import issues from CSV.

On the CSV Source file, you select your file with the epics and then click next.

On the Map fields screen, these are the minimum fields that you are interested in selecting:

Epic Name
Summary — mandatory
Issue type
Description
Priority
Labels

Before you begin the Import on the next step, I recommend you to validate the import first:

The Epics import should be straight forward. If you face any issues, don’t hesitate to drop a comment on this post, and I’ll help you.

If you try to import all the Issue types at once, at this step, you’ll get the following warning for Level 2 issues (Stories/Tasks).

WARN - The value [ [MAW-1730] ] can't be added to the Custom Field [ Epic Link ]. The value [ [MAW-1730] ] can't be found or is in the incorrect format

Your Jira issues would still be imported, but they’ll not be linked to the right Epic. If you have over 800 Stories as I did, assigning by hand each Story to the right epic is not an option. Therefore, my recommendation is to import only Epics at this step.

Step 2: Import the User Stories / Bugs/ Tasks (Level 2)

For a successful Level 2 import, you need to do some data manipulation. Go in the CSV file with you, Jira CSV Export, on the column Custom Field (Epic Link). It has a number. Replace that number with the new Epic Link.

Because with Jira Import/Export, nothing is easy, I can tell you that you need to map by hand the old Jira Epic Link with the new one.

Hopefully, you’ll not have more than some tens of Epic.

The way I managed it was to:

make a table of the Epic summary, Old Jira Key, and New Jira key.
select only the column Custom field (Epic Link)
use the Find and replace the exact cell value to replace the old Jira Key with the new one

It is a not so pleasant manual process, but it’s doable fast. Make sure you use the Custom field (Epic Link) because if you use the Parent column, that’s a mix between all the levels, and everything is even more confusing.

Also, pay attention to the same Jira key on the two instances, but for other Epics. The easiest way to avoid this is to have the project index different on the 2 Jira instances. Instead of using MAW, I used AON in the new Jira instance.

When you are done, you can import your CSV with the Level 2 Jira issues, the same way as for Jira Epics.

Filters > Advance issue search > Import from CSV > Select file (make sure you have maximum 250 issues per file > Import.

On the Map fields, you need to select at least:

Summary
Epic Link
Description
Environment (if you know you use it)
Issue Type
Labels
Priority

If you try to import the subtasks (Level 3) in this step, they cannot be imported, and you receive this error:

ERROR - Subtask 'Tile example: A Subtask is Level 3 in Jira Issues hierarchy' doesn't have a valid Parent Id selection. Issue will not be created.

Learn how to import the sub-tasks or any other Level 3 (children of Stories/Level 2) Jira issues on the next step.

Step 3: Import the Sub-tasks (Level 3)

If in your OLD Jira configuration, the bugs are level 3 — as children for User Stories, then you’ll import them in this step.

In the same way, as you updated the parent key to the New Jira instance, you’ll need to do the same thing now. Still, because with Atlassian Jira, the export/import of Jira projects is not easy. To identify the Level 3 Jira issue's parent key, you need to look at another column: Parent ID and Parent Summary. And to make it even more complicated, you need to replace the OLD Parent ID with the NEW Parent Key.

It doesn’t make any sense, I know. It is not documented anywhere, and I wasted a LOT of hours to find it out. I hope this blog post will save you many hours and frustrations.

If you have a few Sub-tasks, Replacing the OLD Parent ID with the New Parent Key might be a quick manual task, but if you have tens or hundreds, I recommend using some automation. Here is how:

1. Export to CSV all the Level 2 issues from the NEW Jira instance. You can identify them by issuetype != epic

2. Open the file in Excel or Google sheets

3. Add a NEW Jira story and add all your Jira issues exported from the OLD Jira instance. To identify the Level 3 issues, you filter for ALL, BUT Blanks. NOW you have two sheets: NEW Jira Stories (sheet 1) and OLD Jira Sub-tasks(sheet 2)

5. in sheet 2 — Bring the Parent Summary columns on the left side of the OLD Jira sub-tasks table, so you find them easier.

6. in sheet 2 — Insert a new column that you call it NEW Parent Key

7. in sheet 2 — Write the following formula: VLOOKUP(D3; ‘NEW Jira Story Sheet1’A$2:B$20; 2; FALSE)

D3 = OLD Jira Parent Summary column
‘NEW Jira Story Sheet1’A$2:B$20 — contains on Column A the summary of the Stories and on column B the new story key (= Parent Key)
2 = you want to display the value of the B column (=the story key = your parent key)
FALSE = you are looking for the exact match of the summary text.

If you inserted the formula correctly, you’d have the OLD Jira sub-tasks mapped with the NEW Jira Stories in this column.

The next step is to import them:

Filters > Advance issue search > Import from CSV > Select file (make sure you have maximum 250 issues per file > Import.

On the Map fields, you need to select at least:

Summary
NEW Parent Key = Parent ID
Description
Environment (if you know you use it)
Issue Type
Labels
Priority

Reminder to validate the import first.

Hopefully, now, if everything runs correctly, you have your sub-tasks linked to the right stories connected to the good epics.

If you face any issues, drop me a message, happy to help you.

If you followed my advice of cleaning the OLD Jira instance before the import, now will be a quick and straight forward update on putting the issues in the good upcoming sprints.

What to do about links between Jira issues?

For me, this sounded like a very tidies job that I didn’t do. I clean up and closed everything before importing things over, and I had only less than 10 Jira issues to link between themselves by hand.

If you need to do it, it must be the same way as above — you need to go on the columns Outward issue link (Cloners) or Outward issue link (Duplicates) or Outward issue link (Blocks) and replace the OLD Issue Key with the new one. You can do that only if you find a way of splitting the imports, so the NEW Outward issue link exists. I find this step as mission impossible and not worth it the effort.

How to update the fields that aren’t imported automatically by Jira?

I used the Atlassian Jira feature of Bulk edit: I identified the issues that need the same update (e.g., the transition of status, story points, assignee, etc.), I query by their key, and I bulk edited them.

How to “Bulk Edit” the status of any other field that is not automatically imported from the Atlassian Jira CSV Import feature?

I do a full export of all the NEW Jira issues and the OLD Jira issues and add them in 2 sheets in the same Excel file.

In the NEW Jira issue sheet, I add two fields: Value that needs modified (Status to be) and CONCATENATE.

In the Status to be column, I insert a

VLOOKUP (summary of NEW Jira issue;’OLD Jira issue sheet2'Summary of OLD Jira issues:status from OLD Jira; 2; FALSE)

This function returns me the status that my issues should have and that I need to update.

In the columns CONCATENATE, I write:

=CONCATENATE(B2;”,”)
Which adds a “,” after each issue key.

I do a filter on all the Done statuses, for example, and then I copy all the CONCATENATE column values. They will look like: “MAW-1, MAW-2".

I for in my NEW Jira > Filters > Advance Issue Search, and I write:
issue key in (MAW-1, MAW-2)

In this way, I get only the issues that need to be updated. And I can edit more than 200 Jira issues at a time using the Bulk edit function on the top right corner.