Refined for Confluence

We’re here to help you make your migration as smooth as possible.

Server/Data Center vs. Cloud: differences and similarities

Refined for Confluence Cloud combines key features from 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 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 

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 for Confluence Cloud and Refined 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, 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:

• Build a help & support site

• Build an intranet

• Build a documentation site/knowledge base

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:

1. Use Atlassian’s Cloud Migration Assistant. In the App Vendor checks, you’ll get a notification if you have spaces without home pages.

2. Download the report.

3. Add a home page to each of the spaces in the list.

4. 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 site. The overview covers macros from Refined Toolkit, Confluence, and third party Atlassian Marketplace apps.

Because Refined Cloud works as a site builder parallel to native Confluence, native Confluence is not changed by Refined. Therefore, Refined 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 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’re using any Refined macros

1. Go to General Configuration.

2. In the left-hand menu, find the Administration heading and click Macro usage.

3. Do you see macros listed for the apps Refined for Confluence and Refined Toolkit for Confluence?

   1. No > You aren’t using Refined macros, so you can move on to step 5 of this preparation guide.

   2. 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:

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.

This table shows which Refined Toolkit for Confluence Server/DC macros you can keep using if you get Refined Toolkit 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.

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 Refined 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:

1. Go to General Configuration.

2. In the left-hand menu, find the Administration heading and click Macro usage.

3. In the overview, look for the apps Refined for Confluence and Refined Toolkit for Confluence.

4. 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)

5. 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:

1. On the published page, copy the content from the macros.

2. Go into editing mode and convert the page to the new editor.

3. 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 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

Step 1. Migrate Confluence to Cloud

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:

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.

Step 4. Export a site with the migration assistant

1. Go to the Refined Administration.

2. Go to the Site Builder tab.

3. Toggle on Cloud migration mode and click a site’s Cloud button.

4. Follow the steps in the dialog that opens.

Step 5. Import and set up the site on Cloud

1. Go to your Atlassian instance.

2. Click Apps > Refined in the navigation menu.

3. Click the Open Refined button.

4. Click the Import Server or Data Center site button.
   

   

5. Decide what we should call your site in the Refined Administration. This name also shows up in the browser tab for your site’s visitors. 

6. Choose your site’s URL by picking a subdomain: (subdomain).refined.site. While you are welcome to keep this URL, you can also set up a custom domain later.

7. Let us know what kind of site you’re importing.

8. Upload the file you exported from your Server or Data Center instance. Keep the tab open while the file is uploading.
   

   

   
   

9. Click the Continue button. It may take up to 2 hours to create your site. You can close the tab and check back later.
   

   

   
   

10. Review your site once it’s ready. You may need to make changes in your setup, depending on your configurations and assessments you made on Server/DC.

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:

1. Make sure you have the following installed:

   • Refined 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.

2. 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.

3. Click the Import/Export button > Download latest published version for use on Cloud.
   

   

4. 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.

5. When you're ready, click Download.
   

   

6. Go to the landing page on your Refined Cloud site where you want to use the layout.

7. Click the … (three dots) > Edit page to open the Page Builder.

8. Click the Three lines in the top-left > Export/Import page layout.

9. Upload the layout.

10. 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.

Once you’ve migrated the layouts, you can also start using these modules:

• Button

• Divider

• Page Tree

• Site Navigation

• Spacer

• Text

• Links

• 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

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 for Cloud subscription:

• Get started with Refined for Confluence Cloud

• Build an intranet

• Build a help & support site

• Build a documentation site/knowledge base

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.