Project Configurator for Jira Server and DC

Migrate Projects From One Instance to Another

Suppose you have a group of projects in a Jira instance called SOURCE. You want to move this group of projects to a different instance, called TARGET, where none of those projects exist. The original projects in instance SOURCE are going be abandoned because SOURCE is going to be shut down after the merge.

Setup & Best Practice

Ensure Project Configurator is installed on both your source and target instances. You can install Project Configurator either through the UPM or by downloading the app from the Atlassian Marketplace. Apply your license to the target instance only—​Project Configurator will allow you to export without having a license applied to the source instance. You must have Jira Administration permissions to complete this process.

While we have tried to make Project Configurator as easy to use as possible, there are a few things you should do to ensure a successful import:

  • Make full backups of your source and target databases including attachments.

  • Disable Outgoing Mail to not spam users.

  • Run the Object Dependencies Report before exporting to give you visibility of where objects are used or referenced by other objects in your configuration.

  • Run the Import Conflict Detection report before importing.

  • Run a simulated import, and verify the import will make the changes you expect.

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

  • Perform the configuration promotion out of office hours (it might take some time).

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 the exported zip file has been placed.

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

Importing

  1. Create a folder called projectconfigurator under JIRA_HOME/import in the TARGET Jira installation.

  2. Copy the zip file created in the export to that folder.

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

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

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

  6. Click Import Options.

  7. Select Run First a Simulated Configuration Import, then click Import Complete Project. The following page displays the configuration changes that will be applied to TARGET instance to migrate the projects.

  8. Review the proposed changes, and, if you are happy with them, click Next. When the process is finished, your project(s) will be in the TARGET instance, including their configuration, issues, and attachments.

Congratulations

If you followed along, you have just successfully moved your projects to a different Jira instance. If you would like to see this process in action, watch the video below.