Cloud Migration Assistant for Confluence

by | Apr 15, 2019 | Atlassian, Confluence | 0 comments

The Cloud Migration Assistant for Confluence is an app that helps you easily move content, users, and groups from Confluence Server to Confluence Cloud. Built and maintained by Atlassian, the app is free to install and use.

Once installed, you can choose what you want to move to the Cloud, start migrating at your convenience, and monitor the progress of everything throughout the migration process. 

When to use the Cloud Migration Assistant for Confluence

  • After completing the pre-migration steps in your migration plan. 
  • After you’ve migrated your Jira Server instance to your Jira Cloud site, and you’re ready to migrate to a new Confluence Cloud site. Migrating Jira after Confluence may overwrite some of the migrated data. 
  • When you want to migrate an entire Confluence Server site to a new Confluence Cloud site.
  • When you want to move spaces or users from Confluence Server to an existing Confluence Cloud site.
  • When the Atlassian Support team has recommended using the app.

Before you migrate

Check out the Cloud Migration Center and FAQs to find out everything you need to know before migrating. You can also use our helpful guide to plan your migration from start to finish. 

Pre-migration checklist

Confluence Data Center

Step 1: Check for possible data conflicts in your cloud site

You can reduce the risk of running into issues, or the migration failing, if you conduct some manual checks in your server instance and cloud site.

Groups

Make sure that there are no groups already in your cloud site with the same name as groups from your server site, unless you are intentionally trying to merge them. 

If we find a group in your server instance that has the same name a group in your cloud site (either Jira or Confluence), we will merge the users from the server group into the cloud group. The server group users will inherit the permissions of the cloud group. This also applies to groups with Jira product access that have the same name as a Confluence group you are migrating. This is because all users and groups are managed in a central location in your cloud site.

If you don’t want this to happen, you will need to make sure all groups across server and cloud have unique names before running your migration plan. 

The following generic groups are blacklisted and will not be migrated at all: “site-admins”, “system-administrators”, “atlassian-addons”, “atlassian-addons-admin”. Users from within these groups will be migrated, you will then need to manually add them to these groups after migration.

Space keys

Your migration could also fail if a space from your server instance has the same space key as a space in your cloud site. This is because every space in Confluence Cloud must have a unique space key.

If the migration assistant finds a conflict, the space will not migrate. In this case some spaces may still migrate, but the overall plan will fail.

Before migrating, check that there are no competing space keys between your Server and Cloud sites. If you find a conflict you may need to use a workaround to change the space key, or you can choose not to migrate that space in step 3. 

If a space key conflict is caused by a previous test migration you can reset your cloud site before migrating. 

Step 2: Install the Cloud Migration Assistant for Confluence app

There are a few things to check before using the app:

Once all of the prerequisites are complete, you can begin using the app. If your Confluence Server instance is version 6.13 or above you won’t need to install anything because it comes pre-installed, although you may be asked to update the app. See step 3 to locate the migration assistant within your server instance. 

To install the app on versions 5.10 to 6.12:

  1. In Confluence Server go to  > Manage apps.
  2. Choose Find new add-ons. 
  3. Search for the Cloud Migration Assistant for Confluence app. 
  4. Choose Install and you’re all set.

Step 3: Use the app to prepare and run your migration

Analyze your instance

  1. In Confluence Server, go to  > General Configuration > Migration Assistant. 
  2. Choose Create a migration plan > Run analysis

This step evaluates your Confluence Server instance. It will give you an overview of the number of users, groups, spaces, pages, and attachments that currently exist. 

It will also check for any user account errors, such as invalid or duplicate email addresses. You’ll need to resolve these errors before you can migrate. 

Updating the app

You may be asked to update the Cloud Migration Assistance for Confluence. You will need to do this before running any migrations. 

Choose what you’d like to migrate 

You can migrate everything together or break it up into different stages.

You can choose:

  • all or none of your users and groups
  • which individual spaces (and their attachments) you’d like to migrate 

If you choose to migrate spaces and no users, some user data will be migrated along with the spaces. This is to make sure that mentions and comments stay active. These users will appear in your cloud site but will not be granted product access, and will not be added to your license.


If you choose to migrate users later, their product access will be updated.

Migrating users and groups

There are a few things to be aware of when migrating users and groups from your server instance to a cloud site:

  • Confluence Cloud is subscription-based and billed on a per-user basis. If you plan to migrate your users, make sure you check the licensing options or calculate the cost with our pricing calculator.
  • If you use an external user management system, we recommend syncing it with your local directory before migrating. 
  • All users must have a unique and valid email address before you will be able to migrate. The process for fixing any invalid email errors will depend on where your user data is stored. 
  • Users with disabled status will be migrated as active but without any product access. This means they will not be counted as active Confluence users for billing purposes. 
  • If we find a group in your server instance that has the same name a group in your cloud site, we will merge the users from the server group into the cloud group.
  • Global settings and global site permissions are not migrated with this tool. You will need to set these manually after migration.
