--- title: "Migration preparation guide" canonical: "https://help.refined.com/space/MIGRATETOOLKITCLOUD/7082442893/Migration%20preparation%20guide" format: markdown --- ## Introduction This guide will help you prepare for your migration to Cloud with Toolkit. There are a few important changes to be aware of. Please review this page to understand how Refined Toolkit works on Cloud and what to expect during and after your migration. **What do you need to know?**
Step 1: Understand the Cloud Toolkit apps - **Refined Toolkit is now two apps on Cloud** On Cloud, Refined Toolkit has been split into two separate apps: **[Refined Macro Toolkit](https://help.refined.com/space/MACROTOOLKIT/5635604632/Macros)** – content formatting macros **[Refined UI Toolkit](https://help.refined.com/space/UITOOLKIT/5628854324/Get+started)** – Page Builder and navigation components We know our customers use Refined in different ways. This allows you to install only the functionality you need. - **Both Toolkit apps are available on**** ****[Forge](https://developer.atlassian.com/platform/forge/)**** (from July 2026 onward).** Forge is Atlassian's modern Cloud platform. Forge Native apps run entirely on Atlassian's infrastructure, offering better security, improved reliability, long-term compatibility with Atlassian Cloud and no customer data leaving Atlassian's environment. - **Review your macro content to choose which apps you need.** | **Feature** | **Macro Toolkit** | **UI Toolkit** | | --- | --- | --- | | **Content formatting macros **(Panels, tabs /expands, countdown etc.) | ✅ | ❌ | | **Page Builder macro **(Advanced page layout & formatting) | ❌ | ✅ | > ⚠️ **Not sure? Contact our Support team.** It's important to identify which macros you use before migrating to Cloud to ensure you install the correct Toolkit apps and avoid disruption.
Step 2: Using nested Refined macros? Read this first. Before migrating, review how nested macros are affected. This will help to avoid unexpected changes after migration. If your pages contain **Refined Step Container, Refined** **Tab Container, or Refined** **Expand Container** macros, it's important to understand how nested content behaves after migration. > ❌ After migration, **native Atlassian and third-party macros** nested inside Refined macros (Refined Step Container, Refined Tab Container, or Refined Expand Container) **will not be visible on published pages.** ### What changes after migration? | If you have... | What happens | | --- | --- | | **Native Atlassian macros** nested inside Refined container macros | They remain in the page and are **editable**, but **will not be visible on published pages** until moved outside the Refined container macros. | | **Third-party or Connect-on-Forge macros** nested inside Refined container macros | Same behavior as above. Content is preserved and **editable,** but **not visible** until moved outside the Refined container macros. | | **Refined container macros **nested inside other Refined container macros | Existing nesting is preserved automatically using the Legacy Content Macro.
The content **remains visible on published pages**, but the **nesting cannot be restructured** in the new editor. | > ⚠️ **Good to know:** Macro content is never permanently lost. The limitations affect visibility and editing, not data preservation. ### What should you do? If your pages contain **native Atlassian or third-party macros** inside Refined container macros, review those pages after migration and choose one of the following: - **Restructure** the page by moving the nested macro outside the Refined container macros, so they become visible again. - **Leave the page as-is** if the hidden content is no longer needed, or you plan to move it outside of Refined container macros after the migration. ### Refined container macros If your pages use **Step Container, Tab Container, or Expand Container** macros: - They are automatically wrapped in the **Legacy Content Macro** during migration. - No preparation is required before migrating. - You can continue editing the content. - Re-nesting or restructuring these macros after migration in the new editor **is not possible.** > ❌ **Note: **If you un-nest these macros in Data Center before migrating, the Legacy Content Macro will not apply in Cloud, and you **will not be able to re-nest them afterwards**. > ❌ > ❌ Leaving the nesting in place before migration is the safe option.
> ⚠️ Re-nesting or restructuring **Refined** container macros **after migration** in the new editor **is not possible.** Please do not Skip step 2.
Step 3: Supported migration paths - **DC → Forge Native** (Macro Toolkit and/or UI Toolkit) - What changes | What changes | DC → Cloud (Forge Native) | | --- | --- | | **Themes & visual customization** | | Space themes (background colors and images on pages) | — | | **Macro nesting** | | Native Atlassian macros nested inside Refined macros *e.g. Table of Contents inside a Tab or Panel* | Not supported. Content is not lost but will not be visible on published pages until moved outside the macro. | | Third-party or Connect-on-Forge macros nested inside Refined macros | Not supported. Content is not lost but will not be visible on published pages until moved outside the macro. | | Refined macros nested inside Refined macros *e.g. Tab inside a Panel* | Existing nesting is preserved via the [Legacy Content Macro](https://support.atlassian.com/confluence-cloud/docs/the-legacy-content-macro/) - content remains visible and readable.
Note: Re-editing or restructuring the nesting is not possible in the new editor. | | Editing existing bodied macro content *Known Atlassian platform bug* | Not currently supported by Atlassian. However we have introduced a workaround that will enable the editing/saving of the macro. | | **Images** | | External image URLs in macros and Page Builder *Previously: paste a URL to use a web-hosted image* | Not supported. Previously added images can be downloaded from the macro editing interface and re-uploaded locally. | | **Macros not available on Cloud (DC migrations only)** | | DC-only macros with no Cloud equivalent *e.g. Image macro, Profile macro, Divider macro, and others* | Not available on Cloud. See [full list of differences between DC and Cloud](https://help.refined.com/space/MIGRATETOOLKITCLOUD/5333844090/Differences+between+Server%2FData+Center+and+Cloud+in+Macro+Toolkit). | | **Page Builder (UI Toolkit)** | | Page Builder data retained after uninstall. *Only relevant during the transition window between uninstalling old app and installing new one.* | — | | Historical layout versions in Page Builder. *Previously: browse and restore prior layout versions within the app* | Not supported. Use [Confluence page versioning](https://support.atlassian.com/confluence-cloud/docs/view-page-history-and-manage-page-versions/) to access previous versions instead. |
> ℹ️ If it feels like a lot, feel free to [open a support ticket in our portal](https://help.refined.com/portal/13) - our team is here to guide you at any point. 🔗** Useful links** - [FAQ Toolkit](https://help.refined.com/space/TOOLKITCLOUD/5683937411/FAQ+Toolkit+new+app(s)) - [Macro comparison between Refined apps](https://help.refined.com/space/TOOLKITCLOUD/6455885840/Macro+comparison+between+Refined+apps)