Step 1: Plan your Scaffolding migration

Owned by Shane Smith
Last updated: Oct 08, 2024
4 min read

Overview

This document explains how to plan your Scaffolding migration.

Confluence Cloud currently does not support nested macros (See CONFCLOUD-68323).

This means integration with other apps by way of nesting will be limited.

This Atlassian documentation lists the Confluence macros that go through changes when converted to the new editor in Confluence Cloud. 

On this page:

On this page:

 

 

 

 

Upgrade the Scaffolding app

Update the Scaffolding app to at least version 8.25.0 through the UPM inside the Confluence administration console.

  1. Click the global admin icon.

  2. Click Manage apps.

  3. Search for Scaffolding.

  4. Ensure the app is updated to the most recent version.

 

 

 

Find all the Scaffolding macros

  1. Ensure that the site search indexes are current.

  2. Choose one of the 2 options below to assess data compatibility between the Scaffolding Server and the Cloud:

Option 1: Use the Macro Usage details page

The Macro Usage page will give you the number of Scaffolding macros on your site and the pages that contain them.

  1. Navigate to Administration > Macro Usage.

Or access the macro usage information via the shortcut  <base-url>/admin/pluginusage.action .

  1. look under Scaffolding.

  2. Record:

    1. the number of Scaffolding macros on your site.

    2. identify how many cannot be migrated.

In this example, the ones marked will not be migrated to the Cloud.

  1. Select the macro links to show you all pages containing those macros.

 

 

Option 2: Use the SQL query below

Use the sample SQL queries below to help you gather all pages and templates that contain unsupported Scaffolding macros.

This example uses PostgreSQL query syntax; please adjust usage according to your database syntax. Also, to avoid performance issues, limit the outcome to a smaller scope if needed (using limit may help).

 

Relevant page titles SQL

  • This SQL will provide a list of impacted page authors and the relevant page titles that currently contain Scaffolding macros that are unavailable in the 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="hidden-data"%' or bc.body LIKE '%ac:name="repeating-data"%' or bc.body LIKE '%ac:name="get-data"%' or bc.body LIKE '%ac:name="excerpt-data"%' or bc.body LIKE '%ac:name="eval-data"%' or bc.body LIKE '%ac:name="set-data"%' or bc.body LIKE '%ac:name="label-options"%' or bc.body LIKE '%ac:name="group-data"%') order by s.spacekey, c.title

Relevant template SQL

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

select s.spacekey, s.spacename, p.templatename as "Template Title", um.username from pagetemplates p left join spaces s on p.spaceid = s.spaceid left join user_mapping um on p.creator = um.user_key --left join where p.prevver is null --and p.creator = um.user_key and p.content LIKE '%ac:name="hidden-data"%' or p.content LIKE '%ac:name="repeating-data"%' or p.content LIKE '%ac:name="get-data"%' or p.content LIKE '%ac:name="excerpt-data"%' or p.content LIKE '%ac:name="eval-data"%' or p.content LIKE '%ac:name="set-data"%' or p.content LIKE '%ac:name="label-options"%' or p.content LIKE '%ac:name="group-data"%' order by s.spacekey, p.templatename ;

Prepare the Scaffolding data in server

Know your Scaffolding structure and data in server to anticipate incompatibilities in Cloud after migration. As the Scaffolding server is more versatile than Scaffolding Cloud, it is important that admins understand what's inside their scaffolding structure, and anticipate what is not migratable. 

Due to CCMA Limitations: Global templates will not be migrated automatically and have to be manually migrated instead. (Bug report:  MIG-190 - Consider making the Confluence Assistant migrating Global Templates)

As a workaround, you can copy all Global Templates manually into Space Templates before the migration, in order to migrate them to Cloud. You may copy the migrated templates back to Global templates after the successful migration.

Detailed step-by-step instructions are available on this page - Global Template is not automatically migrated to Cloud.

Create a staging instance, and perform a test migration on sample data

This is a recommended best practice step.

Test migration with staging instance

  1. Create a Staging environment licensed by a developer license.

  2. Create a snapshot of the current Confluence server, and clone it for the staging instance.

Test data by creating sample space

  1. Identify a space that contains:

    1. Space templates that are widely used in your organization and use Scaffolding macros.

    2. Pages with Live Templates that are using the Space templates.

  2. Clone the contents of that space to a new space.

  3. Now you are ready to migrate.

  4. Prepare a migration window as highlighted below.

  5. Go through the Test migration as highlighted in Step 1: Plan your Scaffolding migration | Find all the Scaffolding macros and Step 1: Plan your Scaffolding migration | Prepare the Scaffolding data in server

Schedule the migration window

To estimate the time you will need for the migration steps, we recommend reviewing all of the steps before executing.

Depending on the size of the data and the complexity of the existing template configuration, it may take a few hours to complete these steps.

We advise you to schedule a maintenance window in your organization to perform the migration.

Next Steps

Questions?

Contact us via our support portal.

 

 

Â