Restoring a project from backup

Before you begin

Restoring a project from a backup is not a trivial task. You may be required to change the configuration of your target Jira instance to accommodate the project import. Additionally, the Project Import data mapping can be resource intensive on your hardware and may take a long time to complete, if you are importing a large project. 

 Note: For all of the following procedures, you must be logged in as a user with the Jira Administrators global permission.

Project import restrictions

The Project Import tool will only import a project between identical instances of Jira. That is;

• The version of Jira in which your backup was created must be identical to the version of your target Jira instance, e.g. if your backup file was created in Jira 6.4, then your target instance of Jira must be version 6.4.
• If your instance of Jira had any custom fieldpluginversionmismatchapps installed when the backup file was created, and the custom field was used in your project, then your target instance of Jira must have the same version of the apps installed for the Project Import tool to automatically work.

For more information about extending the Project Import functionality, see Guide - Extending the Jira Import app.

If any of these restrictions apply and you still wish to restore your project from backup, you will need to create a compatible backup file before importing your project by following the appropriate instructions below.

Jira versions do not match

• If your backup file was created in an earlier version of Jira than your target instance of Jira:
  1. Set up a test Jira instance, which is the same version as your target instance of Jira. Make sure that the test Jira instance uses a separate database and index from your target Jira instance.
  2. Import the backup file into a test Jira instance. (This will completely overwrite the test instance.)
  3. Create a new backup file from your test Jira instance. You can now use this backup to import a specific project into your target production instance.
• If your backup file is from a later version of Jira than your target instance of Jira:
  1. Upgrade the version of your target instance of Jira to match the version of Jira in which the backup was created.

Custom fields app versions do not match

• If the custom fields app from your backup is an earlier version than the custom fields app in your target instance of Jira:
  1. Import the backup file into a test Jira instance. Make sure that the test Jira instance uses a separate database and index from your target Jira instance, as the import will overwrite all data in the database.
  2. In your test Jira instance, upgrade your version of your custom fields app to match the version of the app in your target instance of Jira.
  3. Create a new backup file from your test Jira instance.
• If the custom fields app from your backup is a later version than the custom fields app in your target instance of Jira:
  1. Upgrade the custom fields app version of your target instance of Jira to match the version of Jira in which the backup was created.

Restoring a project from Jira Cloud to Jira Server

You cannot import a project directly from Jira Cloud to Jira Server — the importer will display errors about version mismatches. If you want to restore a project from Jira Cloud to Jira Server, follow the steps below:

1. Install a new Jira instance (in addition to the one that you want to import your project into). This will be a temporary instance that is used to store a full Jira import from Jira Cloud. Ensure that the version of this temporary instance matches the version of the Jira instance that you want to import your project into, e.g. JIRA 6.2.
2. Do a full Jira migration from Jira Cloud to the temporary Jira instance. See Migrating from Jira Cloud to Jira Server applications.
3. Export the desired project from the temporary Jira instance.
4. Import the project into your desired Jira instance, by following the instructions in the Restoring your project section below. 
5. (optional) Delete the temporary Jira instance, once the project has completed.

Restoring your project

The Project Import tool will attempt to map the data in your backup file into your target Jira instance. If the project you are restoring does not exist in your target Jira instance, it will create and populate the project with data from your backup. If the project already exists and is empty, it will attempt to populate the data from your backup into the project.

You may wish to carry out the following setup tasks to ensure that your target Jira instance is prepared to receive a project import beforehand. This can improve the time taken to validate the data mappings to your target Jira instance.

If you are confident that your Jira instance is set up appropriately, you can skip straight to the Project Import tool instructions. If there are any problems mapping the data from your backup file to your target Jira instance, the Project Import tool will present validation errors for you to address.

Preparing your target Jira instance

The Project Import tool does not automatically add missing project entities (e.g. user groups, issue priorities, custom field types) or fix incorrect associations (e.g. issue types in workflow schemes), so some manual work is required to set up your target Jira instance so that your project can be restored. If the Project Import wizard cannot find a valid target location for any of the backup project data, it will not be able to restore the project. The instructions below describe the setup activities that address the most common data mapping problems that occur when restoring a project from a backup.

