| Infonote |
|---|
The migration tool is only available to Confluence administrators. It’s not possible to migrate blog sites, because this type of site doesn’t exist on Cloud. Create a new site on Cloud instead, add the Confluence Space(s) containing your blog posts to the site, and use the News module to show blog posts |
Step 1. Prepare for migrating your Refined macros
The Refined Sites for Confluence Cloud app doesn’t come bundled with Refined macros like the Server/DC app does. This is due to the technical differences between Confluence Server/DC and Confluence Cloud. Macros are instead available in our app Refined Toolkit for Confluence Cloud.
This means that you if you use Refined Sites macros on Server/DC, you need to install Refined Toolkit on your Cloud instance. If you don’t, the migrated macros will show as Unknown macro on your Cloud pages. Depending on which macros you use, you may need to take additional steps or apply workarounds to secure that your macros will work as intended. How this preparation looks depends on your specific setup. The following guide helps you assess how to proceed in your situation.
Step 1a. Check if you’re using any Refined Sites macros
Go to General Configuration.
In the left-hand menu, find the Administration heading and click Macro usage.
Do you see macros listed for the apps Refined Sites for Confluence and Refined Toolkit for Confluence?
No > You aren’t using Refined Sites macros, so you can move on to step 5 of this preparation guide.
Yes > Follow steps 4b-4d.
Step 1b. Note down which Refined Sites macros you use
The macros are named according to their macro keys, which in most cases are self-explanatory. There are however some exceptions, in which macro keys can have two different names:
...
Macro
...
Macro key
...
...
rw-activity-stream
recently-updated-dashboard-category
...
...
rw-divbox
divbox.
...
...
rw-space-news
space-news
...
...
rw-spaces-in-categories
spaces-in-category
Step 1c. See which actions to take for each Refined Sites macro
Consult the tables below to see what will happen to your macros after migration and decide which actions to take. In most cases you can prevent issues by installing our app Refined Toolkit for Confluence Cloud. Note that macros on Cloud might look and work a bit differently - click the links to read the documentation.
This table shows which Refined for Confluence Server/DC macros you can keep using if you get Refined Toolkit on Cloud.
...
Refined Sites for Confluence Server/DC
...
Refined Toolkit for
Confluence Cloud
...
...
Supported settings: Title, Max items (limit), Types, Authors, Labels (label), Spaces (space key)
Unsupported settings: Content Types, Authors, Category key, CQL
...
...
This macro is available on Cloud, but it is not migrated from Server/DC to Cloud. This means that you have to recreate it on Cloud.
...
...
This macro is available on Cloud, but it is not migrated from Server/DC to Cloud. This means that you have to re-add it on Cloud.
...
...
Supported settings: Title, Theme (DisplayMode), Max items (limit), ProfilePic, ShowSpaceName, Labels (label), Spaces, CQL
Unsupported settings: Type, Profile pictures, Categories, Show space name, View in popup, Expand first item
This table shows which Refined Toolkit for Confluence Server/DC macros you can keep using if you get Refined Toolkit on Cloud.
...
Refined Toolkit for Confluence Server/DC
...
Refined Toolkit for
Confluence Cloud
...
...
Supported settings: Title, URL, Tooltip, Size, and Color.
Unsupported settings: Icon, Display, Open in a new window
It’s not possible to set custom color profiles on Cloud.
URLs are static. If they link to local pages and blog posts in Server/DC, you need to manually change the link to the new URL in Cloud.
...
...
Supported setting: Page
Unsupported settings: Display, Columns, Sort children by, Reverse sort
...
...
Turns into a Child Pages macro with the cards display mode.
...
...
Supports the same settings as on Server/DC
...
...
Images are migrated if you have Refined Toolkit Cloud, but they are not editable. To add images in Cloud, simply insert them in the Confluence Editor.
...
...
Unsupported setting: Size
...
...
Supports the same settings as on Server/DC
...
...
Supported setting: Type
Unsupported settings: Text size, Show icon
It’s not possible to set custom color profiles on Cloud.
This table shows Refined for Confluence Server/DC macros that aren’t supported in Cloud – neither by Refined Sites nor by Refined Toolkit. Where applicable, we suggest workarounds for your setup.
...
Refined for Confluence Server/DC
...
Workaround for Cloud
...
...
Although the Divbox macro doesn’t exist on Cloud, images and text within the Divbox macro are migrated if you have Refined Toolkit. Macros in the Divbox are not rendered due to technical limitations – read more about this in step 4d below.
...
...
Users can save Confluence pages on your Refined site for future reference, by clicking the Star icon in the top-right corner of a page. By clicking My favorite pages in the avatar menu, users see an overview of all pages they saved.
...
...
After you migrated to cloud, create a Layout Editor macro and place an Activity Stream macro in it. Set up the Activity Stream macro with CQL: type=page AND contributor = currentUser()
Note that this solution will only work in native Confluence, because Refined sites can’t show Layout Editor macros.
...
...
Use Confluence’s Livesearch macro.
...
...
Use Refined Toolkit’s News macro instead.
...
...
Due to differences between Server/DC and Cloud, these macros become irrelevant after migration. That’s why they aren’t supported and don’t have a workaround.
| Info |
|---|
To make sure that your macros work as expected, we recommend to install Refined Toolkit for Confluence Cloud before migrating. |
Step 1d. Un-nest macros to prepare for the new Confluence editor
When you migrate to Cloud, you edit your pages in Confluence Cloud’s legacy editor. This editor is similar to the one you're used to from Server/DC. While Atlassian recommends you to convert your pages to the new editor, this may pose problems with some of your migrated macros.
On Server/DC it is possible to nest macros which contain content within one another. These are called bodied macros. This is essential to the functioning of some macros: for example, you place content in a Step macro within a Step Container macro.
Due to a Confluence Cloud limitation, it is not possible to nest bodied macros in the new editor on Cloud. So when you convert a page with a nested bodied macro from the legacy editor to the new editor, the macro becomes uneditable.
To prevent this, we recommend un-nesting bodied macro content before migrating:
Go to General Configuration.
In the left-hand menu, find the Administration heading and click Macro usage.
In the overview, look for the apps Refined Sites for Confluence and Refined Toolkit for Confluence.
Click these macros to see on which pages they are located:
Expand Container (contains Expand macros, which contain bodied content)
Tab Container (contains Tab macros, which contain bodied content)
Step Container (contains Step macros, which contain bodied content)
Take out the content out of each macro and paste it directly on the page. You can re-create the setup after migration, using the Cloud equivalents of these macros.
If you have many nested macros, it’s understandable that you might not have the time to un-nest them all before your migration. In that case, a temporary solution is to migrate as-is, stay in the legacy editor at first, and gradually convert pages to the new editor as needed:
On the published page, copy the content from the macros.
Go into editing mode and convert the page to the new editor.
In the new editor, paste the content back in where the macro used to be.
We're aware that neither option is ideal, and we're in contact with Atlassian to solve this. Note that we do recommend you to move to the new editor over time, despite the hassle of manual work. Although migrated macros usually show on the legacy editor pages at first (if you have Refined Toolkit installed), they may still break eventually if Atlassian makes changes to the legacy editor.
If this issues affects you, please vote or comment on this ticket.
...
Before starting your migration, it’s essential to understand key differences between Cloud and Server/Data Center. Please make sure you’ve read these pages and prepared your instance: |
| Table of Contents | ||
|---|---|---|
|
Step 1. Migrate your Confluence instance
Use Atlassian’s Confluence Cloud Migration Assistant to migrate your Confluence Server/DC instance to Cloud.
Step
...
2. Install Refined apps on Cloud
Install these apps on your Atlassian Cloud instance:
App | Description |
|---|---|
Required app. | |
Install if you assessed during preparation that you need it to keep using your macros on Cloud. | |
Install if you want to integrate service desks into your Cloud sites. |
Step
...
3. Upgrade Refined for Confluence Server/DC
Upgrade Refined for Confluence Server/DC to the latest available version. How to upgrade depends on which version you currently use. To check your current version, go to the Confluence Administration > Manage apps.
Your current version | How to upgrade |
|---|---|
Version 1.0.0 - 5.1.19 |
|
Version 6.0.0 - 7.0.x |
|
Version 7.1.x or newer |
|
Step
...
4. Export a site with the migration assistant
| Info |
|---|
The migration assistant is only available to Confluence administrators. |
Go to the Refined Administration.
Go to the Site Builder tab.
Toggle on Cloud migration mode and click a site’s Cloud button.
Follow the steps in the dialog that opens.
...
The permission settings Anonymous, Anyone, and Logged in users only (without user groups specified) are migrated. The setting Logged in users only (with user groups specified) isn’t migrated and needs to be set up manually on Cloud.
Step
...
5. Re-create and apply themes
Themes aren’t migrated and need to be re-created manually using the Theme Editor.
...