Confluence pre-migration checklist
You can use the pre-migration checklist to ensure your data is ready to migrate from Confluence Data Center to Cloud. To avoid common failures, complete these checks before attempting to migrate.
Before you begin
1. Confirm your migration method
Check for various Cloud migration methods. The methods covered in this checklist are:
Next, follow the pre-migration checks for the migration method you have chosen.
2. Prepare
To complete the pre-migration checks, you may need:
access to the Confluence Data Center or Cloud user interface
access to an unzipped Confluence Space export
access to an unzipped Support ZIP file. Learn how to create a Support ZIP
to run SQL queries on the source instance
Sometimes you may experience extended performance degradation during migration, or pre-migration checks, due to certain types of scheduled background processes running. We recommended that you stop all unnecessary/non-crucial scheduled jobs on your Confluence Data Center when you start your migration journey. The impact is not necessarily from one specific job, and is more likely to be a cumulative effect of multiple jobs running during the migration window. How to check all scheduled jobs
Confluence Cloud Migration Assistant checklist
The Confluence Cloud Migration Assistant automatically reviews your data for common errors. However, it won’t check for everything, so you’ll also need to run through this pre-migration checklist before starting a migration.
Use the table below to run through all the items for the Confluence Cloud Migration Assistant checklist.
Type | Action |
|---|---|
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Recommended | |
Recommended | |
Recommended | |
Recommended | |
Recommended |
1. Confirm your user migration plan [mandatory]
While the assistant can migrate your users and groups, it doesn't have the ability to determine whether you are migrating only Confluence, or Jira as well.
If you’re also migrating Jira from Data Center to Cloud, or may do so in the future, it’s important to develop a user migration strategy. This helps you avoid user management and content ownership related issues post-migration. Learn more about user migration strategies
Migrate Confluence only
Review the guidance in Determine your user migration strategy.
Migrate Confluence and Jira using the Jira Cloud Migration Assistant
The migration assistants will migrate your users and groups, however, you’ll need to ensure that email addresses are the same for users shared across Jira and Confluence. For example, if UserA (usera@example.com) can access Confluence and Jira, both applications should have the same email address for UserA in their databases. This is because the migration assistants use email addresses to map content during the migration.
Migrate users first
Migrate all users beforehand with the assistance of our support team, as outlined in Determine your user migration strategy, and then migrate Confluence or Jira in any order.
2. Ensure you won’t exceed your Cloud user limit [mandatory]
If you’re migrating to a Confluence Cloud site that’s on the Free plan, the migration assistant will check to ensure your migration won’t exceed the user limit. That means the sum of users to be migrated from Data Center, plus any users that already exist in Cloud, can’t exceed 10 or the migration will fail.
If your Confluence Cloud site is on an annual subscription to another plan, you need to check to make sure the sum of users to be migrated from Server, plus any users that already exist in Cloud, doesn’t exceed your subscription user tier. For example, if you have a 51 - 100 user subscription and try to import 110 active users, the migration will fail.
To fix this, you can:
subscribe to a plan with a higher user limit.
reduce your number of users before migrating.
get in touch with Atlassian support to import users without product access beforehand.
Check using SQL (tested on Postgres)
Use the query below before running a migration to crosscheck the number of users to be migrated with your Cloud plan user limit. If needed, take actions to reduce the number of users, upgrade your Cloud plan, or add more users to your subscription: --USER LIMITS - TESTED ON POSTGRESQL
SELECT u.lower_user_name, d.directory_name
FROM cwd_user u
JOIN cwd_membership m ON u.id = child_user_id
JOIN cwd_group g ON m.parent_id = g.id
JOIN SPACEPERMISSIONS sp ON g.group_name = sp.PERMGROUPNAME
JOIN cwd_directory d on u.directory_id = d.id
WHERE sp.PERMTYPE='USECONFLUENCE' AND u.active = 'T' AND d.active = 'T'
GROUP BY u.lower_user_name, d.directory_name
ORDER BY d.directory_name; |
Check using your Support Zip
Use the query below before running a migration to crosscheck the number of users to be migrated with your cloud plan user limit. If needed, take actions to reduce the number of users, upgrade your cloud plan, or add more users to your subscription: grep '<users>' application.xml |
3. Ensure you have the right permissions [mandatory]
Ensure that the user who runs the migration:
has system admin permission on the Data Center instance
exists in the target cloud site
has both an organization admin and an app admin role in Confluence Cloud. For older organizations, you might be able to use the Site Administrator role, but it has been deprecated for new organizations
4. Check your Confluence Data Center version [mandatory]
For the migration assistant to work, you need to be on a supported version of Confluence. Confluence Cloud Migration Assistant supported versions
Check through the server UI
To verify Confluence's version:
You can also use the methods outlined below for Linux and Windows. |
Check on Linux
This can be validated by the following command. Ensure the number returned is 8100 (Confluence 6.15.x) or greater. grep 'createdByBuildNumber' exportDescriptor.properties |
Check on Windows
This can be validated by the following command. Ensure the number returned is 8100 (Confluence 6.15.x) or greater. cat exportDescriptor.properties | Select-String -Pattern createdByBuildNumber |
Check using your Support Zip
This can be validated by the following command. Ensure the version returned is 6.15 or greater. grep '<product name="Confluence" version=' application.xml |
5. Fix any Marketplace app email addresses [mandatory]
The check applies when trying to merge two or more Confluence Cloud sites. One common scenario is to export one of them as an XML backup, import it to a Confluence Data Center instance, and leverage the Confluence Cloud Migration Assistant to merge it with the desired Cloud site. This would carry Marketplace app users from the Cloud site to the Server instance. As Marketplace users are not common in the Data Center world, they might cause a few issues during the migration back to Cloud. Before migrating, delete or update any of these users.
Check 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. Fix any duplicate email addresses [mandatory]
The migration assistant will flag duplicate email addresses and will not allow the migration to run until all users have unique email addresses. However, as a proactive step, it's good to find and fix those beforehand. If user information is managed in an LDAP Server, emails will need to be updated in the LDAP Server and synced over to Confluence before the migration. If user information is managed locally, emails can be fixed via the Confluence Data Center UI.
Check using SQL (tested on Postgres)
Use the query below to find duplicate email addresses, the number of times these addresses repeat, as well as the users assigned to the email address: --DUPLICATED EMAIL ADDRESSES - TESTED ON POSTGRESQL
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; |
7. Fix any duplicate usernames [mandatory]
The migration assistant will flag duplicate usernames and will not allow the migration to run until all users have unique usernames. This can happen when a user exists with the same username in Confluence's Internal Directory and Confluence's LDAP Directory. If that happens, either rename the users or remove one of them before running the migration.
Check using SQL (tested on Postgres)
Use this query to identify any duplicate usernames: --DUPLICATED USERNAMES - TESTED ON POSTGRESQL
select lower_user_name, count(lower_user_name)
from cwd_user group by lower_user_name having count(lower_email_address) > 1; |
8. Rename restricted groups [mandatory]
There are a few groups that will not be migrated because they already exist in Cloud and are specific to Cloud-related functions. If any of these groups exist in your Server instance before migration, it’s important to rename them to ensure group-based access is maintained.
Check using SQL (tested on Postgres)
Use the query below to see if these groups exist in your Server instance. If they do, rename them in Server before migrating: --RESTRICTED GROUPS - TESTED ON POSTGRESQL
select lower_group_name from cwd_group where lower_group_name in
('site-admins', 'system-administrators', 'atlassian-addons', 'atlassian-addons-admin'); |
9. 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. Learn which IP addresses and domains need to be allowlisted
10. Set up HTTP or HTTPS Proxy for Confluence [mandatory]
If you are using a web proxy setup, this is a mandatory step. Ensure that you have correctly set up either or both HTTP or HTTPS proxy using the steps explained at: Proxy and HTTPS setup for Confluence
Note the following points before initiating any migration using CCMA:
CCMA supports only HTTP and HTTPS proxy.
You can use only one of these proxy setups: HTTP or HTTPS. Therefore, configure the one that is appropriate for your Confluence server.
In CCMA, the HTTP proxy is enabled by default. However, to use the HTTPS proxy, you need to enable the feature flag:
migration-assistant.enable.migration.https.proxy
11. Determine how you’ll migrate Marketplace apps [mandatory]
The Confluence Cloud Migration Assistant will not migrate Marketplace app data. If you have app data to migrate, contact vendors beforehand for advice on how to migrate their data properly. This includes Atlassian-built Marketplace apps like Team Calendars for Confluence. If you need to migrate Team Calendars for Confluence, you can watch the related feature request to stay up to date.
Check using your Support Zip
Use the query below to see if you have Team Calendars or Questions for Confluence installed: grep -e '<key>com.atlassian.confluence.plugins.confluence-questions</key>' -e '<key>com.atlassian.confluence.extra.team-calendars</key>' -- application.xml |
12. Check your public access settings [mandatory]
You can configure your Confluence Data Center or to be publicly available to the internet. Before migrating, check for any spaces in Server that have been made publicly available and remove their anonymous access setup, unless content is meant to be public.
Check using SQL (tested on Postgres)
Use the query below to check your space permissions: select spaces.spacekey, spaces.spaceid, spacepermissions.permtype from public.spacepermissions
inner join public.spaces on spacepermissions.spaceid = spaces.spaceid where spacepermissions.permtype = 'VIEWSPACE'
and spacepermissions.permgroupname is null and spacepermissions.permusername is null; |
13. Check your Heap Allocation [mandatory]
Depending on the amount of data to be migrated, Confluence Data Center might experience an OutOfMemory error. This will crash the entire migration. To prevent this, ensure that your application is running with at least 4GB of Heap Allocation (if not, make it as close as possible).
Check on Linux
Go to /confluence-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): -Xms4096m -Xmx4096mAlso, check 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 you’re not sure how to check that via system commands, complete these steps:
Learn more about the 'Too many open files' error This doesn’t apply if you are running Windows. |
Check on Windows, if running as a service
Go to /confluence-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): -Xms4096m -Xmx4096m |
Check on Windows, if not running as a service
Follow the first step in How to fix out of memory errors (look for Windows Service inside the step). |
Check using your Support Zip
Use the query below to check that you're running at least 4 GBs of Heap Allocation: grep '<max-heap>' application.xml |
14. Don’t change your server timezone [recommended]
We recommend that you don't change the server timezone if you plan to migrate from server to cloud. Changing the server timezone could cause migration failures. Contact support if you run into such timezone related failures.
15. Back up your Cloud site [recommended]
If the Cloud site you’re migrating to has existing data, create a site backup before importing your space(s). Learn how to create a site backup
16. Run a test migration [recommended]
We strongly recommend doing a trial run of your migration to a test or staging Cloud site before running your final migration. Learn how to test your migration
Note that we don’t support the H2 Database in Confluence Cloud Migration Assistant. Also, we’ve ended support for the H2 database in Confluence 8.0.
17. Notify support of your migration plan [recommended]
If you'll be performing your migration over a weekend or holiday, or will have over 1,000 users in cloud, we recommend getting in touch with our support team at least two weeks in advance to let us know. That way, we can ensure we have extra support on hand during your migration.
18. Check your network bandwidth [recommended]
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.
Space-by-space import (using XML) checklist
We highly recommend using the Confluence Cloud Migration Assistant when migrating from Data Center to Cloud. However, in cases where it can’t be used, or the space(s) to be imported to Confluence Cloud were exported from a different Cloud site (for example, in the case of a Cloud to Cloud migration), use the following checklist before running a migration.
Type | Action |
|---|---|
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Mandatory | |
Recommended | |
Recommended | |
Recommended |
1. Confirm user migration plan [mandatory]
The space export XML will not import users, groups, or group memberships to your destination Cloud site. This means that if there are pages that are restricted to these users or groups, you may not be able to see them until you recreate these users and groups in your destination site.
2. Ensure you have the right permissions [mandatory]
Ensure that the user running the migration exists in the target cloud site and is an organization admin and an app admin (previously, product admin) in Confluence Cloud.
3. Determine how you’ll migrate Marketplace apps [mandatory]
The space export XML will not migrate any Marketplace app data, including Atlassian Marketplace apps such as Team Calendars. After deciding which Marketplace apps you need to migrate, you'll need to check with the app developers to confirm whether you are able to move app data across. Learn how to decide which apps to migrate
Check using your Support Zip
Use the query below to see if you have Team Calendars or Questions for Confluence installed: grep -e '<key>com.atlassian.confluence.plugins.confluence-questions</key>' -e '<key>com.atlassian.confluence.extra.team-calendars</key>' -- application.xml |
4. Check Confluence Data Center version [mandatory]
If the space you’re importing is from another Cloud site, there should be no need to worry about versioning.
If you’re importing a space from Confluence Data Center, ensure the instance is running on version 6.14.x or later, otherwise, the import will not work properly. If you're running an earlier version, you’ll need to upgrade it first.
Check through the server UI
To verify Confluence's version:
You can also use the methods outlined below for Linux and Windows. |
Check on Linux
This can be validated by the following command. Ensure the number returned is bigger or equal to 7901 (Confluence 6.14.x): grep 'createdByBuildNumber' exportDescriptor.properties |
Check on Windows
This can be validated by the following command. Ensure the number returned is bigger or equal to 7901 (Confluence 6.14.x): cat exportDescriptor.properties | Select-String -Pattern createdByBuildNumber |
5. Check your XML structure [mandatory]
Check that the space export XML is not corrupted.
Check using your XMP Space export
Before importing it to Cloud, ensure it doesn’t have any broken data by running the command below: xmllint --noout entities.xmlIf the XML is correctly structured, the command shouldn’t return anything. If it does, fix the reported issues before running the import. |
6. Ensure you have the right type of export [mandatory]
Check that the file being imported is a Space Export, not a full Site Export – otherwise, the import process will fail.
Check on Linux
Before importing your XML file to Cloud, run the command below and ensure it returns exportType=space. grep 'exportType' exportDescriptor.properties If it doesn’t, what you have on hand is a Site Export file and you’ll need to create a space export instead. Learn how to create a space export |
Check on Windows
Before importing your XML file to Cloud, run the command below and ensure it returns exportType=space. cat exportDescriptor.properties | Select-String -Pattern exportTypeIf it doesn’t, what you have on hand is a Site Export file and you’ll need to create a space export instead. Learn how to create a space export |
7. Check for duplicate space keys [mandatory]
Each space is associated with a unique space key. If the space you're trying to import has a space key that already exists in Cloud, the import will fail.
Check on Linux
Run the command below, get the Space Key and then ensure it doesn’t exist in the destination Cloud instance prior to running the import: grep 'spaceKey' exportDescriptor.properties |
Check on Windows
Run the command below, get the Space Key and then ensure it doesn’t exist in the destination Cloud instance prior to running the import: cat exportDescriptor.properties | Select-String -Pattern spaceKey |
8. Check your Heap Allocation [mandatory]
Depending on the amount of data to be migrated, Confluence Data Center might experience an OutOfMemory error. This will crash the entire migration. To prevent this, ensure that your application is running with at least 4GB of Heap Allocation (if not, make it as close as possible).
Check on Linux
Go to /confluence-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): -Xms4096m -Xmx4096mAlso, check 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 you’re not sure how to check that via system commands, complete these steps:
Learn more about the 'Too many open files' error This doesn’t apply if you are running Windows. |
Check on Windows, if running as a service
Go to /confluence-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): -Xms4096m -Xmx4096m |
Check on Windows, if not running as a service
Follow step 1 of How to fix out of memory errors (look for Windows Service inside the step). |
Check using your Support Zip
Use the query below to check that you're running at least 4 GBs of Heap Allocation: grep '<max-heap>' application.xml |
9. Back up your Cloud site [recommended]
If your destination Cloud site has existing data, create a site backup before importing your space(s). Learn how to create a site backup
10. Run a test migration [recommended]
We strongly recommend doing a trial run of your migration to a test or staging Cloud site before running your final migration. Learn how to test your migration
If you use a staging environment to run test migrations, make sure that you save the staging Server ID (Administration > System > System info) before copying the production data to your staging environment. After you clone the production, the last step is to update the staging Server ID to the saved value.
11. Notify support of your migration plan [recommended]
If you'll be performing your migration over a weekend or holiday, or will have over 1,000 users in Cloud, we recommend getting in touch with our support team at least two weeks in advance to let us know. That way, we can ensure we have extra support on hand during your migration.
Site import (XML) checklist
This method will only be available if your Cloud site is Confluence-only. We don’t recommend using this method to migrate, as it comes with a number of limitations.
If you need to use it instead of leveraging the Confluence Cloud Migration Assistant or space by space import, please get in touch with our support team so we can help determine the best approach for 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?