Cloud Migration (v 3.5)

Owned by Andreas Ebert
Aug 01, 2024
4 min read

Welcome to the Cloud Migration Documentation for our app User Profiles for Confluence!

This comprehensive guide provides an in-depth overview of the steps and considerations involved in migrating your app to Confluence Cloud. Whether you are an administrator, developer, or a member of the migration team, this documentation is designed to assist you throughout the process.

In this documentation you will find detailed information about which content is not migrated and which is migrated and therefore prepared for migration. We also outline the User Profiles for Confluence content that will be prepared and those that won’t be. Additionally, we explain the steps involved in the preparation process, with a focus on updating macro instances.

Supported User Directories in the Cloud App

As of the current version, our cloud version exclusively supports Microsoft Entra ID (previously Azure AD) as the User Directory. To consider migrating to Cloud, your organization should already use or plan to use Microsoft Entra ID for identity management.

Migration Process and Preparation

In general, only our app’s macros are prepared for migration, and currently, only the most important macros. We are continually working to expand the app’s capabilities, and this documentation will provide insights into the macros that can be migrated successfully.

How to perform the preparation

To prepare your macros for migration, follow these steps:

  1. Go to User Profiles Configuration: Access the User Profiles Configuration in Confluence.

  2. Navigate to the "Cloud Migration" section: Within the User Profiles Configuration, navigate to the "Cloud Migration" section.

    Navigate to 'Cloud Migration' section of User Profiles Configuration
    Image 1: Navigate to "Cloud Migration" section of User Profiles Configuration

  3. Select the Spaces to migrate: In the "Cloud Migration" section, specify the spaces that you want to migrate. You can provide these spaces as a comma-separated list of space keys.

  4. Upload CSV file: Provide a CSV file containing user data from Microsoft Entra ID. Please refer to Microsoft Entra's documentation for guidance on creating this file.
    Uploading this data is essential for ensuring that your macros continue to function seamlessly after the migration, i.e. display the correct user’s data (for technical details, see What does the app do during the preparation process).
    The data contained in the uploaded CSV file will only be available to your Confluence instance and will not be send to Atlassian or to us.

    Image 2: Macro preparation ready to get started

  5. Validate since 3.4.2: Click on “Validate macro preparation”. After validating your input a summary about the macro preparation to be carried out will be displayed. It will contain information about the affected spaces and the user data from Microsoft Entra ID.

  6. Start: Click on the Start button to start the preparation process.

 

What does the app do during the preparation process

  • Update Macro Instances: All instances of Enhanced Profile and Profile macros will be updated to ensure compatibility with the Cloud version. During this process, the names of the macros will be changed, and user mappings to Entra ID users will be performed and added to the macro instances, to ensure seamless functionality in Cloud.
    The updated macro instances will show a badge indicating their Cloud-readiness.

  • New Version History: During the update process, a new version of the content will be created. This new version will be documented in the page history of the page or blog post to track changes and revisions.

Migrated content

Confluence content

Our app provides a streamlined process for preparing content for migration. Please note that while Confluence supports a wide range of content types, our app is specifically designed to support these content types:

Prepared

Not prepared

  • Pages

  • Blog posts

  • Comments

  • History of pages and blog posts

  • Shared drafts

  • Custom templates

User Profiles for Confluence content

Prepared

Not prepared

  • Enhanced Profile macro: always

  • Profile macro: if overriding of the default Profile macro is enabled in User Profile Configuration (→ Administration → User Profile Configuration → Advanced Options → Enable Enhanced Profile Macro)

  • Profile List macro: always

  • Organization Chart macro

  • Organization Chart (compact) macro

  • Any data not specific to macros

Finding content with unmigrated macros

Enhanced Profile macro

In Confluence Data Center (before Cloud migration): Content with unmigrated macros can be found with the search-query macroName:enhanced-profile OR macroName:profile. So, go to Confluence’s search, enter this query, optionally filter for your spaces, and the results should list all content (pages, blogposts, comments) with unmigrated macros.
If no results are found, then no unmigrated content are left in your spaces, and you are good to go for your Cloud migration.

In Confluence Cloud (after Cloud migration): Content with unmigrated macros can be found by performing an advanced search using CQL with the query macro IN ("enhanced-profile", "profile"). Since CQL is not accessible on Confluence’s search page, you have to access it directly by navigating to the correct URL. An example for site “my-site” is: https://my-site.atlassian.net/wiki/search?cql=macro IN ("enhanced-profile", "profile")

Profile List macro

Profile List macros will be in an unmigrated state after moving content to the cloud. The macro will be diplayed like this:

The parameter “criteria“ contains a Lucene query that needs to be migrated manually to the new filter of the contact list macro. During this process the original set value from the on premise environment will be shown. After saving the Macro the migration specific messages will disappear.