• Documentation

Migrate data using the Confluence Cloud Migration Assistant

When migrating Confluence, you build a migration plan and fill it in with data. You can either include everything in a single plan or divide it into many migration plans.

Looking for information on assessments?

Before you migrate data, you should complete assessments available in the assistant:

Before you begin

Complete these steps:

  • Check what can be migrated with this option. Learn more

  • Update the assistant and allowlist required IPs and domains. Learn more

  • Check for possible data conflicts to avoid issues. Learn more

  • Complete the pre-migration checklist to prepare your environment. Learn more

  • Pre-migrate users, groups, and attachments before other data to reduce downtime. Learn more

Permissions:

  • To migrate, you need to be a system admin in the source instance and an organization admin in the destination cloud site.

Running a test migration

We strongly recommend doing a trial run of your migration to a test or staging site before running your final migration. Learn how to test your migration

Create a migration plan and connect to your cloud site

To create a migration plan:

  1. Open the Confluence Cloud Migration Assistant.

  2. Select Create new migration.

  3. On the Connect to your cloud site screen, provide the following data:

Example screen

Fields

Connect to your cloud site
  • Name your migration

  • Choose migration stage: production or testing. This option doesn’t affect your migration. It will help you recognize different migrations plans on the dashboard.

  • Choose destination cloud site: If you don’t have one yet, you can activate your free Cloud migration trial and create one.

Once you select a destination cloud site, you’ll be able to choose what to migrate.

Choose what data to include in your plan

You can add the following items to your migration plan.

Example screen

What you can migrate

Task list with options to select global templates, spaces, user and groups
  • Global page templates and custom system templates

  • Spaces (and their attachments), Team Calendars associated with Team Calendars

  • Only attachments

  • All apps that you marked as Needed in cloud when assessing your apps

  • All users and groups from the Confluence directory

OR

  • Only users and groups that have space permissions. This option also includes users who:

    • Commented on a page

    • Created or modified pages in the space

    • Are mentioned on a page

How each data type is migrated

Check how each data type is migrated and what are the best practices:


Migrate global templates

To add global templates to your migration:

  1. In the Global templates section, select one of the following options:

  • Migrate global page templates

  • Migrate custom system templates

  • Migrate all global templates

  • None

Select the global template to migrate

2. When you’re ready, select Add to migration.

Migrate spaces

To add spaces to your migration:

  1. In the Spaces section, select one of the following options:

Option

Description

All

Migrate all selected Confluence spaces, and their associated Team Calendars

Attachments only

Migrate only attachments from the selected Confluence spaces. Learn how to migrate attachments in advance.

2. Select the spaces you want to migrate.

Select space data to migrate, either select all components or migrate the attachments associated with the selected spaces
  • If you're using Confluence Cloud Migration Assistant 3.4.14 or higher for the first time, you'll see a loading message on the space selection screen displaying the percentage of space data being loaded.

  • If some space information can't be calculated, the data for such spaces will be displayed as '--' with a warning. Learn more about such warnings on the space selection screen.

  • You won't be able to migrate spaces with space keys that already exist in your Confluence Cloud destination site. Learn more about space key conflicts.

You can filter or search for particular spaces using the space name or key or select any of the following options in the table.

Space selection options

Description

Select all on this page

Selects all the spaces to be migrated on that particular page.

Select all

Selects all the spaces to be migrated on all the pages.

Clear all on this page

Clears all the spaces on that particular page.

Clear all

Clears all space selections on all pages.

If you’ve many spaces and attachments or you are on Data Center, you might want to break the migration up into a few smaller migrations. The migration assistant can be slow to load and process tasks when there is a lot to manage.

You can sort spaces by any columns shown on the space selection screen. Also, you can filter spaces according to their migration status and the date they were last edited. Here’s a brief description of the features on the space selection screen.

Features on space selection screen

Description

Select and sort spaces based on the migration status

The Migration status filter helps to filter spaces based on their migration status. The space migration statuses can be:

  • NOT IN ANY PLAN: The space hasn’t yet been added to any migration.

  • QUEUED: The space has already been added to a migration waiting to be run.

  • RUNNING: The space is currently migrating.

  • STOPPED: The space was added to a migration, but the migration was stopped at runtime.

  • FAILED: The space migration failed.

  • MIGRATED: The space migration is successful.

The Migration status column sorts spaces based on their migration status.

Filter and sort spaces based on when they were last edited

Last edited filter in space selection

The Last edited filter helps to filter spaces based on when edits were made related to an attachment, a page, or a space description. The edits don’t include views, likes, and comments.

The Last edited column allows you to sort the spaces based on the elapsed time since an attachment, a page, or a space description was edited.

Sort spaces based on the Pages column

The Pages column allows you to sort the spaces based on the total number of blogs, drafts, and current and previous versions of pages in the space.

Sort spaces based on the Attachments column

The Attachments column allows you to sort the spaces based on the total size of the space attachments.

Filter and sort spaces based on the Space type column

The Space type filter helps to filter spaces based on the type of space, whether Site or Personal.

Site spaces are shared spaces. Personal spaces are private spaces.

The Space type column allows you to sort the spaces based on the space type.

Sort spaces based on the Team Calendars column

The Team Calendars column allows you to sort the spaces based on the number of Team Calendars in the space.

Team Calendars is available as a feature in Confluence Cloud Premium and Enterprise. Your Team Calendars data is migrated regardless of the type of Confluence plan. But to access this data after migration, upgrade to Premium. Learn more about upgrading to Confluence Cloud Premium

3. When you’re ready, select Add to migration.


Migrate users and groups

To add users and groups to your migration:

  1. In the Users and groups section, choose one of the following options:

Option

Description

All users and groups from the Confluence directory

Migrate all users and groups from your Confluence users directory.

If you’re looking to speed up your migration, this option is faster. When migrating only a subset of users, the assistant needs to check them against every space in Confluence, which takes time.

Only users related to the selected spaces

Migrate only users that are referenced in the spaces you added to your migration plan, which includes users who:

  • Commented on a page

  • Created pages inside the space

  • Have permissions to access the space

  • Are mentioned on a page

When you choose this option, we always migrate some data connected to the spaces you’re migrating. This is to ensure that all mentions, comments, and page history stay active.

Some users in team calendar events may not be migrated

Users invited to Team Calendar events but not linked to selected spaces aren’t migrated. These users are not included and hence not added to your Team Calender events after migration.

To ensure all relevant users are migrated select the ‘All users and groups from the Confluence directory’ option or select all spaces that are linked to users in your Team Calendars.

If you have selected this option and have also selected any global template for your migration the following users will be migrated:

  • Users who created or modified the templates

  • Users who are mentioned on the template

2. When you’re ready, select Add to migration.


Migrate apps

To add apps to your migration:

  1. In the Apps section, choose one of the following options:

Option

Description

All

Migrate all apps that you marked as ‘Needed in cloud’ when assessing and preparing apps, and that have a migration path provided by the app vendor.

None

Don’t migrate any apps.

2. When you’re ready, select Add to migration.


Next steps

Once you’re done, check for errors in your migration. Learn how to check for errors in your migration plan


More information and support

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

Support for Atlassian Server products ends in February, 2024. Learn more about the Server end of support timeline.

Still need help?

The Atlassian Community is here for you.