Migration
This page contains details to learn more about the migration process from Data Center (DC) to Cloud versions of the app. Before migrating your HTML for Confluence app content from the server to the cloud, we recommend reading this Atlassian article to plan your migration.
The following sections explain:
Migration process
Differences between the server and cloud versions of the app
It is recommended to go through the pre-migration process to avoid possible errors on pages after migration. Read more about the pre-migration process.
Migration process
Confluence instance migration - Use the Confluence Cloud Migration Assistant app to migrate everything you need from the Confluence server to the Atlassian cloud. Confluence Cloud Migration Assistant explains in detail the step-by-step procedure to migrate the required content.
App installation - Install the app from the Marketplace.
On completion of migration from version 5.8.0:
All global configuration and profile data in the Configuration page are transferred from the server instance to the cloud instance as specified in the Cloud Migration Assistant wizard.
If multiple migrations are performed on the same cloud instance, the latest migration takes precedence.
Any subsequent migrations performed on the same cloud instance only add or merge the data, but do not delete any existing data.
Points to note about profile data migration:
For profiles with distinct names on the server/DC and cloud instances, the profiles from both server/DC and cloud instances are combined and listed under Configuration > Profiles as-is.
For profiles with the same name in both server/DC and cloud instances, the profile configurations available on the server/DC overwrites the profile configuration on the cloud instance. Thus, only one copy of the profile configuration, taken from the server/DC, is available on the cloud, and the original configuration details on the cloud are overwritten.
Consider an example if:
Profiles in DC: A, B, and D
Profiles in the cloud: A (profile with the same name as in server, and has the same or different configuration), and X
After the migration is completed, the Configuration page of the cloud instance now contains the A (with configuration details as in server/DC), B, D, and X profiles.
Administrators, installing the HTML for Confluence cloud app for the first time, can begin the installation and configuration process for both macros as given in the Installation and Configuration guides.
Data migration from server to cloud is independent of app installation or configuration in your cloud instance. We recommend that administrators verify that all data is displayed properly after all processes are completed successfully. Please report any issues immediately after looking through the known problem list.
For existing HTML macro content
Due to restrictions in the Confluence cloud, the HTML macro name was changed to HTML-bobswift, causing HTML content display issues in pages and templates using the HTML macro of the HTML for Confluence app. For this purpose, an update process is now available in Migrate to Confluence Cloud on the HTML for the Confluence Configuration page. This option lets you initiate a process that automatically updates the macro name to prepare your HTML content for migration. Refer to this article for the HTML macro name update process instructions.
Administrators must run the HTML macro name update process before migrating content to the cloud. Once the process is completed, the Confluence Migration Assistant must be run to migrate all content to the Confluence cloud.
For XSLT macro
The migration process for this macro is quite straightforward. Administrators must use the Migration Assistant in the Confluence instance to start the migration.
Use the Confluence Cloud Migration Assistant app to migrate everything you need from the Confluence server to the Atlassian cloud. Confluence Cloud Migration Assistant explains in detail the step-by-step procedure to migrate the required content. As mentioned in the previous section, Atlassian does this job for you in most cases.
Known issues and troubleshooting
There are certain issues that can occur after the migration process is completed. These are listed along with the possible solution for each in the following table:
Possible issue | Possible solution |
|---|---|
Macro does not have access to the meta tags in the head of the page it's embedded in. For example, the macro is unable to reference the var pageMetaTags = document.getElementsByTagName('meta'); console.log("Parsing meta tags...");
for (let i=0; i<pageMetaTags.length; i++) {
k = pageMetaTagsi.getAttribute('name') || pageMetaTagsi.getAttribute('id');
v = pageMetaTagsi.getAttribute('content'); console.log(`Page meta tag: $ {k} = $ {v} `);
} | The Atlassian server has a feature that toggles whether the head of the page is available within the macro via the macro's configuration but the same feature does not appear to be present in the cloud version of the HTML macro. Without this feature, the currently logged-in user's ID and/or full name cannot be retrieved which are stored in meta tags. In the cloud, the macros are rendered in iframes so you cannot access the information of the user the same way. You can invoke the JavaScript APIs (https://developer.atlassian.com/cloud/jira/service-desk/jsapi/user/) or Rest APIs (https://developer.atlassian.com/cloud/confluence/rest/api-group-users/#api-wiki-rest-api-user-get) exposed by Atlassian to get the user info. //Gets the logged in user's accountId
AP.user.getCurrentUser(function(user) {
console.log("The Atlassian Account ID is", user.atlassianAccountId);
}); |
Issue rendering Vimeo videos from the HTML macro | It is recommended to set the referrerpolicy attribute to render the Vimeo video which has the following privacy settings: Example video: https://vimeo.com/manage/679057197/advanced# Who can watch it? - Unlisted Specific domains - |
Issue rendering SVG image | Modify the function call from |
The issue with the code inside the HTML macro uses regular JavaScript and also Confluence’s connect library. Example: | Use |
Open issues
Issue | Comment |
|---|---|
HTML content is not shown as-is, or, does not work as expected after migration to cloud.
| This is a known issue with the Confluence cloud. Due to the cloud architecture, all content is rendered as iframes, thus limiting the macro capabilities after the migration is completed. Refer to this Atlassian article to learn more. Note that the HTML macro is a dynamic content macro, and all dynamic content macros render their content in iframes with Confluence cloud. Hence, the macros have little to no ability to interact with any parent controls. |
Support template variables in the HTML macro | This feature is not supported at this point. |
Export Space as HTML does not work, limitations from the Atlassian cloud | Refer to https://support.atlassian.com/requests/PCS-92505/ for details. |
HTML contents with | This is an open issue. Click https://bobswift.atlassian.net/browse/HTML-697 to know more. |
Unable to nest a bodied macro (like the Expand Macro) into another bodied macro. | This is an open issue. Click https://jira.atlassian.com/browse/CONFCLOUD-68323 to know more. |
Macro does not work properly when nested within a Tab or Tab Group macro. | Refer to https://docs.servicerocket.com/composition/knowledge-base/incompatible-macros-when-nested-within-composition-cloud-s-tab-and-tab-group-macros to learn more. |
Problem reporting
If you experience any problems or behavior changes that are unexpected, refer to Help and open a ticket with us. This helps us identify and prioritize fixes and improvements.
Need support? Create a request with our support team.