Step 1 - Plan Out Your Migration (Composition)

Owned by Li Xuan Liew (Deactivated)
Last updated: Sept 21, 2023 by Smita Nair
6 min read

Use the steps on this page to plan for complete migration from Composition Server to Composition Cloud:

Prerequisites

Guide

1. Upgrade the Composition Tabs macro

  • Update the Composition tabs macro to at least version 5.14.1 through the UPM inside Confluence administration console.

    1. Go to  >   Manage apps

    2. Search for Composition. Make sure that the app is updated.

2. Find all the Composition Tabs macros

  • Complete the steps below to assess data compatibility between Composition Tabs for Server and Cloud.

  • In summary: 

    • Prepare deck and card macros as mentioned in the section below, "Prepare the Tabbed Content data in Server".

    • For macros that cannot be migrated, please alert users to take the next actions if needed. (The SQL shown in Option 2 below may be more helpful in this regard, as it can also provide hints about the authors of these contents.)

  • Upon completion, you will know which data will not be compatible with Composition Tabs Cloud. Choose one of the 2 options below:

Option 1: Use the Macro Usage details page

  1. The Macro Usage page will give you the number of Composition macros on your site, and the pages containing those macros.

  2. Go to Administration > Macro Usage. Or access it via the shortcut <base-url>/admin/pluginusage.action.

  3. Look under Composition. 

    1. Take note of how many Composition macros are on your site, and how many of them need to be actioned, and how many of them cannot be migrated.

    2. Macros that cannot be migrated are shown below, you can find more information on the feature differences page.

  4. Clicking on the macro links will show you all pages that contain those macros.

Option 2: Use the SQL query below

  1. The sample SQL query below to help you gather all pages and templates that contain macros that will not be migrated to Cloud.

     

  2. This SQL will provide a list of impacted page authors and the relevant page titles which currently contain Composition macros that are unavailable in Cloud.

select s.spacekey, s.spacename, c.title as "Page Title", um.username from content c, spaces s, user_mapping um left join cwd_user cu on um.username = cu.user_name where c.spaceid = s.spaceid and c.contenttype = 'PAGE' and c.prevver is null and c.content_status = 'current' and c.creator = um.user_key and c.title in (SELECT c.title FROM CONTENT c JOIN BODYCONTENT bc ON c.contentid = bc.contentid JOIN SPACES s ON c.spaceid = s.spaceid WHERE c.prevver IS NULL AND c.contenttype IN ('PAGE', 'BLOGPOST') AND bc.body LIKE '%ac:name="banner"%' or bc.body LIKE '%ac:name="composition-setup"%' or bc.body LIKE '%ac:name="cloak"%' or bc.body LIKE '%ac:name="toggle-cloak"%' or bc.body LIKE '%ac:name="float"%' or bc.body LIKE '%ac:name="show-card"%') order by s.spacekey, c.title

3. Prepare the Tabbed Content data in Server (Convert Deck and Cards macro to Tab and Group of Tabs macro)

This is a pre-requisite step for Confluence Server & Data Center users who are planning to migrate to Confluence Cloud and have pages that use the Deck of Cards and Card macros from Composition Tabs.

  • Pre-migration overview

    • These pre-migration steps in this article are crucial for avoiding clashes with similarly named macros on Confluence Cloud. On Cloud, there are currently Confluence-native macros which are also called Deck and Card (these are not ServiceRocket macros). More details are available in this bug report.

    • As part of the migration process, a ServiceRocket pre-migration tool is available which can rename all Deck and Card macros to Tab Group and Tab macros. On Confluence server, Tab Group and Tab macros behave exactly the same way as Deck and Card macros previously do, but with a different name.

    • Once this process is completed, administrators can then run the Confluence Cloud Migration Assistant to migrate all their content to Confluence cloud.

  • What happens during this process?

    • All content that contains Deck of Cards and Card macros, including pages and comments, will be updated to the new macro names, Tab Group and Tab.

    • After the macros are renamed, your content will be displayed as it was previously. You can still view, edit and use your updated tabbed content as before on this site.

Before 

After

Before 

After

If new Deck and Card macros are created on your server after the rename process, you will need to run the pre-migration tool again before migrating to Confluence Cloud. For example, If you have completed this process for migration test purposes, but your users continue to add new content with Deck and Card macros, you will need to run the tool again before doing the production migration.

Before you start

  • Make sure you have updated your Composition plugin to the newest version (5.14 or above) 

  • Use the Macro Usage details page (highlighted above) to get an idea of how many macros and pages will undergo this transformation

 

  • Run the pre-migration tool

  1.  

    1. Go to Confluence Admin console.

    2. Under Composition Configuration, select Composition Cloud Pre-migration Tool.

    3. On the pre-migration page, the following information can be seen:

      1. Number of contents to update - A count of all content pages that still use the  Deck  and Card  naming convention.

      2. After a first run of this process, the page will be updated with the following information:

        • Previous run - The date and time of the last run. 

        • Number of contents updated - Accumulated total number of content pages with renamed macros (refer to the screenshot in step 5)

    4. Click Run update. The button will be greyed out, and there will be a spinner to indicate that the macro rename process is in progress.

    5. The button is disabled when the process is completed. The page is updated with details such as Previous run and Number of contents updated.

       

    6. All pages that have been updated will have a new entry under Page History with the comment "Composition Migrator: Move Deck & Card macros to Tab & Tab Group Macros".

    7. The number of pages that contain Deck and Card macros in the Macro Usage menu will be updated