Jira Cloud Migration Assistant pre-migration checklist

The Jira Cloud Migration Assistant automatically reviews your data for common errors. It will check that:

all users have valid and unique email addresses
none of the project names or keys conflict with project names or keys that already exist in Cloud
the migration assistant is up to date

However, it won’t check for everything, so you’ll also need to run through this pre-migration checklist before starting a migration.

Before you begin

To complete the pre-migration checks, you may need:

access to the Jira Server/Data Center or Cloud user interface
access to an unzipped Jira Support ZIP. Learn how to create a Support ZIP file
access to an unzipped Jira XML backup. Learn how to create an XML backup
to run SQL queries on the source instance

1. Create a user migration plan [mandatory]

External directories

Sync your active external user base to make sure all users and groups are migrated properly as part of your user strategy. This also ensures that data remains linked to the correct users during the migration. Learn more about user migration strategies

If you’re using an external identify provider to manage your users, make sure they are active and synced to Jira before migrating.

Sync using the Jira Server user interface

Select the cog icon in the top right corner.
Select User Management.
Select User Directories.
Select Sync.

Verify using your Support Zip

You can cross-reference the Epoch timestamps in a site such as https://www.epochconverter.com/.

Make sure directories that are needed are set to Active.

Last External Users Sync Verification

grep "com.atlassian.crowd.directory.sync.laststartsynctime" <Support Zip Location>/auth-cfg/directoryConfigurationSummary.txt


Example Output: 
	com.atlassian.crowd.directory.sync.laststartsynctime: 1586922783853
	com.atlassian.crowd.directory.sync.laststartsynctime: 1586911983804
	com.atlassian.crowd.directory.sync.laststartsynctime: 1579025414214

Active External Directory Verification

grep "Active:" <Support Zip Location>/auth-cfg/directoryConfigurationSummary.txt


Example Output: 
Active: true
Active: true
Active: true
Active: false
Active: true

Note that the Jira Cloud Migration Assistant migrates:

all users and groups
users and groups related to the selected projects

2. Check your Jira Server version [mandatory]

Make sure Jira is running on a supported version, otherwise, the Migration Assistant will not work. Learn more about the supported versions

Verify using the Jira Server user interface

Select the cog icon in the top right corner.
Select System.
Select System Information in the left navigation panel.
Look for Jira Version.

Verify using your Support Zip Product Version Verification

grep "<product name" <Support Zip Location>/application-properties/application.xml
 
 
Example Output:
<product name="Jira" version="8.7.1"/>

3. Fix any invalid and duplicated email addresses [mandatory]

Invalid or duplicated email addresses are not supported by Jira Cloud and can’t be migrated with the Jira Cloud Migration Assistant. To avoid blocking your migration, you can use the assistant to identify such email addresses and then either fix them manually or apply one of the suggested options to fix them automatically during migration, for example by merging duplicates or deactivating related users.

Open the Jira Cloud Migration Assistant.

In the Assess and prepare users card, select Begin assessing. You’ll be moved to the page with empty results.
To start the assessment, select Begin assessing. Once the assessment is complete, you’ll see the number of email addresses that don’t meet the requirements. You can then view the details and choose how you’d like to fix these addresses.

Learn more about assessing and preparing users

4. Make sure you have the right permissions [mandatory]

Ensure that the user who runs the migration:

has the system admin permission on the server instance
exists in the target cloud site
has the organization admin role in the Jira Cloud
and has necessary disk access permissions for the <Jira home directory>/export directory on your server. This directory is used for creating temporary files during the migration process.

5. Check for conflicts with group names [mandatory]

Make sure the groups in your Cloud site don't have the same name as any groups in your Server site, unless you're intentionally trying to merge them. Learn how the Migration Assistant manages group name conflicts

Additionally, there might be some migration scenarios that result in your Server site ending up with add-on users. Add-on users are not common in the Server world and they might cause a few issues during the migration to Cloud. Before migrating, delete or update any of these add-on users.

Verify using SQL (tested on Postgres)

Use the query below to find any of these users and either delete them or update their emails to something other than @connect.atlassian.com:

--ADD-ON USERS - TESTED ON POSTGRESQL
select * from cwd_user where lower_email_address like '%connect.atlassian.com%';

6. Update your firewall allowance rules [mandatory]

