Background
The full backup and restore operations supported by Jira are relatively straightforward and can be summed up as:
- Backing up data in Jira is performed in two different stages:
- Database Contents (the recommended option would be using Jira's XML backup utility; it is also possible to use native database backup tools);
- "data" directory.
- And the Restoring data process which is typically conducted towards the end of migrating Jira applications to another server or splitting Jira applications across multiple servers.
For restoring projects, Jira offers the "Project Import" tool which allows partial, project imports (i.e. importing a specific project from a previous backup).
This tool has some limitations though; it cannot transfer apps/add-ons related data between instances unless apps are prepared for it.
Fortunately, since v3.3, Xray is able of taking advantage of this mechanism; on previous versions, issues would be restored but the testing data wouldn't.
Overview
Since Xray v3.3, you can use Jira's "Project Import" tool in a seamless manner to import projects containing Xray related data. As simple as that.
Xray actively participates in the import process by extending the Jira's project import mechanism and working out how the missing data is mapped.
If we have an older version of Xray please update it in order to be able to perform the project backup&restore.
Project restoring is used in several scenarios; for example:
- for copying a project from one Jira instance to another Jira instance (e.g. from staging to production, or from internal to a DMZ instance)
- to restore a project upon some mistake/data loss has been done in that project within an existing Jira instance
Please note
Restoring a project from a backup is particularly useful if you do not wish to overwrite the existing projects or configuration of your Jira instance by importing the entire backup.
As per Atlassian recommendation, if you wish to restore a project from a backup file into a new empty Jira instance, we highly recommend that you do not use the Project Import tool. Restoring the entire backup file into the new instance and then deleting unwanted projects is much simpler in this scenario, as you will retain the configuration settings from your backup. Instructions on moving a project to a new instance are available on the splitting a Jira instance page from Atlassian. Projects can be deleted via the 'Projects' page in Jira, which is accessed from the '*Administration' menu.
Before Using the Project Import Tool
Restoring a project from a backup is not a trivial task and you must be logged in as a user with the Jira Administrators global permission.
There are some important aspects to take into consideration before importing a project:
- You may be required to change the configuration of your target Jira instance to accommodate the project import;
- Is strongly recommended that you perform a full backup of your target Jira instance before attempting to restore a project into it;
- 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.
Requirements and Limitations
| Notes | Additional information |
|---|---|
Your backup file must have been created using Jira's backup tool. You cannot import a project from a backup using your native database tools. | |
The version of Jira in which the backup was created must be identical to the target Jira instance. It is recommended to have also the same version of the apps on the target JIRA instance. | |
If the instance of Jira had any app/add-on having their own custom field 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 app installed for the Project Import tool to automatically work. | |
The Project Import tool will lock out your instance of Jira during the actual data import (not during the validations). Ensure that your instance does not need to be accessible during this time. | |
| You cannot import a project directly from Jira Cloud to Jira Server. The importer will display errors about version mismatches. | More information on migrating information from Xray Cloud to Xray server soon. |
When importing test runs from modular tests, the test run mementos from test calls belonging to other projects won't be imported. Ensure that the called tests belonging to other projects are imported first and then proceed with the import of the project containing the modular tests. If there are two-way dependencies between two projects regarding modular tests then the test run mementos for those modular tests won't be imported leading to incoherent test runs. |
How to backup a project
Jira does not provide a project level backup utility; instead, it provides a global backup utility available in System > Import & Export > Backup System.
This utility makes a zipped content of a XML backup, that includes database contents and other data such data. However, some other data, such as attachments, won't be part of that zip; thus, you need to backup them by hand. More info on this procedure here.
Having both the zipped XML backup along with the "data" contents, you can then do project level restoring afterward.
Restoring a project
Jira's Project Import tool can create a project if one does not exist in your target Jira instance but it does not recreate any configuration settings that affect the data (e.g. screen schemes).
If you wish to retain any configuration settings from your original project, is recommended that you create an empty project in your target instance with the necessary configuration settings before importing the data from your backup project.
If the project you are restoring does not exist in your target Jira instance, the Project Import tool will create and populate the project with data from your backup.
Please note
Ensure that your target Jira instance is prepared to receive a project import beforehand, namelly in terms of configurations. More information here.
Importing a project
If you are confident that your Jira instance is set up appropriately, you can skip straight to the Jira's Project Import tool full instructions.
Here is a quick overview of the Project Import required steps after you open the Jira Project Import Tool in the Jira target instance.
Please note
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.
Select Backup & Select Project
Specify the backup file, select a project to restore and proceed to the "Import Validation" step.
Backup
Make sure you have done a backup of the attachments in the origin Jira instance and moved it to the restore attachments directory in the target Jira instance.
Jira uses this to import the issue attachments, Xray will use it as well but to restore Test Run evidence and step attachments.
The Import Tool will tell you where the restore attachments directory is located.
The Import Validation phase
In this step, you might get some messages about the necessary Jira related configurations.
Xray can also display some warning messages in this stage, namely about dependencies with other projects but these do not prevent the import process from continuing.
Xray warning messages
An example of this would be when you have a Test Plan associated with multiple Tests but the Test Plan and its Tests are in different Jira projects.
In such cases, Xray warns about this project dependencies but if you go ahead after the import is finished those dependencies will be missing because the dependency projects were not there yet. If you decide to import these other projects later, then XRAY will rebuild the dependencies.
On the other hand, if everything is in one project (Requirements, Tests, Test Executions, Test Plans, etc.), then you may not see this warning messages since everything will be imported at once.
If your project has some dependencies to other projects, then you also have to import those projects.
In the image below, you’ll see an example where the project “REQ”, that is currently being imported, had some dependencies to the project “XTP2”.
Afterward, when the import of “REQ” is finished, we need to import “XTP2”. Xray then imports the entities of “XTP2” and rebuilds all the dependencies between “REQ” and “XTP2”.
Import Project & Summary
After proceeding and finishing the Import Project step, you finally get to the Summary step where alongside with a sum up of Jira generic information, Xray will also display how many entities were imported.
