Migrating from Jira Server to Jira Data Center with Project Configurator

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

On this page:

Migrating from Jira Server to Jira Data Center

This use case presents the same process as our Migrating projects from one instance to another use case, which is applied to each of the source instances being merged to the Data Center. Migrating from Jira Server to Jira Data Center involves upgrading an existing instance to the new Data Center setup and merging your remaining instances into the Data Center instance.

Scenario

Suppose you are a Jira System Administrator with multiple Jira Server instances that you want to move to Jira Data Center, but you need to retain all your project data, including configuration, history, and user mappings. You want to identify one of your Jira Server instances to convert to Data Center, then merge your servers with your new instance as seamlessly and as easily as possible.

Assumptions

It is assumed you have installed Jira Data Center and configured your instance according to Atlassian’s DC installation guide. It is also expected that you are familiar with the concepts of migrating and merging Jira instances as described in the following Atlassian guides: Migrating Jira instances and Merging Jira instances.

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. If importing complete projects, 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 (select multiple projects using the Ctrl or Command keys) on the Export Projects page. 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.

  9. Repeat this process for each of your source instances.

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 Data Center 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.

  7. Repeat this process for each of your export files created for the source instances.