---
title: "Migrate projects from one instance to another"
canonical: "https://support.appfire.com/space/PC/197887676/Migrate%20projects%20from%20one%20instance%20to%20another"
format: markdown
---
> Macro (aura-html)

## 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](https://appfire.atlassian.net/wiki/spaces/PC/pages/197853944) and [Support for third-party applications](https://appfire.atlassian.net/wiki/spaces/PC/pages/197887094) 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](https://appfire.atlassian.net/wiki/spaces/PC/pages/198017740) 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](https://appfire.atlassian.net/wiki/spaces/PC/pages/197821626). 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](https://appfire.atlassian.net/wiki/spaces/PC/pages/197887740), 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](https://appfire.atlassian.net/wiki/spaces/PC/pages/197952227) 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. |

4. Type the name of the exported file (include the ".zip" extension) into the **Project File** input box on the *Import Projects* page.
5. Ensure that the **Run a Simulated Import** option is selected.
6. Select any required [import options](https://appfire.atlassian.net/wiki/spaces/PC/pages/198017919). Keep in mind that the default options support 90% of import tasks.
7. Click **Import Projects**.
8. 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.
9. Review the import log and the target instance to ensure the migration was as expected.