The migration assistant connects to Atlassian domains in order to run the migration. If any domain gets blocked by either a firewall or a reverse proxy, the migration will fail. Ensure that IP addresses and domains for Atlassian Cloud products won’t be blocked by any security rules before running a migration.

Learn more about IP addresses and domains used by Cloud products

7. Determine how you’ll migrate apps [mandatory]

You can migrate app data using the Jira Cloud Migration Assistant. Contact the Marketplace Partner (app vendor) for the apps you want to migrate to check if the migration path they have built supports the Jira Cloud Migration Assistant, and for advice on how to migrate their data efficiently.

Learn more about assessing and migrating apps

8. Check your public access settings [mandatory]

You can configure your Jira Server or Jira Cloud site to be publicly available to the internet. Unless you intentionally want your content to be public, you should review your project permissions. If you have projects that are publicly available in Jira Server, remove their anonymous access setup before migrating to Cloud. You can always make these projects public again after migrating.

Verify using SQL (tested on Postgres)

Projects

This will flag projects that have any permission set to Anyone.

SELECT p.id, p.pname, ps.name, sp.permission_key FROM project p
INNER JOIN nodeassociation na ON
p.id = na.source_node_id
INNER JOIN schemepermissions sp ON
na.sink_node_id = sp.scheme
INNER JOIN permissionscheme ps ON
na.sink_node_id = ps.id
WHERE na.source_node_entity = 'Project'
AND na.sink_node_entity = 'PermissionScheme'
AND sp.perm_type='group'
AND sp.perm_parameter is null;

Filters

This will get a list of filters which has share type as "share with everyone" (i.e. global)

// get list of filters which has share type as "share with everyone" (i.e. global)
SELECT sr.filtername, sp.sharetype AS current_share_state, sr.username AS owner_name, sr.reqcontent AS JQL
FROM searchrequest sr
INNER JOIN sharepermissions sp ON sp.entityid = sr.id 
WHERE sp.sharetype='global' and sp.entitytype ='SearchRequest';

Agile Boards

This will get a list of Agile boards which has share type as "share with everyone" (i.e. global)

// get list of Agile boards which has share type as "share with everyone" (i.e. global)
SELECT DISTINCT "rv"."NAME" as "Board Name", sr.filtername, sp.sharetype AS current_share_state, sr.username AS owner_name
FROM "AO_60DB71_RAPIDVIEW" as rv 
INNER JOIN searchrequest sr ON sr.id = rv."SAVED_FILTER_ID"
INNER JOIN sharepermissions sp ON sp.entityid = sr.id 
WHERE sp.sharetype='global' and sp.entitytype ='SearchRequest'; 

Dashboards

This will get a list of Dashboards which has share type as "share with everyone" (i.e. global)

// get list of Dashboard which has share type as "share with everyone" (i.e. global)
SELECT DISTINCT pp.id as Dashboard_Id, pp.pagename AS Dashboard_name, sp.sharetype AS current_share_state, pp.username AS owner_name
FROM portalpage pp
INNER JOIN sharepermissions sp ON sp.entityid = pp.id 
WHERE sp.sharetype='global' and sp.entitytype ='PortalPage'
ORDER BY pp.id;

9. Review your Server setup [mandatory]

Application memory (JVM heap size)

Depending on the number of issues or projects to be migrated, Jira Server might experience an OutOfMemory error that can crash the entire migration. To prevent this, ensure that your application is running with at least 4GBs of Heap Allocation. Learn how to increase Jira's application memory

Benchmarking based on the general instance dataset size vs. resources (CPU cores, RAM, Heap)

The table below lists size profile definition of an instance.

Extra large	32 CPU, 64 GB RAM, 31 GB Heap
Large	16 CPU, 32 GB RAM, 16 GB Heap
Medium	8 CPU, 16 GB RAM, 8 GB Heap
Small	4 CPU, 8 GB RAM, 4 GB Heap

Large and Extra large can be chosen based on the proximity to the maximum/minimum values in the dataset sizings and their corresponding instance profiles.

Also, learn more about infrastructure recommendations for enterprise Jira instances on AWS.

Open Files limit

Also, make sure to review your Open Files limit. Ideally, it should be as close as possible to 32768. Getting the number of Open Files set to your system may vary depending on the Linux distribution. If unsure of how to check that via system commands, generate a Support Zip, open the application-properties/application.xml file and search for <max-file-descriptor>. Adjust the value accordingly. This doesn’t apply to those running Windows.

Learn more about the 'Too many open files' error

Verify using your support zip

Application memory (JVM heap size)

Ensure the value of the Xmx and Xms is at least 4096m or 4g:

grep -i "xmx"" <Support Zip Location>/application-properties/application.xml
 
 
Example Output:
<JVM-Input-Arguments>-Djava.awt.headless=true -Datlassian.standalone=JIRA -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Xms4g -Xmx4g 

Open Files limit

Ensure the value of <max-file-descriptor> is close to 32768:

grep -i "<max-file-descriptor>"" <Support Zip Location>/application-properties/application.xml
 
 
Example Output:
<max-file-descriptor>32,000</max-file-descriptor>

Alternative ways to verify heap sizing

Linux

Go to /jira-installation-directory/bin/setenv.sh file and confirm both parameters below are greater than 4096m or 4g (if it was set in gigabytes instead of megabytes):

JVM_MINIMUM_MEMORY="4096m"
JVM_MAXIMUM_MEMORY="4096m"

Windows - not running as a service

Go to /jira-installation-directory/bin/setenv.bat file and confirm both parameters below are greater than 4096m or 4g (if it was set in gigabytes instead of megabytes):

JVM_MINIMUM_MEMORY="4096m"
JVM_MAXIMUM_MEMORY="4096m"

Windows - running as a service

Learn how to increase Jira application memory

Database connection pool

Jira uses a database connection pool (DBCP), based on Apache Commons DBCP, to manage JIRA's access to its underlying database. Whenever Jira needs to access (read or write) its database, a database connection is required.

During normal usage, Jira’s database connection pool may run smoothly. But, when adding Jira Cloud Migration Assistant on top, it may at times exhaust the database connection pool if it’s not properly sized.

If that happens, Jira will suffer a major performance impact, which will impact the entire application, not only the Migration Assistant. The usual workaround is to increase the database connection pool size.

Fix

By default, Jira has 20 as the maximum DB connection pool size. A common fix will be to increase that number in increments of 10, in order to fine-tune the connection pool to accommodate both Jira and the Migration Assistant. Increasing your maximum DB connection pool size up to 40 should be sufficient to support your migration needs.

To manipulate the DB connection pool and increase its size, see the reference links below:

10. Check your Advanced Roadmaps Shared Teams [recommended]

Customers migrating into Jira Cloud will have their Shared Teams converted to Atlassian Teams which require membership. Learn more about Atlassian teams.

At migration, teams with no members are assigned a default member; this member is a user that has org admin privileges and/or Team management access.

To avoid unexpected changes to Teams, we recommend reviewing your Shared Teams prior to migration.

Find zero member teams using SQL (tested on Postgres)

This will find any shared teams that have no members.

select "TITLE"
from "AO_82B313_TEAM"
where "ID" not in (
  select distinct "TEAM_ID"
  from "AO_82B313_RESOURCE" r
    inner join "AO_82B313_PERSON" p on r."PERSON_ID" = p."ID"
    inner join app_user on p."JIRA_USER_ID" = app_user."user_key"
    inner join cwd_user cu on app_user."lower_user_name" = cu."lower_user_name"
    where active = 1)
and "SHAREABLE" = true;

You can then use the Team management page at <Jira base url>/secure/TeamManagement.jspa to find individual teams and adjust the membership as required.

11. Identify all the projects linked to Advanced Roadmaps plans [recommended]

You can identify all the projects linked to Advanced Roadmaps plans prior to making the project selection. Use the following API request:

API Request

GET:/rest/migration/latest/advanced-roadmaps/all-plan-projects-map

Example API call using curl

curl -u {username}:{password} https://{your-server-base-url}/rest/migration/latest/advanced-roadmaps/all-plan-projects-map

Example response

Upon calling the API, a JSON response will be generated in the following format:

