Migration best practices for Advanced Tables for Confluence from Data Center to Cloud
Migrating Advanced Tables for Confluence from a Data Center (DC) instance to Confluence Cloud involves planning, compatibility validation, and a few key post-migration steps. This page consolidates best practices derived from real customer migrations and Appfire support insights.
1. Pre-migration preparation
Before using Atlassian’s Confluence Cloud Migration Assistant (CCMA):
Upgrade app versions
Environment | Required version |
|---|---|
Data Center | v8.8.7 or later |
Cloud | Latest available version |
Important notes:
Migration is supported from Advanced Tables Data Center version 8.8.7.
Install and update Confluence Cloud Migration Assistant (CCMA) on the DC instance.
Ensure the cloud app is installed before creating or running the migration plan in CCMA.
Version compatibility for Migration to Cloud (Forge app):
For Confluence DC < 9.5.4 → Use Advanced Tables DC 8.8.7
For Confluence DC 10.0+ → Use the latest DC app version
2. When is migration of the Advanced Tables app using CCMA required?
Migration of the Advanced Tables app using CCMA is required only when the Profiles feature is actively used.
In most cases, customers primarily use the Table Plus macro, which does not require Profiles and does not depend on app migration.
2.1. When app migration is not required
You can safely skip the Advanced Tables app migration using CCMA if:
You are using Table Plus, Attachment Table, or standard formatting features.
You are not using Profiles.
CSV or JSON Table macros are used without specifying a Profile name.
In these cases, Advanced Tables macros migrate as part of the regular space migration, and no additional app migration step is needed.
Skipping unnecessary app migration often results in a smoother and faster overall migration.
2.2. When app migration is required
App migration using CCMA is recommended if:
Profiles are actively used.
Multiple CSV or JSON Table macros reference Profiles.
2.3. Best practice before deciding
Before initiating the Advanced Tables app migration:
Verify whether Profiles are actually in use.
Share Profile usage details with the Support team.
We will help determine the most seamless migration approach based on your setup.
3. Staging test migration (Strongly recommended)
Run a pilot migration of 1–2 representative spaces containing:
Table macros (Table Plus, Attachment Table, CSV, JSON Table).
Profile-based macros (external URLs).
Formatting, filtering, and nested content(for example, Table, JSON).
Then:
Compare content and rendering between DC and Cloud.
Look for unknown macros, infinite loading, or broken data links.
3.1. Specific to Production migrations
During migrations, CCMA might display 0% progress for Advanced Tables, even if the data has already migrated successfully. This is most commonly observed during production moves and can be misleading since the UI does not always reflect the true state.
Likely cause:
Profiles are not present in DC, but the app is included in the migration plan.
Or
The migration plan status does not update due to incomplete plugin sync (Cloud app registration to receive migration events from CCMA).
Checklist:
Profiles on DC
If no profiles exist, the Advanced Tables migration can be skipped.
If profiles exist, proceed to step 2.
Profiles/Data on cloud
Check the pages where profiles are applied.
Confirm if authentication is needed and ensure profiles are enabled and valid.
If the data is visible, the migration is complete, even if CCMA shows 0%.
If data is not visible, reinstall Advanced Tables on Cloud and re-run the app migration using the same plan.
Manual profile recreation (Workaround):
Even if Profiles exist in the Data Center instance and you are observing CCMA app migration failures, migration can proceed without using CCMA for Advanced Tables app migration (for example, due to version incompatibility), and the profiles can be manually created in Cloud.
For steps to create and configure profiles in Cloud, refer to:
Configuration - Cloud | [inlineExtension]Profiles
4. Post-migration review
After the migration:
Reconfigure global settings in Cloud (for example, allow JavaScript).
Test profile-based macros (re-configure or re-authenticate profiles if needed).
Check macro rendering on critical pages.
Use Macro Usage under General Configuration > Data Management to validate page usage.
Unsupported macros will show as “unknown macro” errors on migrated pages.
Workaround: replace the JQL macro with the Jira Issue Macro in the cloud.
5. Compatibility Matrix (DC → Cloud)
Confluence DC version | DC app version | Cloud app version | Migration supported |
|---|---|---|---|
10.0.1 onwards | 9.0.1 onwards | Latest version (Forge) | ✅ Yes |
8.4.0 onwards | 8.8.7 onwards | Latest version (Forge) | ✅ Yes |
< 8.4.0 | < 8.8.7 | Latest version (Forge) | ❌ No (Upgrade Confluence DC and Upgrade app) |
10.0.1 onwards | 9.0.1 onwards | Connect-on-Forge | ❌ No (Upgrade Cloud app to latest) |
8.4.0 onwards | < 8.8.7 | Connect-on-Forge | ✅ Yes |
< 8.4.0 | < 8.8.7 | Connect-on-Forge | ❌ No (Upgrade Confluence DC ) |
6. Troubleshooting tips
Symptom | Possible cause | Action |
|---|---|---|
App migration delay with no data(CCMA shows 0%) | No profiles on DC/Cloud, macro-only use | Skip app migration using CCMA |
Cloud app is not registered to receive migration notifications | App/CCMA version mismatch or stalled app registration | Upgrade app(DC/Cloud) and CCMA to the latest version → Cancel migration → Re-run app migration → Validate using Macro Usage |
Infinite loading spinner macro | Profiles with no valid configuration on the macros | Re-check profile configuration, re-authenticate if needed |
Unknown macro | App not installed before migration | Install the app in the cloud and retry rendering |
Unable to access attachments — 404 Not Found error encountered | Incorrect base URL or API path | Check if attachments are inaccessible from the Attachment panel, and if so, please contact Atlassian Support |
Table Plus headings are missing from the “Table of Contents” post-migration | Known issue on Atlassian's side(CONFSERVER-41313) | Manually update the affected pages |
Unexpected Error Occurred | Broken links | Check for incorrect data link settings (Attachments, Labels) |