Metadata for Confluence - Server to Cloud Migration Guide

Owned by Enrico Kutscher
Last updated: Mar 08, 2024 by Juela Zeneli
5 min read

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?

  • Migration of global Metadata values : Already possible.

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

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 / Server side

Confluence, all supported versions

Confluence Cloud Migration Assistant, version 3.4.7 (or higher)

Metadata for Confluence 3.8.0 (or higher)

Confluence Cloud

Metadata for Confluence

Pre-migration Checklist

Before you start the migration process, it is mandatory to check and establish the following preconditions. In addition, due to functional differences between the DC/server and cloud versions, there are also migration implications that you should consider.

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

  1. Clean up duplicate titles: Check if there are global Metadata sets or fields in your server instance whose titles are used more than once. If you have global Metadata sets or fields with the same titles, this causes the migration to fail.

  2. Verify Content Category configurations: A prerequisite for the migration of Metadata values of a global Metadata set is that a matching Content Category exists. It needs to have same title (case sensitive) and must contain a matching Metadata field for each field of the server app. Additional fields in the Content Category are fine and do not affect the migration process.

  3. Verify Metadata fields configuration: Make sure the configuration settings for each Metadata field match between your server and cloud instances. For Single and Multi select fields any option that exists on the server must also exist in the cloud. Additional options for Metadata fields of a Content Category on the cloud side may be present and do not affect the migration process.

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

Specifics of Migration

  1. Hidden and Required Metadata fields: The values of hidden and required Metadata fields are migrated. Thus, the affected Metadata fields and their values become visible and are no longer required fields in the cloud.

  2. Metadata assigned to BlogPosts: If you have assigned Metadata sets to BlogPosts that are not officially supported by Metadata for Confluence Cloud, the values will be migrated and are available after migration.

  3. Metadata sets not configured in cloud: Metadata sets that have no equivalent Content Category on cloud will be ignored.

Limitations

Space Metadata

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

Macros

The migration does not include migration of macros or their configuration. For more information regarding supported macros by Metadata on Confluence cloud, please check https://communardo-products.atlassian.net/wiki/spaces/METADCLOUD/pages/8257783

Metadata History

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

Field Type Specific Limitations

When migrating Metadata values, restrictions may apply to certain field types. These 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 Atlassian’s cloud migration assistant. If a user is not available in the cloud, the migrated value of this field is displayed in the cloud as "Unknown user". This indicates that the user could not be mapped during migration.

    • User Field Modes: If a server 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 server User field set to “One user” can be migrated to a Metadata Multi user field of the cloud.

  • Single and Multi select fields

    • Migrate Single select into Multi select field: A Single select field defined in the server app can be successfully mapped to a multi-select field on the cloud side. However, a multi-select field in the server app cannot be mapped to a single select field on the cloud side. In such cases, the Metadata field and its associated set will not be mapped, resulting in the exclusion of all values during migration.

    • Migrate Single/Multi select field with more than 30 options: The migration will fail for a single/multi-select field from the server app with over 30 options.

  • Link field

    • Missing Values: To be mapped, only Link field values that point to pages within the current or a prior migration (within a 5-day timeframe) are considered. Furthermore, these pages must still exist in the cloud. If a page exists in the server app but not in the cloud app, the Metadata field will be filled with the value "Unknown page" after the migration.

    • External Link Values: Metadata values representing external links cannot be migrated to the cloud. Such values are ignored.

  • Group field

  • Custom field types

Migration Steps

Step 1. Follow official Atlassian Documentation on how to migrate app data from your server to cloud instance. . Metadata for Confluence integrates in this migration process and only migrates the global Metadata values of content in the selected spaces.

Step 2. After the migration is completed, check the on the Confluence Administration. There you will find information related to your migrations, including their status and a short summary.

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 support channels for prompt and reliable assistance.