On your SERVER/DATA CENTER: enable the MultiExcerpt modules for MultiExcerpt macros with Cloud names
- Navigate to 'Manage apps'
- Confluence Admin > Manage apps
- Expand the section for your Multiexcerpt plugin
- Expand the 'modules' section within the Multiexcerpt plugin section
- Enable these two modules to turn on the macro names that will be used in Cloud:
Note: there is no Cloud equivalent of the Server/Data Center macro for MultiExcerpt Enhanced Permissions
- Leave these two modules enabled, they use the Server/Data Center macro names and will allow you to continue to use both names on your Server/Data Center instance during the migration effort:
On your SERVER/DATA CENTER: search/replace the Server/Data Center macro names to replace with Cloud macro names in the page Storage Format markup. Also search/replace the PageWithExcerpt and MultiExcerptName macro parameters to use the Cloud names.
|Search For||Replace With|
- The "PageWithExcerpt" and "MultiExcerptName" are parameters for the "multiexcerpt-include" macro. You will see those parameters when you find a "multiexcerpt-macro".
- Atlassian has a free app for editing Storage Format markup: Confluence Source Editor
- The advanced search tool in Confluence allows you to invoke CQL queries to find pages with macros on them:
- The Search and Replace app may make this easier than doing it manually. We are not affiliated with the Search and Replace app nor the vendor.
Migrate your content from Server/Data Center to Cloud
- Export Confluence pages as XML from Confluence Server/Data Center and import into Confluence Cloud
- Atlassian Confluence Support References:
- Cloud Migration Assistant for Confluence
- Migrate from Confluence Server to Cloud
- Artemis reference for export/import:
- Export Space or Pages for Troubleshooting
- As of early 2021 pages that are exported from Server and imported to Cloud are created as "legacy" pages in Cloud, not "new/fabric" pages
- Confluence Cloud does not have feature parity with Confluence Server. Some of the oddities/limitations of Confluence Cloud that affect MultiExcerpt are listed here:
- Cloud does not allow 3rd party ("Connect") macros to be nested within each other. This Confluence Cloud limitation is for all types of pages (legacy and new). Therefore, you cannot nest a MultiExcerpt within a MultiExcerpt in Cloud even though you could in Server:
- Summary of Problems for Nesting Macros in Confluence Cloud
- Confluence Cloud does not give 3rd party macros the ability to get the CSS stylesheet for the parent page so there are numerous styling oddities with 3rd party macros in Cloud
- We are pursuing this with Atlassian, trying to get them to provide 3rd party apps with an API for getting the CSS stylesheet
- Many of the problems in Cloud are related to "new/fabric" pages and are not a problem for legacy (old) pages. Be aware of this if you decide to convert your imported pages from legacy to new.
- You should be aware that Atlassian will have a "reminder" to convert the page from a legacy (old) page to a new one when you open the page to edit it for the first time.
If Server Was Migrated to Cloud Without Editing Multiexcerpt Macros
If your Server site was migrated to Cloud without following the above steps to edit your Storage Format markup then the macros will not be recognized in Cloud:
If that has happened and you catch it immediately, before your Cloud site is open for production usage, then you may want to stop and redo your Server → Cloud migration and follow the above steps for editing your macros BEFORE importing to Cloud.
If redoing your migration is not an option then you must edit the Storage Format on your Cloud instance to change the macros so they are recognized:
|Search For||Replace With|
The "PageWithExcerpt" and "MultiExcerptName" are parameters for the "multiexcerpt-include" macro. You will see those parameters when you find a "multiexcerpt-macro".
Our Storage Editor plugin is an example of a tool that can be used to edit Storage Format in Cloud.
You will need to find all of the pages that contain "multiexcerpt" and "multiexcerpt-include" macros so you can edit the Storage Format on those pages.
The Confluence Cloud search API is not usable for finding the pages with "multiexcerpt" and "multiexcerpt-include" macros. CQL can only find macros that are successfully installed on your instance. It can find "multiexcerpt-macro" macros on Cloud because that is a valid macro that you can and will install on your Cloud instance. However, it cannot find "multiexcerpt" macros that you have imported in your markup from your Server instance. In addition to the limitations of CQL searches, the search API in Cloud is significantly buggy and is not reliable for finding macros in Cloud sites.
If your site is large enough that you cannot find the broken MultiExcerpt macros manually by navigating your site then you may want to consider doing the search on your SERVER instance and then use those results to know which pages need editing on your Cloud instance. The advanced search (using CQL) to find macros is reliable on Server: