We’re here to help you make your migration as smooth as possible.
...
Server/Data Center vs. Cloud: differences and similarities
Refined Sites for Confluence Cloud combines key features from Refined for Server/Data Center (DC) with the convenience of the cloud. However, there are also some notable differences between the two products.
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 the sites you create.
On Cloud, Refined Sites is a site-building tool parallel to Confluence. The 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
...
...
...
Categories are called Refined Pages (category with landing page) and menu folders (category without landing page).
...
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 feature comparison further down on this page.
...
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 as in native Confluence. For example when they include some of the few formatting or macros that Refined Sites doesn’t (fully) support.
Note that this feature is in beta and limitations apply.
...
Space Layouts
...
...
...
You have the option to connect a fully customizable landing page to a space.
Space settings let you tailor the look and functionalities of pages within the space.
...
Third party apps
...
...
...
Some apps or macros provided by third party Marketplace vendors might work on native Confluence, but not on Refined sites. Read more in step 3 of the preparation guide below.
...
Refined macros
...
...
-
...
Refined Sites 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 step 4 of 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 Service Management content on sites
...
-
...
...
Combine the power of Confluence and Jira, by installing Refined Sites for Jira Service Management Cloud.
...
Promoted search results
...
-
...
...
Offer users a better search experience than in Confluence: suggest pages based on their search query.
Preparation guide
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. 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?
It’s easy to combine both JSM portals and Confluence spaces into one Refined site, if you get both Refined Sites for Confluence Cloud and Refined Sites for Jira Service Management Cloud. Could this improve your workflow and your site’s user experience? It opens up many new ways of using Refined Sites, including:
Building an intranet that features Confluence pages and blogs, as well as JSM portals. For example, this makes it easy for users to explore the company’s employee handbook and directly contact HR if they have any questions.
Creating an external-facing help site that features not just Confluence spaces, but also help desks. This way, users can create support requests if they can’t find what they are looking for.
For insights into the possibilities and best practices, have a look at these in-depth get-started guides:
Step 2. Prepare your base Confluence spaces (and JSM projects)
Once you have an idea of your sites' general structure, prepare your Confluence spaces – and your JSM projects too, if you plan to integrate those into your sites. Generally, we recommend to ask yourself the following questions:
Should I restructure my spaces/projects? In other words: which content can be merged and what can be split into separate spaces/projects?
Which spaces/projects should I introduce?
Which spaces/projects can I refresh?
Which spaces/projects can I slim down?
Which macros am I using on my Confluence pages and how will they work on Cloud? Steps 3 and 4 of this guide will help you prepare your macros for migration.
On Cloud, all spaces need to have a home page. Otherwise, your Refined sites can’t show the page tree menu that is located on the left hand side of all Confluence pages. If some of your spaces don’t have home pages yet, we recommend you to set up home pages already before migration:
Use Atlassian’s Cloud Migration Assistant. In the App Vendor checks, you’ll get a notification if you have spaces without home pages.
Download the report.
Add a home page to each of the spaces in the list.
Re-run the app vendor check to make sure all spaces are set up properly.
Step 3. Prepare for migrating your Confluence/third party macros
Click here for an overview of formatting and macros that are supported on Refined sites. The overview covers macros from Refined Toolkit, Confluence, and third party Atlassian Marketplace apps.
Because Refined Sites Cloud works as a site builder parallel to native Confluence, the app doesn’t change native Confluence. Therefore, Refined Sites doesn’t impact third party apps that provide functionalities in native Confluence such as apps for document management.
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 reach out to us: migration assistance.
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 Sites 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 4a. 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 4b. 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 4c. 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 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'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.
Step 5. Set up a rollout plan
Because Refined Sites 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.
Migration guide
| Info |
|---|
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 and add blogs to it. |
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
...
Refined Sites for Confluence Cloud
Required
...
Required app.
...
Refined Toolkit for Confluence Cloud
Optional
...
Install if you assessed during preparation that you need it to keep using your macros on Cloud.
...
Refined Sites for Jira Service Management Cloud
Optional
...
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
...
Install version 6.1.21 from Atlassian Marketplace.
Navigate to Refined Administration and click the Upgrade button.
Follow the steps below (for version 6.0.0 - 7.0.x).
...
Version 6.0.0 - 7.0.x
...
Go to the Confluence Administration > Manage apps.
Install the latest version of Refined for Confluence.
Make sure Refined is compatible with your Confluence instance.
Make sure that your Confluence instance is fully backed up.
Go to the Confluence Administration > Refined > Configuration.
Click the Upgrade the theme data to Refined 7.1.x data button.
When you have upgraded Refined Sites for Confluence, advise your users to refresh their browser. Stylesheets and scripts have changed in new versions and need to be reloaded.
...
Version 7.1.x or newer
...
Go to the Confluence Administration > Manage apps.
Install the latest version of Refined for Confluence.
Step 4. Export a site with the migration assistant
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.
...
| Rw tab | ||
|---|---|---|
|
While you follow these steps to migrate the site, don’t make changes to the site and its settings.
| Info |
|---|
We’ll notify you in the last step of the migration process if someone made changes to the site or settings since you started the migration. If this happens, we recommend closing the dialog and starting the migration process again, to ensure all choices you make are based on the latest version of the site and its settings. |
...
| Rw tab | ||
|---|---|---|
|
If elements on your site such as modules contain links to pages, you can update them in this step. Create rules to update multiple links at a time, or enter new links manually.
...
| Rw tab | ||
|---|---|---|
|
Configure how you’d like these features to be handled on Cloud. The migration assistant will only show the features that apply to your site.
...
Layout modules
Some modules aren’t available on Cloud. They can be replaced with similar modules:
The My Work module will be replaced with an Activity Stream module. It’ll have CQL set up to show Confluence pages the user has worked on.
The Search module will be replaced with a Search Highlight module.
User Details, Users in Category, and Users modules will be removed. You can create similar user overviews manually with Image and Text modules.
The Confluence Content module will be removed.
...
Option
...
Description
...
Replace unavailable modules when possible
...
Unsupported modules that don’t have a viable alternative on Cloud will still be removed.
...
Exclude all unavailable modules
...
The unavailable modules will be removed and left empty in the Cloud layout on Cloud.
| Info |
|---|
To get more granular control over the modules, you can always migrate layouts individually. Read how to do this under “Migrate single layouts” further down on this page. |
View permissions on categories and links
If your site includes categories or links with manual view permissions, you’ll see a list. You can download the list as .CSV file, to keep it for future reference.
...
Option
...
Description
...
Keep manual view permissions
...
The same users or user groups needs to exist on Cloud. If they don’t, those specific permissions won’t be included in the export: standard Atlassian permissions apply to the category or link.
...
Remove manual view permissions
...
Standard Atlassian permissions will apply.
Uncategorized spaces
If your site contains uncategorized spaces, you’ll see a list. You can download the list as .CSV file, to keep it for future reference.
...
Option
...
Description
...
Include uncategorized spaces in menu folder
...
Menu folders function similarly to a category. The menu folder will be hidden from the site's navigation menu, but users can still access the spaces through search functionalities and with a direct URL.
...
Exclude uncategorized spaces
...
The uncategorized spaces will still be available in your Confluence instance, but they aren’t included in this Refined site.
Archived spaces
If your site contains uncategorized spaces, you’ll see a list. You can download the list as .CSV file, to keep it for future reference.
...
Option
...
Description
...
Exclude archived spaces
...
The archived spaces will still be available in your Confluence instance, but not included in this Refined site.
...
Include archived spaces
...
The archived spaces are still included in the navigation menu, but users can’t find them through search functionalities.
| Rw tab | ||
|---|---|---|
|
These settings aren’t available on Cloud or need to be set up manually. Read this information carefully to assess your next steps after migration.
...
Feature
...
Differences between Server/DC and Cloud
...
Single space sites
...
On Cloud, single space sites don’t exist. All sites are full sites: you’ll see your space in the site navigation menu instead of in the Site Switcher.
...
Site administrators
...
For security reasons, site administrators aren’t included in the export. Reconfigure the site administrator rights on Cloud. The migration assistant will show a list of the current site administrators, which you can download as a .CSV file.
...
Site access permissions
...
By default, migrated sites aren’t available to anonymous users. You can change the site access permission manually on Cloud.
...
Layout module filters
...
The Activity Stream module’s Filter for contributor setting and News module’s Filter for author setting aren’t migrated. These filters need to be set up again on Cloud.
...
Layout section permissions
...
Themes
...
Themes can’t be migrated to Cloud, and need to be re-created manually. Cloud doesn’t support advanced theming or themes made with third party apps.
...
Site switcher
...
Site Switcher settings aren’t migrated. You’ll need to enable and configure it on Cloud after migration. You’ll have same site list for all sites you create.
...
Logos
...
Structure logos, link logos, space logos, and category logos aren’t supported on Cloud sites. The site logo in the navigation menu won’t be migrated and needs to be set up manually on Cloud.
...
Blog spaces
...
Blog spaces become regular spaces on Cloud. Point users to blog posts with News modules or direct links instead.
...
Users connected to spaces
...
On Server/DC, it’s possible to connect users to spaces. Certain macros can automatically display these users and their roles on pages, user dashboards, and space layouts.
On Cloud, it’s not possible to connect users. You can still manually highlight users on landing pages instead, for example by creating an Image module per user.
...
Category administrators
...
Category administrators don’t exist on Cloud. If your site has category administrators, you’ll see a list which you can download as a .CSV file.
...
Custom category modules
...
Blog modules, HTML modules, and Confluence Questions modules don’t exist on Cloud and are therefore not migrated.
...
Users connected to categories
...
On Server and Data Center, it’s possible to connect users to spaces. The Users in Category module can automatically display these users and their roles on on a site or category home.
On Cloud, it’s not possible to connect users. You can still manually highlight users on landing pages instead, for example by creating an Image module per user.
...
Categories with custom URL
...
A category with a custom URL is essentially a link with child items. On Cloud, links can’t have child items. How the category with custom URL is migrated to Cloud depends on whether it has child items:
If it has child items, it will become a menu folder. The link-on-click is removed, but the child items remain grouped together.
If it doesn’t have child items, it will be migrated as a link.
...
Footer
...
The footer won’t be migrated, your site will get the default Cloud footer instead.
| Rw tab | ||
|---|---|---|
|
Click the Download button to export the site. See step 5 below for instructions on importing and setting up the site on Cloud.
...
| Excerpt | ||
|---|---|---|
| ||
Step 5. Import and set up the site on Cloud
|
Possibility to migrate only single layouts
To get more granular control over the modules, you can always migrate layouts individually, outside of the migration assistant. You can then import these layouts on Cloud, where they are called landing pages.
To migrate a single layout:
Make sure you have the following installed:
Refined Sites for Confluence Server/DC version 7.4 or newer (if you need to upgrade, see the version 7.4 upgrade instructions).
Confluence Server/DC version 7.15 or newer.
On your Refined site, go to a site or category home and click the … Three dots in the top right corner > Edit site/category home.
Click the Import/Export button > Download latest published version for use on Cloud.
If the layout contains modules that are unavailable on Cloud, a popup will appear. Select if you want to exclude or replace these modules in the Cloud layout. Scroll down for a module comparison.
When you're ready, click Download.
Go to the landing page on your Refined Cloud site where you want to use the layout.
Click the … (three dots) > Edit page to open the Page Builder.
Click the Three lines in the top-left > Export/Import page layout.
Upload the layout.
Make adjustments if necessary and hit Publish.
Module comparison
Because of technical differences between Cloud and Server/DC, there are some differences between the modules in the Layout Editor (on Server/DC) and the Page Builder (on Cloud). If the layout you export contains modules that are unavailable on Cloud, you can configure how they should be handled in the export.
...
Layout Editor modules
Server/DC
...
Page Builder modules
Cloud
...
...
...
...
There is no alternative for this module on Cloud, so it won’t be included in the downloaded layout. If you plan to add another module in its place on Cloud, a placeholder can help you see where the module used to be.
...
...
...
...
Replace the module with an Activity Stream module in the layout that you download, or exclude it altogether.
The Activity Stream module is set up with CQL to show the activity of the current user: type=page AND contributor = currentUser()
...
...
...
...
...
...
...
...
This module is automatically replaced with an Image module with the Navigation Content style.
...
...
This module is automatically replaced with an Image module with the Navigation Highlight style.
...
...
...
...
...
...
...
...
Replace the module with a Site Navigation module in the layout that you download, or exclude it altogether. The Site Navigation module automatically shows the landing page’s child spaces.
To show only specific spaces, exclude the module from the export and add them manually in a Links module as individual items.
...
...
There is no alternative for these modules on Cloud, so they won’t be included in the downloaded layout. If you plan to add another module instead on Cloud, a placeholder can help you see where the module used to be.
Create similar user overviews manually with Image and Text modules.
Once you’ve migrated the layouts, you can also start using these modules:
Issue Types (if you also have Refined for Jira Service Management Cloud)
Jira Issues (if you also have Refined for Jira Service Management Cloud)
My Requests (if you also have Refined for Jira Service Management Cloud)
Request Types (if you also have Refined for Jira Service Management Cloud)
Section permissions limitation
| Excerpt | ||
|---|---|---|
| ||
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 6. Re-create and apply themes
Themes aren’t migrated and need to be re-created manually using the Theme Editor.
What’s next?
Why not transform your Confluence instance into even more sites users love — you can create an unlimited amount of sites with your Refined Sites for Cloud subscription:
Get started with Refined Sites for Confluence 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:
Migration assistance. Our support team is always there to help you with questions before, during or after migration.
Migration assessment. In a one-on-one meeting, we give personalized advice on how to move and improve your sites.Differences between Server/Data Center and Cloud