We recommend that you perform as much of the configuration of your target Jira instance as possible, prior to starting the project import. However, if you do not have the information available to complete these setup activities beforehand, the Project Import wizard will inform you of any problems that need your attention. Alternatively, you can import the backup file into a test Jira instance to check the configuration.

1. Setting up the project

If you have a project in your target Jira instance that you wish to restore data into, you will need to ensure that the project is empty, i.e.

• no issues — perform a search to find all issues in a project
• no components — read the Component management page to find out how to view a summary of a project's components
• no versions — read the Version Management page to find out how to view a summary of a project's versions

2. Setting up users and groups

The following types of users are considered mandatory for a project to be imported:

• reporter, assignee, component lead or project lead.

The following users are considered to be optional for a project to be imported:

• comment author/editor, work log author/editor, a user in a custom field (user picker), voter, watcher, change group author (i.e. someone who has changed an issue), attachment author, user in a project role.

The Project Import will attempt to create missing users if they are associated with the project. However, if the Project Import tool cannot create missing mandatory users in your target Jira instance, then you will not be permitted to import the project. This may occur if you have External User Management enabled in your target Jira instance — you will need to disable External User Management or create the missing users manually in your external user repository before commencing the import.

3. Setting up custom fields

As described previously, the versions of your custom field apps must match between your backup and your target instance of Jira for your project to be imported. You need to ensure that you have set up your custom fields correctly in your target Jira instance, as follows:

• Custom Field Type — If you do not have a particular custom field type (e.g. cascading select) installed on your target Jira, then all custom field data in your backup project that uses that custom field type will not be restored. However, your project can still be restored.
  For example, say you have a custom field, 'Title', which is a 'Cascading Select' field type and was used in your backup project (i.e. there is saved data for this field). If you do not have the 'Cascading Select' custom field type installed on your target Jira, then all data for custom field 'Title' (and all other cascading select custom fields) will not be restored.
• Custom Field Configuration — If you do have a particular custom field type (e.g. multi select) installed on your target Jira, then you must configure all of the custom fields (of that custom type) in your target Jira to match the equivalent custom fields in your backup project. Additionally, if your custom field has selectable options, then any options used (i.e. there is saved data for these options) in your backup project must exist as options for the custom field in your target Jira.
  For example, say you have a custom multi select field named, 'Preferred Contact Method', in your backup project with options, 'Phone', 'Email', 'Fax'. Only the 'Phone' and 'Email' were actually used in your backup project. In this scenario, you need to set up your target Jira instance as follows:
  • There must be a field named, 'Preferred Contact Method', in your target Jira instance.
  • 'Preferred Contact Method' must be a multi select custom field type.
  • 'Preferred Contact Method' must have the options, 'Phone' and 'Email' at a minimum, since they were used in your backup project. Please note, 'Preferred Contact Method' in your target Jira could also have additional options like 'Fax', 'Post', 'Mobile', etc, if you choose.
    If you have not configured your existing custom field correctly, you will not be permitted to import your backup project until you correct the configuration errors in your target Jira.
    See Adding a custom field for more information on custom field types and custom field configuration.
• Compatibility with the Project Import tool — Custom fields also need to be compatible with the Project Import tool for the custom field data to be imported. Custom fields created prior to Jira v4.0 cannot be imported by the Project Import tool. The custom field developer will need to make additional code changes to allow the Project Import tool to restore the custom field data. If any of the custom fields used in your backup file are not compatible with the Project Import tool, the Project Import wizard will warn you and the related custom field data will not be imported. All the target Jira system custom fields and the custom fields included in Jira apps supported by Atlassian (e.g. Jira Toolkit, Charting app, Labels app, Perforce app) are compatible with the Project Import tool.

4. Setting up workflows, system fields, groups and roles

In addition to custom fields, you need to correctly configure the project workflow, issue attributes (e.g. issue types) and groups/roles in your target Jira instance for your project to be restored successfully. Please ensure that you have reviewed the constraints on each of the following:

Workflows and workflow schemes:

