Preparing for migrating projects
These steps are for migrating projects between different instances of Jira Server, and require a 3rd party app Project Configurator for Jira. If you're migrating from Server to Cloud, see Jira Server to Cloud migration resources.
We recommend that Jira versions on the source and target instances are the same. If that's not the case, you should upgrade one of the instances.
However, in some cases, you can work around this limitation.
Migrating between different Jira versions
- If the Jira version on the target instance is earlier than on the source instance, you'll need to upgrade the target instance.
- If the Jira version on the source instance is earlier than on the target instance, you have two options:
- Upgrade the source instance.
- Migrate by using a staging server, following these steps:
- Clone the target instance to a staging server.
- Take an XML backup of the source instance.
- Restore the backup on the staging server. This will erase all content on the staging server, and upgrade the migrated data to a later version.
- Use Project Configurator for Jira to migrate your projects from the staging server to the target instance using the procedure described in this guide.
Disk space requirements
When migrating, you'll export your projects into a ZIP archive that will contain the following information:
- Configuration of the exported projects
- Issues in those projects (including attachments, comments, worklogs, history, and so on)
Before the ZIP archive is created, its components are assembled in a temporary directory, which requires even more space than the final ZIP archive. We recommend that the size of the temporary directory is around 4 times the size of the final ZIP archive.
You can use formulas to calculate the approximate size of the ZIP archive. To do this, you'll need the following information:
- The size of an XML backup of your database.
- The total number of projects in your instance, and the number of projects you want to migrate.
- The size of attachments for the migrated projects. Attachments for each project are stored in separate directories in <Jira-home-directory>/data/attachments, each directory is named after the project's first key. This path is the default directory, you can check it in Jira by going to > System > Attachments.
- Use the following formula:
size of the database * migrated projects/all projects * 1.2
For example, if the size of your DB is 500 MB, and you want to migrate 5 projects out of 20:
500 MB * 5/20 * 1.20 = 150 MB
- Next, check the size of attachments for the migrated projects, and use another formula.
size of the attachments / 4
For example, if the size of your attachments is 300 MB:
300 MB / 4 = 75 MB
The estimated size for the final ZIP archive, using the above examples, would be 225 MB. The disk space for the temporary directory must be around 1 GB, because it must be 4 times the size of the ZIP archive.
Provide the same disk space both on the source and the target instance, because the ZIP archive will be uncompressed on the target instance before being imported to Jira.
Make sure that you have enough licenses for your users in the target instance. If you don't, you'll need to provide more, or deactivate some users after the migration. For more information, see Create, edit, or remove a user.
User management during the migration depends on your specific environment, however, you should consider the following rules:
- Users are mapped from the source to the target instance by usernames (field Username in Jira). If a single person has two different usernames in both instances, you should make them consistent:
- Rename one of the users, or
- If the user is managed in an external directory with LDAP, which has some attribute that is the same for both usernames, you can configure it to act as 'username'.
- Users managed in external directories can be migrated with the following methods:
- Tools specific to external directories (e.g. replicating users across LDAP instances). In this case, you should migrate your users before migrating your projects. They might be referenced in some parts of the projects' configuration (e.g. permissions).
- Project Configurator for Jira. For more information and restrictions, see Specific information for some object types.
- A combination of both.
These considerations also apply to group management.
Matching properties of both instances
Make sure the following properties are the same for both instances:
- locale (especially the rules that define how numbers and dates are formatted into strings)
- the maximum size for text fields (the size in the target instance can be larger than the size in the source instance)
For more information about setting the size limit for text fields, click here.
Names of configuration objects
The migration process will treat configuration objects with the same names in both instances as representing the same thing. It's mostly the case, but sometimes two objects with the same name might be completely different. The configuration coming from the source will overwrite the configuration in the target because it's assumed that the source represents the newer configuration you want to implement. To avoid losing some items:
- Review the names of globally available configuration objects in both instances
- If there are coincidences, check if those name actually represent the same object.
- If needed, rename an object in one of the instances to avoid overwriting it with wrong data.
Project Configurator offers some features that might help you with this issue:
- Import conflict detection – it produces a summary report of all configuration objects in the target instance that will be mapped to objects coming from the source instance. The report also shows where the duplicated objects are used in the target instance.
- "Used by" report – it shows where the configuration objects are used. This is useful if you need to rename, change, or delete any of these objects.
Plugins defining custom field types
Any plugin that defines custom field types in the source instance must also be installed in the target instance with the same version.
Plugins defining workflow extensions (conditions, validators, post-functions)
Any plugin that defines workflow extensions in the source instance must also be installed in the target instance, either in the same or a newer version.
- Workflows from the source instance will be migrated to the target instance. If the required plugins are not there, the workflows might not work.
- If you don't install the plugins, the import might fail because the "create transition" action of the corresponding workflow is run for every issue imported into the target instance.
Migrating Agile boards
Migration of Agile boards is supported, but if you're still on Jira 6, make sure you have Jira Agile 6.7.7, or later. For earlier versions, you won't be able to migrate the boards.
Migrating sprint and ranking data
Migrating sprint and ranking data is supported only for Jira Software. The data from Jira Agile will be ignored.
Language and locale
The source and the target instance must be installed with the same language and locale. Jira Software creates its fields with different names depending on the language settings. This happens even if one of the instances uses English US, while the other English UK (e.g. Epic Color and Epic Colour). For more information, see this issue.
Duplicate and obsolete rank fields
In some cases, an upgrade of Jira Software creates fields of type Rank, which are called Rank (Obsolete). If the projects you want to migrate use these fields, you'll probably encounter errors during the migration. These custom fields are usually locked, which means they must be created or configured by Jira Software (Project Configurator will not create them in your target instance). As a result, your projects in the source and target instance will be using different sets of fields, which breaks the migration.
To avoid these issues, complete the following steps:
- Verify that Jira Software is installed on both the source and the target.
- If there are duplicate or obsolete Rank fields in the source instance, remove these fields and the related rank values. For more information, see Jira KB article and JSW-13098.