General App Documentation
General App Documentation
Breadcrumbs

Migrate Metadata for Confluence to Cloud

Welcome to the Metadata for Confluence Migration Guide

We are here to make migrating your Metadata for Confluence app from your server instance to the cloud easier and more enjoyable. We support you to make your journey to the cloud successful. This document helps you plan, prepare, and execute the migration step-by-step.  

What is our roadmap to support migration?

  • check mark Migration of global Metadata values : Already possible.

  • check mark Migration of space Metadata values: While a fully automated solution is not possible, we currently offer a workaround to assist you with this process. Please contact us for detailed instructions on using the workaround.

  • check mark Migration of Display Metadata macro: Requires Metadata DC 3.15.0 or newer.

  • check mark Migration of global Metadata definitions: Requires Metadata DC 3.16.0 or newer.

Please follow this guide carefully to ensure a successful migration of your Metadata values.

Which technical requirements must be met?

Here is an overview of the technical requirements that must be met in order for a migration of the Metadata for Confluence app to be possible in principle.

Confluence Data Center side

Confluence, all supported versions

The latest version of the Confluence Cloud Migration Assistant (also known as CCMA) app. The CCMA is responsible for migrating Confluence data and Metadata to your Confluence Cloud instance.

Metadata for Confluence:

  • For basic migration support of Metadata values: version 3.14.0 or higher

  • For migration support of Display Metadata macros: version 3.15.0 or higher.

    • If you are using an older version, the value migration still works but Display Metadata macros will not be migrated automatically and must be recreated manually in Cloud.

  • For automatic creation of Content Categories from your global Metadata sets: version 3.16.0 or newer

Confluence Cloud

Metadata for Confluence

Pre-migration Checklist

Before you start the migration process, you must verify and establish the following preconditions. In addition, you should also familiarize yourself with the functional differences between the DC/server and cloud versions and consider the implications on the migration.

Please check the following conditions carefully to ensure a smooth migration. If one or more preconditions are not met, this may result in an incomplete migration or an aborted migration.

  1. Clean up duplicate titles: Check whether there are global Metadata sets or fields in your server instance that use the same title more than once. If you have global Metadata sets or fields with the same titles, this causes the migration to fail. The pre-migration app vendor check which is run by the CCMA will warn you about such cases.

  2. Only one Metadata set is assigned to a page: If more than one global Metadata set is assigned to a piece of content, the migration cannot start. The migration will fail and a new one has to be started after fixing the problem is resolved. The pre-migration app vendor check which is run by the CCMA will warn you about such cases and provides a CSV file that contains the affected pages.

  3. Carefully read the other sections of this document.

  4. Additional pre-requisites when Metadata DC version is 3.15.0 or earlier: The automatic migration of global Metadata set definitions to Content Categories is only supported when using Metadata DC 3.16.0 or newer. In all older versions you have to create the Content Categories manually in your cloud instance before starting a migration. For that consider the following:

    1. For each DC global Metadata set which is used on content in the spaces to migrate, there has to be a matching Content Category in cloud. The Content Category must have the same title (case-sensitive) and must contain a matching Metadata field for each field in the DC Metadata set. Additional fields in the Content Category are fine and do not affect the migration process.

    2. A Metadata DC and a cloud field are considered matching when they have the same title (case-sensitive), type (e.g. Text, User, Single select, …) and a compatible configuration. The latter only applies to the field types User (single/multi user mode), Single select and Multi select. For the select fields it is necessary that any option of the DC field also has to exist in the cloud field, again case-sensitive. Additional options for the cloud select field don’t affect the migration.

Specifics of Migration

  • Metadata definitions:

    • Starting with Metadata DC version 3.16.0, a new Content Category is created for each Metadata set which is in scope of the migration. A Metadata set is in scope when one of the following applies:

      • It is assigned to a content which belongs to one of the spaces that are selected for the migration.

      • Any of its fields is configured in a Display Metadata macro which is contained in a content of the spaces that are selected for the migration

    • If there is already a Content Category named like the Metadata set (case-sensitive), no new one is created. The existing one is also not modified in any way. If the existing Content Category is compatible with the Metadata set it will be used for migrating the values. Otherwise, no values of the Metadata set will be migrated.

      • Compatible means that the Content Category must have a matching field for each field of the Metadata set.

      • Two fields are matching if they have the same title (case-sensitive), type and configuration. The latter only applies to the field types User (single/multi user mode), Single select and Multi select. For the select fields it is necessary that any option of the DC field also has to exist in the cloud field.

      • The Content Category can have additional Metadata fields and the Select fields can have further options.

    • If the Metadata set has a global page template linked and there is a global page template with the same name in Confluence cloud, the Content Category will be linked to that template. The existing template is not renamed to the name of the Content Category.

    • If the Metadata set has no template, the Content Category will be created without a template.

  • Metadata sets not existing in Cloud: Metadata sets without a compatible Content Category (when preparing them manually, see also previous point) will be ignored and the values of that set are not migrated. The migration log will contain warning messages for such cases.

  • Hidden Metadata fields: The values of hidden Metadata fields are migrated. Since the cloud app doesn’t support hidden fields, such fields and their values become visible.

  • Metadata assigned to blog posts: Metadata for Confluence Cloud doesn’t fully support assigning Metadata to blog posts. If your DC Confluence contains blog post with global Metadata, the values will be migrated. You will have to add a Display Metadata macro to the blog post to see the values in Cloud.

  • Only selected spaces are considered: Metadata for Confluence integrates with the CCMA. It only migrates the global Metadata values and Display Metadata macros of content in the selected spaces.

Limitations

Space Metadata

At the moment, migration is only supported for global Metadata sets and fields. Support for migrating space Metadata is still in planning, but not yet finalized.

However, if you need to migrate right now we might be able to provide a workaround. Please contact us for more details.

Global Metadata definitions

The automatic creation of Content Categories from the global Metadata sets and fields is only supported when using Metadata DC 3.16.0 or newer.

The descriptions of the Metadata sets are not yet migrated.

Macros

The Display Metadata macro is now automatically migrated. Depending on how it was configured in DC, it will arrive in Cloud as either the Display Metadata or the Display Metadata Value macro.

Known limitations of Display Metadata macro migration:

  • Only supported when the Metadata DC app is version 3.15.0 or newer. When using an older version, macros are not migrated and must be recreated manually in Cloud.

  • If the macro had display options not supported in Cloud (e.g. showing author or last modified date), those options will be ignored. A warning will be written to the Confluence DC application logs.

  • If the macro is configured in a way which can’t be handled by the cloud app, it won’t be migrated and a warning will be added to the Confluence DC application logs. An example is a macro which is setup with the “Render mode” set to “value” and no or more than 1 field selected in the “Metadata fields filter”.

  • Display Metadata macros which are contained in the body of other Confluence macros might also not be migrated because of limitations in the Confluence Cloud page editor. Such cases will be reported with a warning in the migration CSV log file.

The Overview macro (renamed to Report macro in Cloud) is not automatically migrated and requires manual configuration after migration.

For more information regarding supported macros, please check Cloud vs Server - Metadata for Confluence Differences .

Metadata History

Changes to Metadata values are logged in the Data Center/server version. This feature is not available in the cloud app and therefore the Metadata History is not migrated.

Field Type Specific Limitations

When migrating Metadata values, restrictions may apply to certain field types. Those are listed below and you should be aware of them.

  • User field

    • Unavailable user: User field values can only be migrated when the referenced users have been successfully migrated with CCMA. If a user is not available in Cloud, the migrated value of this field be displayed by our cloud app as "Unknown user". This indicates that the user could not be mapped during migration.

    • User field modes: If a DC User field is set to “Multiple users” and the cloud field is set to Single user, a mapping is not possible. In such cases, the whole global Metadata set is ignored during migration. However, a DC User field set to “One user” can be migrated to a cloud Metadata Multi-user field.

  • Single and Multi select fields

    • Migrate Single select into Multi select field: A Single select field defined of the DC app can be successfully mapped to a Multi select field on the cloud side. However, a DC Multi select field cannot be mapped to a cloud Single select field. In such cases, the Metadata set containing the field will not be mapped to a Content Category and all Metadata values of that set will be ignored during migration.

    • Migrate Single/Multi select field with more than 30 options: The migration will fail if a DC Single or Multi select field has more than 30 options.

  • Link field

    • URL links: In the Data Center app you can add URLs to arbitrary web pages as a Link field value. The cloud app only supports Confluence pages as values (see Cloud vs Server - Metadata for Confluence Differences). During migration only Confluence pages are considered and the URLs will be ignored.

    • Missing values: Only Link field values that point to pages which are part of the current migration or were contained in a previous migration are considered. If a page exists in the Confluence DC instance but has not been migrated to the cloud instance, the Metadata field will show it as "Unknown page" after the migration.

  • Group field

  • Custom field types

    • Fields that have been created by using our Metadata API Quick Setup of Metadata API (v 3.3) and their values are ignored during the migration process because they cannot have a matching field type in the cloud app.

Migration Steps

Use the following steps to migrate your Metadata with the help of the CCMA from Date Center to Cloud.

Preparing a migration

To prepare a Metadata migration to cloud we recommend the following steps.

  • Enable INFO logging: Depending on the amount of data to be migrated, the export of it on DC side can take rather long. Since Atlassian’s CCMA doesn’t support updating the progress in that phase, it will stay at 0%. To keep you informed, Metadata will write updates to the application logs of your DC Confluence. For seeing it in the logs, you have to enable INFO logging for package com.communardo.confluence.metadata.migration.cloud as documented by Atlassian.

  • Pre-migration checklist: Work through the pre-migration check list and consider the limitations described above.

Running a migration

Follow the official Atlassian documentation for migrating to cloud with the help of the Confluence Cloud Migration Assistant.

  • App vendor checks: When the pre-migration check of the CCMA reports that the “App vendor checks” have warnings review them carefully and resolve them. In some of the cases for which Metadata raises a warning, the migration of Metadata values will fail!

After a migration

After the migration completed, review the migration log carefully. The location of that log depends on the version of Metadata DC.

  • Metadata DC version 3.14.0: The migration log can be accessed from a special page in the Metadata cloud app. You can find more details in Metadata Cloud Migrations.

  • Metadata DC version 3.15.0 and newer: The log can be downloaded as a CSV file from the CCMA by selecting the “View logs” action. Some hints for reading it:

    • Every row represents a log entry with the newest one on top.

    • The most interesting part of such an entry is the “Message” column.

    • If the value in the “Message” column starts with “ERROR” then the Metadata cloud migration failed for the given reason. Some Metadata values could, however, have already been migrated. Depending on the cause a re-run of the migration could work. The message should give some guidance.

    • When the value in the “Message” column starts with “WARNING” then this usually means that Metadata values or Display macros for certain pages couldn't be migrated. In such cases you can find additional information about the cause and the affected DC page (and cloud page if possible) in that log entry. This can help you to solve the issue manually.

    • In case the value in the “Message” column isn’t prefixed with one of the words mentioned above, then it’s purely informational.

    • Please note that the CSV log, unfortunately, has a limit of 4,000 lines. If your migration involves a very large amount of content, the log may be truncated and some earlier messages might not be contained. A special log entry will inform you about that.

If you encounter any issues or have questions during the migration process, our support team is available to assist you. Please reach out to our customer support for prompt and reliable assistance.