• The project import process does not import workflows or workflow schemes. If you wish to retain a customized workflow from your backup, you will need to create a new workflow in your target Jira instance and manually edit the new workflow (e.g. create steps and transitions) to reflect your old workflow (note, the default Jira workflow is not editable). You will then have to add this workflow to a workflow scheme to activate it.
• When importing a project, the Create Issue transition and the Issue Created event will be triggered for each issue along with all corresponding postfunctions. If you change the Create Issue transition after the import (for example, setting one of the create issue field values), you may get values that are different from those in the source. As a workaround, you can manually disable postfunctions during the import. 
• Read more about creating and editing workflows in the Working with workflows and Managing your workflows documents. Please note that you may be required to create and edit a new workflow and workflow scheme to satisfy constraints on workflow entities from your backup, as described in the sections below, even if you do not wish to recreate the exact same workflow.

Issue Types:

• If an issue type has been used in your backup project (i.e. there are issues of this issue type), you must set up the same issue type in your target Jira project. You may want to consider setting up issue types for the project instead of globally.
• Workflow schemes — If you have associated an issue type with a particular workflow scheme in your backup project, you must ensure that the same association exists in your target Jira. See the above section on 'Workflow and Workflow Schemes' for further information on how to set up a workflow in your target Jira instance.
• Custom field configuration schemes — custom field configuration schemes can be used to apply a custom field configuration to specific issue types. If you have configured a custom field differently for different issue types in your backup project, you may wish to set up a custom field configuration scheme to apply the same custom field configuration to the same issue types in your target Jira instance. This will help ensure that you do not have a custom field for an issue type that is configured incorrectly (e.g. missing an option, if it has multiple selectable options), as described in the 'Setting up custom fields' section above.

Statuses:

• If an issue status has been used in your backup project (i.e. there are issues with the status), you must set up the same status in your target Jira project.
• Workflow schemes — If you have linked a status into a particular workflow scheme in your backup project, you must ensure that the same association exists in your target Jira. See the above section on 'Workflow and Workflow Schemes' for further information on how to set up a workflow in your target Jira instance.

Security Levels:

• If an issue security level has been used in your backup project (i.e. there are issues with this security level), it must be set up in your target instance of Jira. If you did not create an existing empty project, we recommend that you do so and set up the appropriate security levels for the project (via an issue security scheme).
• Issue security schemes — Not applicable. It does not matter which users, groups or project roles are assigned to which security levels, as long as the appropriate security levels exist (please see the constraints on security levels in the 'Setting up entities and types' section).

Priority:

• If an issue priority has been used in your backup project (i.e. there are issues with this priority), it must be set up in your target instance of Jira.

Resolution:

• If an issue resolution has been used in your backup project (i.e. there are issues with this resolution), it must be set up in your target instance of Jira.

Issue Link Type:

• If an issue link type has been used in your backup project (i.e. there are issues associated by this link type), it must be set up in your target instance of Jira.

Project Role:

• If a project role has been used in your backup project (i.e. there are users/groups assigned to this project role), it must be set up in your target instance of Jira.
  (Note: The Project Import tool will copy across the project role membership from your backup project to your target Jira instance, if you choose. See the Project Import section for further details).

Group:

• If a user group has been used in your backup project (i.e. there are users in this group), it must be set up in your target instance of Jira.

5. Setting up links

While the Project Import tool preserves the existing issue keys from your backed up project during the import process, the tool will also automatically create all issue links between issues within your backed up project. It will also try to create links between the backup project and another project, as long as the other project already exists in your target Jira instance with the relevant issue keys. If the source/target of a link cannot be found (i.e. the entire project or the particular issue may be missing), the link will not be created although the project will still be imported.

Note that the Project Import tool will create issue links between projects in either direction (source to target, or target to source). This means that if you import two projects from the same backup file, the second project import will create all of the links between the two projects that were missing from the first project import.

Once you have completed as many of the setup tasks as you are able to, run the Project Import tool.

Project Import

Restoring your project is a four step process:

1. Specify the backup file
2. Select a project
3. Review data mapping validations
4. Verify the restored project

If you start the Project Import tool, we strongly recommend that you complete all steps of the wizard before performing any other activities in Jira. Please be aware that it can take some time to validate the data mappings and then import the project.

You will most likely need to navigate away from the Project Import wizard to correct your Jira configuration, as advised by validation errors in the wizard. If you have to navigate to other pages in Jira to correct your Jira configuration or for other activities, you should:

• (recommended) open a separate session of Jira in a new browser window/tab. When you return to the Project Import wizard in the original browser window/tab, you can use the 'Refresh validations' button on the validation screen to re-validate the data mappings; or,
• wait until the progress bar completes for the step you are currently in, before navigating elsewhere in Jira. The state of the Project Import wizard will be saved until you log out of Jira, your user session expires or you commence a different project import. You can resume your project import by returning to the Project Import page (via the main Administration menu) and selecting the 'resume' link on the first page of the wizard.

1. Specify the backup file

To start the Project Import tool:

1. In the upper-right corner of the screen, select Administration  > System. 
2. Select Import & Export > Project Import to open the Project Import wizard page.
3. Specify the path and name of your backup file in the 'File name' field. Your backup file must be an XML or ZIP file (as exported by Jira).
4. Copy the attachments from the path where you have backed up the attachments to the 'Backup Attachment Path' shown in the import window. This path is under the Jira home directory of the instance. Please not that if file attachments are not enabled in your target Jira instance you will not see the path to which you need to copy the attachments from the backup.
   Note: You can choose to not copy the attachments to the 'Backup Attachment Path'. If so, you will be able to restore your project from backup, however it will have no attachments associated with it. Please note, you cannot restore your attachments separately if you do not restore them as part of the project import, as the database entries for the attachments will be missing.

2. Select a project to restore

1. Select a project to restore from the 'Projects from Backup' drop-down. This drop-down will list all of the projects contained in your backup file.
2. If you have a valid project to restore from your backup, and your target Jira instance has an existing empty project, then the 'Overwrite Project Details' option will display. Select the 'Overwrite Project Details' option if you want to overwrite the project details of the existing empty project with the project details from your backup. The project details are the Name, URL, Project Lead, Default Assignee and Description of the project, as well as any project role members set up on your project. If there is no existing empty project in your target instance of Jira, this option will be checked and disabled as the Project Import will create the project with project details from your backup file.

3. Review data mapping validations

1. The Project Import wizard will attempt to validate the data mappings required to import your project from the backup file. You can review the validations at this step of the wizard and modify your target Jira instance as required.
   • A tick symbol ( ) means that there are no problems with mapping these entities.
   • An exclamation mark symbol ( ) means that there are problems with the data mapping that you should review before importing the project, but the project can still be imported. For example, a missing optional user that cannot be created automatically by the Project Import tool.
   • A cross symbol ( ) means that there are problems with the data mapping that must be fixed before you can import the project. For example, an Issue Type that is used in the backed up project is missing in your target Jira instance.
2. The 'Preparing your target Jira instance' section on this page lists the common data mapping errors.
3. Once you have resolved the data validation errors as required, click 'Import' to commence the import of data from your backup file.

4. Verify the restored project

1. Once the Project Tool has finished running, click 'OK' to navigate to the restored project. You should verify that the issues, components and versions have been restored correctly. You should also check that any custom field data and links have been restored correctly.
2. Check that your attachments were correctly restored from your attachments backup directory.

What if something went wrong?

• If your project import did not complete, you can refer to the Jira log file. The Project Import tool will log details of the operation to this file, including any unexpected errors and exceptions, e.g. database locked out, disk full, etc.
• If your project import completed but did not restore your project as expected, you may wish to attempt to fix the problem manually in your target Jira instance. You may also wish to try deleting the project in your target Jira instance and re-importing it from backup, paying special note to any warning validations (e.g. users that will not be added automatically).

If you cannot resolve the problem yourself, you can contact us for assistance. Please see the 'Need help' section below for details.

Need help?

Need further help? You can raise a support request in the Jira project at https://support.atlassian.com for assistance from our support team. Please attach to the support case:

• the backup file you are trying to import projects from, and
• the following information from your target Jira instance:
  • your log file
  • an XML backup of your target Jira instance
  • a copy and paste of the entire contents of the System Info page (accessed via the Administration tab), so that we know the details of your Jira configuration.

You can anonymize the XML backups if your data contains sensitive information.