[
	{
		"planId": 1,
		"projectKeys": [
			"ABSHI",
			"ABNFI",
			"AAUDXA"
		]
	},
	{
		"planId": 2,
		"projectKeys": [
			"AKERIA",
			"ALTRAA",
			"ACAPI",
			"ACPMI",
			"ACICRA"
		]
	},
	{
		"planId": 4,
		"projectKeys": [
			"AKERIA",
			"ALTRAA",
			"AMNUA",
			"ASAE",
			"AMTEE"
		]
	},
	{
		"planId": 5,
		"projectKeys": [
			"ASILA",
			"ASOTIA",
			"ASRESA"
		]
	},
	{
		"planId": 6,
		"projectKeys": [
			"ASSTS",
			"ANNUS",
			"ANIKEA"
		]
	},
	{
		"planId": 7,
		"projectKeys": [
			"ASACSA",
			"BADOI",
			"AVERS"
		]
	},
	{
		"planId": 8,
		"projectKeys": [
			"BBVISA"
		]
	}
]

This JSON response provides the Advanced Roadmaps plan ID and the associated project keys for each plan in the instance. The association originates from the issue sources and can be linked to a project, board, or filter.

12. Fix any duplicate shared configuration names [recommended]

To avoid migration conflicts, rename shared configuration (workflows or permission schemes) in your Server instance that have the same name as shared configuration in your Cloud site. If we find a conflict we may alter the name of the configuration during migration. Learn how the Migration Assistant links your data

13. Account for free disk space on your Server or DC [recommended]

Ensure your server or DC has enough disk space for migration. The space needed will depend on your Jira instance size and migration specifics. Account for additional storage for temporary files created during migration.

For more details:

14. Check you won't exceed storage limits on cloud [recommended]

Atlassian's Cloud plans have different storage limits. Before migrating, take a few minutes to check how much disk space you're currently using and review information about storage and limits in Cloud. Learn more about Cloud storage

15. Prepare your Server instance [recommended]

To ensure that your Server data migrates successfully, check the status of your data using the Database Integrity Checker (native to Jira Server) and the Integrity Check for Jira app from the Atlassian Marketplace.

Other checks and actions to perform:

all required fields must have a value and should not be null
reactivate any inactive user directories that you intend to migrate

Learn more about cleaning up your server instance

Fix HTML or JavaScript code embedded in custom field descriptions

The Jira Cloud product doesn't allow HTML or JavaScript code to be embedded in custom field descriptions as this can be an attack vector for Cross-site scripting (XSS) and other security vulnerabilities. You need to either adjust or remove these fields in the Jira Server before migrating. You can identify these custom fields in Jira Server using the queries mentioned in the document How to identify fields with custom JavaScript in their description.

16. Prepare your Cloud site [recommended]

Things to consider when setting up your cloud site:

Your cloud site must have the same Jira products enabled as your Server site, if there are groups containing product access to those respective products. This is so that all your users and groups migrate successfully.
Ensure that the language of your cloud site is the same as the language on your Server site. Some fields may not migrate properly if the languages are different.
If you’re using Atlassian Guard Standard, you should set it up before migrating and check the details on how to best migrate your users. Learn more about user migration strategies

17. Prepare Jira Align for the migration [optional]

If you use Jira Align, you’ll need to complete additional steps before, during, and after the migration. Some of them will need to be done together with the Jira Align Support team, so you’ll also need to inform us about your migration timeline.

Learn how to migrate Jira Align

18. Back up your data [recommended]

Before you run a migration, we recommend that you back up your current Jira Server site. If your destination Cloud site has existing data, back up your Jira Cloud site as well.

19. Run a test migration [recommended]

We strongly recommend you run a test migration before running your production migration.

Learn more about testing your migration

20. Notify support of your migration plan [recommended]

If you’re performing your migration over a weekend or holiday, or will have over 1,000 users in Cloud, we recommend getting in touch with our migration support team at least one to two months in advance. That way, we can ensure we have extra support on hand during your migration.

21. Check your network bandwidth

Right before your production migration, we recommend you perform a network test on the server to make sure the network is healthy (download, upload, and transfer bandwidth).
Recommended CLI tool for running a speed test: Speedtest CLI: Internet speed test for the command line
Ensure that your production environment doesn't have any additional security controls (e.g. egress traffic scanners) that may slow down data upload into the Atlassian cloud environment.

More information and support

We have a number of channels available to help you with your migration.

For migration planning information, visit the Atlassian Migration Program website.
For technical issues or support with strategy and best practices, get in touch with our support team.
For peer advice, ask the Atlassian Community.
For expert guidance, work with an Atlassian Partner.
For more help, check out the Cloud migration guide or register for our Cloud migration demos with live chat Q&A.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community