Preparing for migrating projects

Versions

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:
    1. Clone the target instance to a staging server.
    2. Take an XML backup of the source instance.
    3. 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.
    4. 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. 

Licenses

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

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:

• timezone
• 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:

1. Verify that Jira Software is installed on both the source and the target.
2. 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.