Confluence pre-migration checklist

Confluence server to cloud migration resources

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

description

Before migrating from Confluence Server to Cloud, run through this checklist to ensure you and your data are ready to go.

Migration can be a complex and challenging process. To help you out, we’ve created this checklist of everything you need to ensure your data is ready to migrate from Confluence Server or Data Center to cloud. 

To avoid common failures, complete these checks before attempting to migrate.

Before you begin

1. Confirm your migration method

What you'll check for varies depending on your migration method. The methods covered in this checklist are:

  1. The Confluence Cloud Migration Assistant

  2. Space by Space Import (XML)

  3. Site Import (XML)

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 Server or Cloud user interface
  • an unzipped Confluence Space export
  • an unzipped Confluence Support Zip
  • run SQL queries on the source instance

Confluence Cloud Migration Assistant checklist

The migration assistant automatically reviews your data for common errors. It will check that your:

  • migration assistant app is up to date

  • users have valid and unique email addresses

  • groups will merge through the migration process

  • spaces already exist in your cloud site

However, the migration assistant won’t check for everything, so you’ll also need to run through the following list before starting a migration.

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 server to cloud, or may do so in the future, it’s important to develop a user migration strategy. This help you avoid user management and content ownership related issues post-migration.

To develop a user migration strategy, you’ll need to know what you’re migrating as well as the method you’ll use for your Jira migration

If you plan to:

Also migrate 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.

Also migrate Jira using Jira Site Import (XML backup)

In this case, you have two options:

  1. 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. Migrate Jira first: Migrate Jira before migrating Confluence via the Confluence Cloud Migration Assistant. Jira Site Import won’t correlate server users with Atlassian Accounts, whereas Confluence and Jira Cloud Migration Assistants do. This means content ownership might break if Jira Site XML is imported after using the Confluence Cloud Migration Assistant, because the assistant will create all users and associate them to an Atlassian Account hash in the database tables. As the XML Importer cannot read them, it will associate all of Jira issues and comments to "Unknown Users", given it doesn't know its users do exist in cloud already. This cannot be reverted after the migration has completed. 

    On the other hand, when the Jira Server XML is imported before running the Confluence Cloud Migration Assistant, the migration assistant knows how to map the existing server usernames to the Atlassian Accounts in cloud.

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 limitThat means the sum of users to be migrated from server, 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:

Verify 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;
Verify 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:

4. Check your Confluence Server version MANDATORY

For the migration assistant to work, you need to be on a supported version of Confluence Server or Data Center.

Verify through the server UI

To verify Confluence's version: 

  1. Click on the cog icon in the application's right upper corner

  2. Select General Configuration

  3. Select System Information in the left navigation panel

  4. Finally, look for Confluence Version.

You can also use the methods outlined below for Linux and Windows.

Verify if on Linux

This can be validated by the following command. Ensure the number returned is 7901 (Confluence 6.13.x) or greater.

grep 'createdByBuildNumber' exportDescriptor.properties
Verify if on Windows

This can be validated by the following command. Ensure the number returned is 7901 (Confluence 6.13.x) or greater.

cat exportDescriptor.properties | Select-String -Pattern createdByBuildNumber
Verify using your Support Zip

This can be validated by the following command. Ensure the version returned is 5.10.x or greater.

grep '<product name="Confluence" version=' application.xml

5. Fix any app or add-on 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 Server instance, and leverage the Confluence Cloud Migration Assistant to merge it with the desired cloud site. This would carry app (add-on) users from the cloud site to the server instance. As add-on users are not common in the server world, they might cause a few issues during the migration back to cloud. Before migrating, delete or update any of these 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. 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 Server UI.

Verify 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.

Verify 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.

Verify 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.

Verify you can connect to Atlassian domains

Ensure that the domains listed on Atlassian cloud IP ranges and domains will not be blocked by any security rules before running a migration. Additionally, allow these endpoints:

10. Determine how you’ll migrate apps MANDATORY

The Confluence Cloud Migration Assistant will not migrate app or add-on data.  If you have app data to migrate, contact vendors beforehand for advice on how to migrate their data properly. This includes Atlassian-built apps like Confluence Questions or Team Calendars for Confluence. If you need to migrate either of these apps, you can watch the related feature request to stay up to date:

  • MIG-106 - Getting issue details... STATUS
  • MIG-124 - Getting issue details... STATUS
Verify 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

11. Check your public access settings MANDATORY

You can configure your Confluence Server or cloud site 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. Learn more about checking your public access settings

Verify 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;

12. Check your Heap Allocation MANDATORY

Depending on the amount of data to be migrated, Confluence Server might experience an OutOfMemory error. This will crash the entire migration. To prevent this, ensure that your application is running with at least 4 GBs of Heap Allocation (if not, make it as close as possible to it).

Verify if 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 -Xmx4096m

Also, 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 unsure of how to check that via system commands, create a Support Zip, open the application-propperties/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 if you are running Windows.

Verify if on Windows, 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
Verify if on Windows, not running as a service

Follow the instructions in this article for Step 1: Increase Available Memory (look for Windows Service inside the step).

Verify 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

13. Back up your cloud site RECOMMENDED

If the cloud site you’re migrating to has existing data, back it up before importing your space(s).

14. 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. Check out our guidance on testing your migration.

15. 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 two weeks in advance. That way, we can ensure we have extra support on hand during your migration. 

Learn more about how we support cloud migrations.

Space by space import (XML) checklist

We highly recommend using the Confluence Cloud Migration Assistant when migrating from server 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.

1. Confirm your 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 who will be running the migration exists in the target cloud site and has been granted Site Administrator permission.

3. Determine how you’ll migrate apps MANDATORY

The space export XML will not migrate any app data, including Atlassian apps such as Team Calendars. After assessing which 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.

Verify 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 your Confluence Server 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 Server or Data Center, ensure the instance is running on version 6.13.x or later, otherwise, the import will not work properly. If you're running an earlier version, you’ll need to upgrade it first.

Verify through the server UI

To verify Confluence's version: 

  1. Click on the cog icon in the application's right upper corner

  2. Select General Configuration

  3. Select System Information in the left navigation panel

  4. Finally, look for Confluence Version.

You can also use the methods outlined below for Linux and Windows.

Verify if on Linux

This can be validated by the following command. Ensure the number returned is bigger or equal to 7901 (Confluence 6.13.x):

grep 'createdByBuildNumber' exportDescriptor.properties
Verify if on Windows

This can be validated by the following command. Ensure the number returned is bigger or equal to 7901 (Confluence 6.13.x):

cat exportDescriptor.properties | Select-String -Pattern createdByBuildNumber

5. Check your XML structure MANDATORY

Check that the space export XML is not corrupted.

Verify using your XML Space export

Before importing it to cloud, ensure it doesn’t have any broken data by running the command below:

xmllint --noout entities.xml

If 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.

Verify if 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 in hands is a Site Export file and you’ll need to create a Space export instead.

Verify if 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 exportType

If it doesn’t, what you have in hands is a Site Export file and you’ll need to create a Space export instead.

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.

Verify if 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
Verify if 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 Server might experience an OutOfMemory error. This will crash the entire migration. To prevent this, ensure that your application is running with at least 4 GBs of Heap Allocation (if not, make it as close as possible to it).

Verify if 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 -Xmx4096m

Also, 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 unsure of how to check that via system commands, create a Support Zip, open the application-propperties/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 if you are running Windows.

Verify if on Windows, 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
Verify if on Windows, not running as a service

Follow the instructions in this article for Step 1: Increase Available Memory (look for Windows Service inside the step).

Verify 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, back it up before importing your space(s).

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. Check out our guidance on testing your migration.

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 at least two weeks in advance to let us know. That way, we can ensure we have extra support on hand during your migration.  Learn how we support cloud migrations.

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 support 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.

Last modified on Oct 21, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.