Data Migration
Migrating from Other Tab or Formatting Apps to Content Formatting Macros
If your Confluence space currently uses another tab or formatting app (e.g., Comala, Scroll Viewport, Brikit Theme Press, or other tab macro apps), this guide covers what to expect when switching to Content Formatting Macros.
Before You Migrate
Step 1 - Audit Your Current Usage
Before installing Content Formatting Macros, take stock of what you're replacing:
- Identify all pages that use the old tab/formatting macros
- Note the tab structures in use - how many tabs, what content type, mapper vs. manual
- List any conditional visibility or CSS customization features you rely on
- Check if any page templates reference the old macros
Step 2 - Install Content Formatting Macros First
Install Content Formatting Macros before uninstalling your old app. This allows you to:
- Test the new macros side by side on a copy of a key page
- Validate rendering and feature parity before committing
- Train page authors on the new workflow before removing the familiar interface
Step 3 - Map Old Macros to New Macros
| Old Pattern | Content Formatting Equivalent |
|---|---|
| Manual tab macro (other app) | Custom Tabs |
| Dynamic tabs from child pages | Tab Parent Content Mapper |
| Tabs by label/tag | Tab Label Content Mapper |
| Hand-picked page list as tabs | Tab Page Mapper |
| Show/hide section (role-based) | Conditional Show / Conditional Hide |
| Custom CSS background | Background Macro |
| Styled button link | Buttons Macro |
| Styled expand/collapse | Advanced Expand Macro |
Migration Process (Per Page)
For Pages with Manual Tabs
- Open the page in edit mode
- Note the content in each tab of the old macro
- Type "/" → search Create Custom Tabs → insert it directly on the page below the old tab macro
- Add a tab for each section and copy the content from each old tab into the corresponding new tab
- Once the new tabs are verified, delete the old tab macro
- Publish
For Pages with Dynamic Tabs (Child-Page Based)
If your old app populated tabs from child pages, the Tab Parent Content Mapper is the direct equivalent:
- Type "/" → search Tab Parent Content Mapper → insert it directly on the page
- Configure the Parent Page in the mapper config panel
- Compare the tab output against the old macro's output
- If the output matches, delete the old tab macro
- Publish
For Pages with Conditional Visibility
- Identify the condition used in the old macro (group name, role, or login status)
- Insert the equivalent Conditional Show or Conditional Hide macro
- Configure with the same condition
- Test with users in the target group
- Delete the old macro and publish
What to Expect When Uninstalling the Old App
When you uninstall your previous tab or formatting app:
| What Happens | Details |
|---|---|
| Old macros stop rendering | Macro placeholders appear in their place - {old-macro-name:...} - visible in edit mode; in view mode they typically show as empty space or a "Macro not found" message |
| Page content is NOT deleted | All page text, images, and Confluence content remain intact - only the macro rendering is affected |
| Macro storage is retained | The macro parameter data is stored in the page's storage format and remains in the page even after uninstall - it's just not rendered |
| Re-install restores rendering | Re-installing the old app restores rendering of the old macros |
Macro Content Persistence on Pages
Confluence stores macro parameters (the macro's configuration settings) as part of the page's storage-format XML. This means:
- When an app is uninstalled, the macro parameters remain stored in the page - they are not deleted
- The macro body content (content you typed inside a macro) is also preserved
- If you re-install the old app, all macros return to their fully rendered state
Important implication for migration: If you migrate pages to Content Formatting Macros and then delete the old macro instances, the old macro data is permanently removed from the page. This is typically the desired outcome, but make sure you have verified the migration before deleting.
Rollback Plan
If you need to roll back after starting a migration:
- Do NOT uninstall Content Formatting Macros - uninstall would leave its macros unrendered
- Re-install the old app if you uninstalled it - this restores old macro rendering
- Pages where you have already replaced old macros with Content Formatting macros cannot be automatically reverted - those pages must be manually updated or restored from Confluence's page history
Recommendation: Use Confluence's Page History feature before migrating important pages. This gives you a point-in-time restore option if a migration goes wrong.
Getting Help with Migration
If you are migrating a large Confluence space (100+ pages with tab macros) and need assistance, contact the Clovity support team:
- Email: developers@clovity.com
- Subject: Migration Assistance: [your Confluence site URL]
Include the number of pages involved, the app you are migrating from, and your timeline. The support team can provide migration guidance and tooling recommendations.