If your users already exist in cloud

If you have users that already exist in your destination cloud site and you choose to migrate users with this app, you will need to consider the following:

  • If a user has product access in cloud, but has disabled status in your server instance, they will continue to have product access in cloud after migration. 
  • If a user does not have product access in cloud, but is enabled in your server instance, they will be granted product access through the migration process. 
  • If we find a group in your server instance that has the same name a group in your cloud site, we will merge the users from the server group into the cloud group.

When migrating users and groups, be sure to check for the issues listed above. Some users may be granted escalated access. 

Add spaces to your plan

When you’re ready to add spaces to your plan, select Continue. 

Select the spaces you want to add to your migration plan. You can filter the list or search for particular spaces, or click Select all if you want to migrate everything at once. You will not be able to migrate spaces with space keys that already exist in your Confluence Cloud destination site. Make sure you check for conflicting space keys in step 1. 

When you’ve chosen all your spaces, select Add items to plan. 

Give the plan a name 

Add a name for your migration plan in the Migration plan name field. This name helps you keep track of your plans, for example, differentiating between a user migration, a test migration, and a final production migration.

Choose your destination Confluence Cloud site

  1. Select Choose cloud site and follow the prompts to log in to your Atlassian Cloud account as a Site Admin (if you’re not already logged in). 
  2. The sites associated with your Atlassian Cloud account will be listed in the Migration destination drop-down menu. If the current account is not correct, click Change account to log in with a different account.
  3. Select your site from the Migration destination field then select Confirm. 
  4. When you’re ready, select Review plan. 


Review your migration plan

If everything looks correct and you want to start your migration, click Run. If you would like to start your migration later from your migration dashboard, click Save. If you choose to run your migration plan, it will still be saved to your migration dashboard. There, you can view the progress and details of the migration. 

The first time you run a migration plan, you will be asked to Securely share your migration data with Atlassian to begin the cloud migration process. This allows Atlassian to securely copy data from your Confluence Server instance to your Confluence Cloud site. You will need to confirm that you agree before the migration plan can run.

You won’t be able to run your migration until all user email errors are resolved. This is because these errors will cause the migration to fail. 

Manage your migration plans

Your saved migration plan will be listed on the migration dashboard, where you can view its details or run it. You can also check the status of a plan, monitor the progress of a migration plan that is currently running, stop a plan that’s currently running, or create a new plan. 

You can create as many plans as you need. At this time, migration plans can’t be edited or deleted, so if you create a plan that can’t be used, just create a new plan to continue your migration to the Cloud.

Plan status definitions

READY Your migration plan is ready to run.

RUNNING Your migration plan is currently in progress.

FINISHED Everything in your migration plan has been migrated.

STOPPED Your migration plan has been stopped. Once stopped, it can’t be resumed. Any step already in progress will first need to finish before the plan is shown as fully stopped. Some users, groups and spaces may already have been migrated to your Confluence Cloud site.

FAILED We were unable to complete the migration plan. This might be because a space key already exists in the destination site, or the migration hit an unexpected error. Some users, groups and spaces may already have been migrated to your Confluence Cloud site.

Run a saved migration plan

To run your plan:

  1. In Confluence Server, go to  > General Configuration > Migration Assistant.
  2. Select Run on the plan you want to run. The first time you run a migration plan, you will be asked to Securely share your migration data with Atlassian to begin the cloud migration process. This allows Atlassian to securely copy data from your Confluence Server instance to your Confluence Cloud site. You will need to confirm that you agree before the migration plan can run. 

You can check the progress of your migration in the progress column, or choose View details to see a summary of the migration tasks.

After migrating spaces, it may take a while for them to appear in the space directory. However, you can still access them via a direct link. 

Step 4: After migrating

Depending on the type of migration, there may be some things you need to do once your migration is finished. 

Users and groups

To make sure your users and groups are set up correctly:

  • Review members of groups and approve their permissions by going to Review imported groups.
  • Add users to the generic groups if necessary. The generic groups are: “site-admins”, “system-administrators”, “atlassian-addons”, “atlassian-addons-admin”
  • If you use an external user management system, check that your users have synced correctly. 
  • When you are ready, invite your users by using the send reminder email function. When they first login they may be prompted to set a new password and add personal details. 

Spaces

To check that your spaces have migrated successfully:

  • Review content and spaces, or ask your users to review their own content. 
  • Check for any instances of Former User. This means that we were unable to match content to a user. 

You can then install any apps you wish to use and onboard your users. 

For a full list of post-migration recommendations, refer to the Confluence migration planning guide.

Submit a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.