We’re here to help you make your migration as smooth as possible.
| Table of Contents | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
...
...
...
Creating and editing Confluence Content
The Refined apps for Server/DC and Cloud operate differently from each other, which impacts the way you create and edit content.
On Server/DC, Refined is added on top of Confluence: when enabled globally, Refined acts as a skin applied to native Confluence. This means that users view, create and edit Confluence spaces, pages and blogs all through Refined sites.
On Cloud, Refined is a site-building tool parallel to Confluence. The Refined sites that you build show Confluence content, but live outside native Confluence. This means that you create and manage the sites with Refined, and you create and edit spaces/pages/blogs in Confluence. All the updates you make in Confluence instantly show on your Refined sites too. Note that Confluence space and content permissions are always respected on Refined sites as well.
Feature comparison
...
Feature
...
Server/
DC
...
Cloud
...
Comment about the Cloud feature
...
Sites
...
...
...
You can add any space to as many Refined sites as you like.
...
Navigation menu
...
...
...
Categories
...
...
...
You group spaces with Refined Pages and menu folders instead (and JSM projects too, if you have Refined for Jira Cloud).
...
Site and
Category homes
...
...
...
You edit these pages with the intuitive what-you-see-is-what-you-get Page Builder. Available modules differ slightly from Server/DC: see a comparison.
...
Blog site
...
...
...
You can create a blog site by adding a space with only blog posts to a Refined site and using the News module to show the blogs on landing pages.
...
Announcement Banners
...
...
...
Themes
...
...
...
Advanced Themes
(self-coded)
...
...
...
You can still add custom CSS to alter your theme (but note that we don’t support issues caused by custom CSS).
...
Confluence formatting and macros
...
...
...
Sometimes you may want to embed Confluence pages so they look in native Confluence. For example when they include some of the few formatting or macros that Refined doesn’t (fully) support.
Note that this feature is in beta and limitations apply.
...
Space Layouts
...
...
...
Each space gets a fully customizable landing page and can be tailored further with space settings.
...
Third party apps
...
...
...
Some apps or macros provided by third party Marketplace vendors might work on native Confluence, but not on Refined sites.
...
Refined macros
...
...
-
...
Refined for Confluence Cloud doesn’t include any Refined macros. Possible solutions for this depend on your specific setup and require the app Refined Toolkit for Confluence Cloud. See the detailed migration preparation guide below.
...
User Dashboards
...
...
-
...
User Categories
...
...
-
...
Custom domains on sites
...
-
...
...
Give each site a custom URL for quick access and easy recall.
...
Jira Content on sites
...
-
...
...
Combine the power of Confluence and Jira, by installing Refined for Jira Cloud.
...
Promoted search results
...
-
...
...
Offer users a better search experience than in Confluence: suggest pages based on their search query.
...
Step 1. Consider overhauling your setup
Migrating to a new platform can be a great opportunity to rethink your Confluence and Refined setup. We recommend to evaluate what was working well on the Server/DC instance - and what you can improve.
Then, make a game plan from there. You can opt to replicate your Server/DC setup on Cloud with improvements here and there, or see Cloud as a blank canvas to create a totally new setup. Whichever option you choose, ask yourself how you can leverage these key advantages of the Cloud infrastructure:
You can create as many sites as you want: what content can you split out into multiple sites?
You can add a space to as many sites as you want. What content can be relevant to include on multiple sites?
With Refined for Jira Cloud it’s easy to combine Confluence and Jira Service Management (JSM) on the same site. For example, this opens up the possibility to create a support site or intranet featuring:
A knowledge base (Confluence spaces)
One or more help desks (JSM projects)
For insights into the possibilities and best practices, have a look at these in-depth get-started guides:
Step 2. Prepare your base Confluence (and JSM) content
Once you have an idea of your sites' general structure, prepare your Confluence content – and your JSM content too, if you plan to integrate it into your sites. Generally, we recommend to ask yourself the following questions:
Could it improve our workflow and user experience to add service desks to my sites?
Should I restructure my spaces - in other words: which content can be merged and what can be split into separate spaces?
What content should I introduce?
What content can be refreshed?
What content can we slim down?
Which macros am I using on my pages and how will they work on Cloud?
Step 3. Prepare for migrating your Confluence/third party macros
Click here for an overview of formatting and macros that are supported on Refined site. The overview covers macros from Refined, Confluence, and third party Atlassian Marketplace apps.
If a macro you use on Server/DC is not supported on Cloud, remove it from your pages and find a workaround. If you use a critical third party macro that we don’t support on Cloud, please request reach out to us.
Team Calendars are not supported due to Atlassian API limitations. Click here to view the issue and vote on it.
Step 4. Prepare for migrating your Refined macros
The Refined 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. Refined macros are instead available in our app Refined Toolkit for Confluence Cloud.
This means that you if you use Refined 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 4a. Check if you are using any Refined 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 for Confluence and Refined Toolkit for Confluence?
No > You are not using Refined macros, so you can move on to step 5 of this preparation guide.
Yes > Follow steps 4b-4d.
Step 4b. Note down which Refined 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 4c. See which actions to take for each Refined 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 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 UI Children 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 for Confluence 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 Content Layout 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 Content Layout 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 4d. 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 are 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 Refined macros: for example, you place content in a Step macro within a Steps 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 body 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 for Confluence and RefinedToolkit for Confluence.
Click these macros to see on which pages they are located:
UI Expands (contain UI Expand macros, which contain bodied content)
UI Tabs (contain UI Tab macros, which contain bodied content)
UI Steps (contain UI Step macros, which contain bodied content)
Take out the content out of each macro and paste it directly on the page.
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 are aware that neither option is ideal, and we are 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.
Step 5. Set up a rollout plan
Because Refined works parallel to Confluence Cloud, your sites don’t have to be ready directly after migrating. Users can access native Confluence while you build your Refined sites. This gives you ample time to get feedback and fine-tune the sites before introducing them to your user base.
...
...
Due to the major infrastructure differences between Server/DC and Cloud, you need to re-create your sites when you migrate.
Step 1. Install Refined apps on Cloud
Install these apps on your Atlassian Cloud instance:
Refined Toolkit for Confluence Cloud (if you assessed earlier that you need it to keep using your macros)
Refined for Jira Cloud (if you want to integrate service desks into your sites)
Step 2. Migrate Confluence
...
...
Step 3. Create Refined sites and add content
...
...
Step 4. Manage site settings
Manage the site settings for each of your Refined sites. Some good settings to start with:
Set up a custom domain for each site.
Control which kinds of users can access the sites with Site Access Permissions.
Create a cookie dialog.
Use space settings to customize the layout and interaction settings of Confluence pages and blog posts.
Step 5. Create and apply themes
Learn how to create and apply themes. Note that Refined for Confluence Cloud doesn’t support advanced theming or third party themes. If you had an advanced theme or used other apps to theme Confluence on Server/DC, you have to recreate these on Cloud.
Step 6. Create landing pages
Although space homes still exists in Confluence, they aren’t used as home pages on your Refined sites. Instead, you get a fully customizable landing page and can adapt the layouts of the space’s pages to your needs with space settings.
There are some differences between the modules in the Layout Editor (on Server/DC) and the Page Builder (on Cloud). Click the links in this table to see compare the documentation. In some cases, a module is not available on Cloud and we suggest a workaround. We also introduce many new useful modules in the Page Builder on Cloud.
...
Layout Editor modules
Server/DC
...
Page Builder modules
Cloud
...
...
...
...
There is no Cloud equivalent for this Server/DC module, because of technical differences between Cloud and Server/DC.
...
...
...
...
To show Confluence pages that the current user has worked on:
Add an Activity Stream module or Pages module.
Set it up with CQL: type=page AND contributor = currentUser()
...
...
...
...
...
...
...
...
Add an Image module with the Navigation Content style.
...
...
Add an Image module with the Navigation Highlight style.
...
...
...
...
...
...
...
...
The Site Navigation module automatically shows the landing page’s child spaces. To show only specific spaces, add them as individual items to a Links module.
...
...
Create similar user overviews manually with Image and Text modules.
...
-
...
...
-
...
...
-
...
...
-
...
...
-
...
...
-
...
...
...
-
...
Issue Types (if you have Refined for Jira Cloud)
...
-
...
Jira Issues (if you have Refined for Jira Cloud)
...
-
...
My Requests (if you have Refined for Jira Cloud)
...
-
...
Request Types (if you have Refined for Jira Cloud)
Need more help?
Have a look at the FAQ and the demos & other resources page.
And of course don’t hesitate to contact us: