How-To-Guide for Project Configurator: Five simple steps to easier Jira project migrations

Using Project Configurator's improved functionality and user interface

This how-to guide will show how to easily complete a full Jira project migration by utilising Project Configurator for Jira's new version 3.0 features.

If you prefer to watch videos, take a look at this Jira project migration demo video. Otherwise, keep reading for a step by step breakdown.

Zed Inc purchases Alpha Co

Company acquisitions can be a complicated time for those involved. One person who has a big task is the Jira Admin who is responsible for preparing their Jira instance for the newly formed company and teams. Usually, this involves merging two Jira instances into one by migrating several projects across from one Jira instance to another.

For the purposes of this post, we are going to use a company acquisition, let's say Zed Inc has purchased Alpha Co, and we need to move Alpha Co’s projects across to Zed Inc’s Jira instance in the quickest and most accurate way possible.

Stage 1 - Understand your Jira instance using PC’s “Used By” report

The first recommended step when migrating projects is to utilise Project Configurator’s ‘Used-By’ report. This report will show you all objects that are directly or indirectly part of the configuration of any project in your instance, and where they are being used or referenced by other configuration objects. This helps give you better visibility over your Jira instance and the details of the projects you are planning to migrate. Enabling you to make any necessary changes to these projects prior to the migration.

PC Used by report

Fig: "Used-by" report showing custom field information and what projects they are related to.

Stage 2 - Export Jira Projects

Location: Alpha Co’s Jira instance
Task: Export the projects that we want to migrate

The next step is for you to agree on and locate Alpha Co’s projects that need to be migrated to Zed Inc’s Jira instance.

Once identified you can navigate to the PC import tool via the Apps menu.

From here, we can select the projects we want to import and the required export settings. By default, PC will select the recommended options that cover 90% of the migration situations you’ll come across. 

Fig: PC export phase and settings options.

Once the file has been downloaded we can move on to Stage 3. Start by opening the target Jira instance - Zed Inc’s Jira.

Quick Tip!

If you get stuck on any step you can use the in-app links to take you right to the relevant support page in our documentation.

PC3.0 screenshots In app links

Fig: In-app documentation links and a view of the documentation.


Stage 3 - Import Jira Projects into Zed Inc’s Jira instance

Location: Zed Inc’s Jira instance
Task: Import the projects into Zed Inc’s Jira

Stage 3.1 - Import settings

At this stage, we will import Alpha Co’s projects into Zed Inc’s Jira instance. Navigate to the import project section of PC via the addons menu.

Select your desired settings, once again these are pre-selected to meet most situations. 

Stage 3.1.1 - Simulated Import

We highly recommend running the Simulated Import prior to the actual import. This will help you map your migration to ensure Alpha Co’s projects fit well into Zed Inc’s instance.

Another useful feature to note is the ability to opt-out or ‘skip’ certain objects from the import. This is helpful as you may have exported an object that you no longer need to import. Rather than returning to the export phase to repeat that stage, you can simply exclude it here.

PC skipped object plus results 3

Fig: Import phase - showing the option to skip certain objects, for example, Groups.

Once happy with your settings, hit ‘Import Complete Project‘ to start the Simulated Import.

Stage 3.2 - Simulated Import Report

The Simulated Import Report page shows you a variety of vital information to help you ensure your migration is a success. PC 3.0’s import functionality is significantly more powerful than previous versions of PC, allowing you to identify and resolve more import issues than ever.

You’ll find the report is presented in a tree-like structure. This gives you the ability to expand or collapse each section to see as much, or as little, information as you need about each of the import objects.

Fig: Expand or collapse the tree to view more or less information.

The new colour coding scheme we’ve implemented makes it really easy to know what is due to happen to each object when the actual import is completed.

PC LegendFig: Import report legend.

 To explain the tree legend in more detail:

  • Modifies existing objects
    • These are objects that already exist in the target Jira instance and will be modified during the real import.
  • Creates new objects
    • These objects don't exist yet in the target Jira instance, so they will be created during the import.
  •  Warnings
    • Yellow warnings show objects that you may want to pay attention to. However, these warnings will not disturb your actual import.
    • If you do have any concerns over these objects, PC now provides the ability to deselect objects directly from the Simulated Import Report. As with skipping objects at the import settings page, this removes the need to repeat the export phase before importing again.
    • Once an object is deselected, it is recommended that you use the ‘Recalculate’ function to check those removed objects have no dependencies or negative consequences on other objects. 

Fig: How to deselect objects and recalculate the simulated import.

  • Errors
    • Highlighted in red, these objects have something wrong with them and therefore will not be migrated into your target instance.  

PC error screen
Fig: An example of an import error (highlighted in red).

    • By skipping objects that have errors associated with them you’ll save significant time compared to previous versions of PC. Previously, if an error occurred, the import would have stopped mid import, requiring you to resolve any errors before re-running the import. As you can imagine this process could have taken multiple attempts to complete successfully.
    • Now an import will continue, skipping those troublesome errors but still giving you full visibility of them in the final import report. From there you could resolve the errors, if required.

Stage 4 - Final Import

Now that we have tested our import using the Simulated import tool, we can continue to the actual import where Alpha Co’s project will be migrated into Zed Inc’s Jira.

To initiate this we need to select “Apply Configuration”.

Once completed we can review the final import report. This is similar to the Simulated Import report but this time the migration has occurred for real; if all went as planned this report should look the same as the Simulated Import report from earlier. If not, any errors that occurred will be highlighted allowing you to investigate them further if needed.

Final import report

Fig: The final import report.

Now that we have successfully migrated Alpha Co’s projects into Zed Inc’s Jira, the newly formed team can get to work with their familiar project data and settings. Making this transition as seamless as possible for the team allows them to become productive from day one. 

Stage 5 - Ongoing Responsible Jira Change Management

However, as all Jira Admins will know, change is always just around the corner. PC is also the ideal tool to facilitate your ongoing Jira Change Management process. Using a very similar process to the one described above, you can continuously promote proposed configuration changes from a Testing/Staging environment into your live Production instance.

For more information on this process please see this step by step video guide.

Try Project Configurator for Jira 3.0 today

We hope with this guide, and the new PC 3.0 features, you’ll be well on your way to saving yourself significant time and stress when migrating projects and making ongoing configuration changes.

To get started with your own migrations and configuration changes download the latest version of Project Configurator for Jira via the Atlassian Marketplace today.

Try PC 3.0