Plan your Cloud migration
Documents to help you prepare to migrate your Atlassian Server products.
Jira Cloud Migration Assistant pre-migration checklist
Upgrade to Jira Cloud Migration Assistant 1.7.3 or higher
To give you a more stable and reliable migration experience, we’ve improved the way attachments and other media files are migrated.
Starting September 19, 2022, we recommend you upgrade to Jira Cloud Migration Assistant 1.7.3 or higher for all your migration needs in future.
Starting January 31, 2023, you won’t be able to use 1.7.1 and lower of the Jira Cloud Migration Assistant.
Learn more about this announcement and how to upgrade.
For any further details or technical concerns, contact us.
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 the following list before starting a migration.
To complete the pre-migration checks, you may need:
access to the Jira Server or Cloud user interface
access to an unzipped Jira Support Zip
access to an unzipped Jira 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 migration strategy. This also ensures that data remains linked to the correct users during the migration.
If you’re using an external identify provider to manager your users, make sure they are active and are synchronized to your internal user base 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
1
2
3
4
5
6
7
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: 1579025414214Active External Directory Verification
1
2
3
4
5
6
7
8
9
grep "Active:" <Support Zip Location>/auth-cfg/directoryConfigurationSummary.txt
Example Output:
Active: true
Active: true
Active: true
Active: false
Active: trueNote 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.
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
1
2
3
4
5
grep "<product name" <Support Zip Location>/application-properties/application.xml
Example Output:
<product name="Jira" version="8.7.1"/>3. Fix any duplicate email addresses [mandatory]
Duplicate email addresses are not supported by Jira Cloud and therefore can't be migrated with the Jira Cloud Migration Assistant. To avoid errors, you should find and fix any duplicate email addresses before migration. If user information is managed in an LDAP Server, you will need to update emails there and sync with Jira before the migration. If user information is managed locally, you can fix them through the Jira Server or Data Center user interface.
Verify using SQL (tested on Postgres)
Use the query below to find duplicate email addresses (if any), the number of times these addresses repeat, as well as the users assigned to the email address:
1
2
select lower_email_address, count(lower_email_address), array_agg(user_name) as "Users with Dupe E-Mail"
from cwd_user group by lower_email_address having count(lower_email_address) > 1;4. Make sure you have the right permissions [mandatory]
Ensure that the user who runs the migration:
has System Administrator global permissions on the Server instance
exists in the target Cloud site
has Site Administrator permission in Cloud
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 about 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:
1
2
--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 will not be blocked by any security rules before running a migration.
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. This includes Atlassian-built apps like Portfolio for Jira. If you need to migrate Portfolio for Jira, watch the related feature request to stay up to date.
Also note that in Jira Cloud, Portfolio is not offered as a standalone app, but the features are available as Advanced Roadmaps in Jira Software Cloud Premium.
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 any projects that have the Browse Project permission set to Anyone.
1
2
3
4
5
6
7
8
9
10
11
12
13
// get list of project permission schemes which has share type as "Anyone" (i.e. open)
SELECT p.id, p.pname, ps.name 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.permission_key='BROWSE_PROJECTS'
AND sp.perm_type='group'
AND sp.perm_parameter is nullFilters
This will get a list of filters which has share type as "share with everyone" (i.e. global)
1
2
3
4
5
// 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)
1
2
3
4
5
6
// 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)
1
2
3
4
5
6
// 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]
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 by checking the parameters outlined in Increasing Jira's Application Memory.
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>. If this number is close to 32768, adjust it accordingly. More information about it can be seen in the following documentation: Too many open files error. This doesn’t apply to those running Windows.
Verify using your support zip
Ensure the value of the Xmx and Xms is at least 4096m or 4g:
1
2
3
4
5
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 Ensure the value of <max-file-descriptor> is close to 32768:
1
2
3
4
5
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
If on 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):
1
2
JVM_MINIMUM_MEMORY="4096m"
JVM_MAXIMUM_MEMORY="4096m"If on 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):
1
2
JVM_MINIMUM_MEMORY="4096m"
JVM_MAXIMUM_MEMORY="4096m"If on Windows, running as a service
Follow the instructions in this article about increasing Jira application memory.
10. Check your Server timezone [mandatory, if merging Cloud sites]
If you're using the migration assistant in order to merge Jira Cloud sites, there might be a slight shift in timezones for timestamps in issues. Jira Cloud uses UTC. If the Jira Server instance uses any other timezone, it shifts in hours based on the difference from UTC.
The workaround is to add a system flag to the Jira Server instance -Duser.timezone=UTC as outlined in this article about updating documentation to include timezone details.
Verify using your Jira Server user interface
To confirm your Server timezone:
Select the cog icon in the top right corner.
Select System.
Select System Information in the left navigation panel.
Look for jvm.system.timezone.
Verify using your Support Zip
You can also use the following query to verify your Server timezone:
1
2
3
4
5
grep "<jvm.system.timezone>" <Support Zip Location>/application-properties/application.xml
Example Output:
<jvm.system.timezone>America/New_York</jvm.system.timezone>11. 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.
12. Check you won't exceed storage limits [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 our Cloud storage documentation.
13. 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 archived projects that you want to migrate
reactivate any inactive user directories that you intend to migrate
For more information about cleaning up your data, see Clean up your server instance before migration.
14. 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. For example, if you’ve Jira Core and Jira Software on your Server site, you need both Jira Work Management (formerly Jira Core) and Jira Software on your Cloud site, even if you're not migrating Jira Core projects. This is so that all your users and groups migrate successfully.
Note: If you've Jira Software or Jira Service Management license, you can use Jira Work Management for free. Learn more about Jira Work Management licensing.
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 Access, you should determine your user migration strategy and set up Atlassian Access before migrating.
15. 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.
16. Run a test migration [recommended]
We strongly recommend you run a test migration before running your production migration. Check out our guidance on testing your migration.
17. 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.
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?