Preparation guide

Before starting your actual migration, prepare using the following resources:

Step 1. Learn the differences between Server/Data Center and Cloud

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. Read this page to know what to expect when migrating

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

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

Team Calendars are not supported due to Atlassian API limitations. Click here to view the issue and vote on it.

If a third-party macro isn’t supported on Cloud, watch this video for a workaround:

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.

Step 6. 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 apps Refined Macro Toolkit for Confluence Cloud, and Refined UI Toolkit for Confluence Cloud.

This means that you if you use Refined Sites macros on Server/DC, you need to install Refined Macro Toolkit and / or Refined UI 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 6a. Check if you’re using any Refined Sites 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 app Refined for Confluence?

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

   2. Yes > Follow steps 6b-6d.

Step 6b. 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:

Step 6c. 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. 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 UI Toolkit on Cloud.

This table shows which Refined for Confluence Server/DC macros you can keep using if you get Refined Macro Toolkit on Cloud.

This table shows Refined for Confluence Server/DC macros that aren’t supported in Cloud – neither by Refined Sites nor by Refined Toolkits. Where applicable, we suggest workarounds for your setup.

Step 6d. Un-nest macros to prepare for the new Confluence editor

On Server/DC it is possible to nest macros which contain content within one another. These are called bodied macros.

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.

It is possible that some of your Refined for Confluence macros on server / DC are nested within other bodied macros - for these, we recommend un-nesting prior to migration.

Read more on nested macros here.