Migrate projects from one instance to another

Owned by Rosen Marinkov
Last updated: May 21, 2024 by Stanley Neychev
5 min read

On this page:

Migrate projects from one instance to another

This use case depicts a migration task where a Jira System Administrator wants to merge a group of projects and their configuration with another instance. The methods in this scenario can apply to any migration task where you want to move complete projects (project data and configuration objects). If you are considering how this use case represents your migration goals, it is assumed that you understand how Project Configurator handles project configurations and data. It is also assumed that you are a Jira System Administrator with good knowledge of the setup and state of your instances.

Scenario

Suppose you have a group of projects in a Jira instance called SOURCE. You want to move this group of projects, including their configuration and data, to a different instance called TARGET, where none of these projects exist. You plan to abandon the SOURCE instance when you have completed the migration because it is no longer needed.

Prerequisites

  • Verify that Project Configurator supports the objects that you would like to migrate. Supported objects are listed in our Supported object types and Support for third-party applications pages.

  • The same version of Project Configurator is installed on both instances. If not, then the version on your target instance should be more recent than your source. You must have a licensed version to complete an import on a production instance.

  • Any apps used to configure objects in the source instance must also be installed on the target, ensuring the versions are the same.

  • Your Jira locale and language are the same for both the source and target instances.

  • It is recommended that your Jira versions be the same for both the source and target instances. Project Configurator allows you to import data from an earlier version of Jira. However, the greater the difference in Jira versions between the instances, the higher the possibility of issues arising from the migration.

Instance setup before an export

  • Run the object dependencies report on your source instance. This gives you visibility of where objects are used or referenced by other objects in your configuration. You can use this information to clean up your instance and to help you make the best choices for your export options.

  • Ensure that the naming schemes for user accounts are consistent between the source and target instances. You should not have the same user accounts with different user names, e.g., jsmith and jan.smith. If you are using an external user directory such as LDAP or Active Directory, ensure that these users exist in the target instance before the migration.

  • If you are cleaning your instance before export, you can use the Jira built-in XML backups to first back up your source instance.

Exporting

  1. Open your SOURCE Jira instance.

  2. Select Add-ons from the Jira Administration menu, then select Export Projects under Project Configurator in the left sidebar.

  3. Make your selection(s) on the Export Projects page—​select multiple projects using the Ctrl or Command keys. To export all projects, select the Select All Projects checkbox.

  4. Choose Complete Project from the Export Mode options.

  5. An export file name is created for you. You can change this to something more memorable if you wish.

  6. Select any required changes to the default export options. It is worth noting the default settings will work well for 90% of exports. You may also save your configuration options for future export tasks.

  7. Click Export Projects. The app downloads a zip file for the selected projects. The export could take some time, depending on the number, complexity, and size of the selected projects. When complete, a summary of the export is displayed, including the location in the SOURCE server where a copy of the zip file has been placed.

  8. Note the location and the file name for use in the importing process.

Instance setup before an import

  • Make a full backup of your target instance, including attachments.

  • Perform the migration out of office hours whenever possible and announce the planned downtime to your users. The larger the amount of data, the longer the process takes. This could mean running the process over multiple days and splitting your projects across multiple export/imports.

  • Disable Outgoing Mail to not spam users.

  • Run a simulated import, and verify the import will make the changes you expect. This report helps you visualize which objects will be created, modified, or result in errors. You can then disable any actions you do not want to apply. You can also investigate any errors and make any necessary changes to the target instance. At this stage, you may discover that you need to resolve issues in the source instance and build a new export file. You can review our troubleshooting articles in the Project Configurator Knowledge Base to help you anticipate and resolve some common errors.

  • Perform the import on a test instance before moving your changes to a live environment.

Importing

  1. Open a Jira session as a system administrator on the TARGET instance.

  2. Select Add-ons from the Jira Administration menu, then select Import Projects under Project Configurator in the left sidebar.

  3. You have two options when uploading your zip file:

Option

Required Actions

Server Upload - useful for larger files

Create a folder called projectconfigurator under JIRA_HOME/import in the TARGET Jira installation. Copy the zip file created in the export to that folder. If your server is Linux-based, ensure that the zip file permission is set so that it is owned by the same operating system User and Group under which Jira is running. Select Server Upload in the Import Projects screen.

Browser Upload - uploads the file directly from its original saved location on your computer, providing quicker access to locally stored files

Select Browser Upload in the Import Projects screen.

  1. Type the name of the exported file (include the ".zip" extension) into the Project File input box on the Import Projects page.

  2. Ensure that the Run a Simulated Import option is selected.

  3. Select any required import options. Keep in mind that the default options support 90% of import tasks.

  4. Click Import Projects.

  5. The Import Simulation results are displayed once the process is complete. The displays the configuration changes that will be applied to the TARGET instance. Review the proposed changes, and if you are happy with them, click Apply Configuration. When the process is finished, your project(s) will be in the TARGET instance, including their configuration, issues, and attachments.

  6. Review the import log and the target instance to ensure the migration was as expected.