Update to 5.6.10

We have released an update so that you no longer need to do the "Prepare Migration" step described below. MultiExcerpt Cloud now recognizes the MultiExcerpt Server macros after following the standard Confluence Cloud Migration Assistant process. You do NOT need to take any special action to migrate your MultiExcerpt macros to Cloud.

This was started in 5.6.7 and then was fully implemented in 5.6.10. In 5.6.7 the tools for migrating MultiExcerpt Server to Cloud were removed and only the 'rollback' migration tool was left in place. In 5.6.10 the removal was completed and the 'rollback' migration tool is now gone too.

If you had previously done the Prepare Migration action to prepare one or more spaces, you can continue migrating your instance to Cloud without finishing your MultiExcerpt migration and without doing a rollback. MultiExcerpt Cloud will accept either unchanged Server markup or it will accept markup that was migrated to Cloud using the pre-5.6.7 migration tools.

Please make sure you review Differences between the Server, Data Center, and Cloud MultiExcerpt App

Note: there is no Cloud equivalent of the Server/Data Center macro for MultiExcerpt Enhanced Permissions so you will need to consider your strategy for Cloud excerpting of restricted resources before you do this migration.

Instructions to use

the MultiExcerpt Migration Assistant (changing the macro names)

The Server/Data Center to Cloud migration of the MultiExcerpt macro can be performed without any loss of service for your macros on your Server or Cloud instances.

The MultiExcerpt macros have different names on Cloud than they do on Server/Data Center. For example, the "multiexcerpt" macro on Server/Data Center is "multiexcerpt-macro" on Cloud. In addition, the macros have a few parameters whose names need to be changed.

You will perform a migration with no loss of service on your Server/Data Center by enabling app/macro modules (on Server/Data Center) that use the MultiExcerpt macro names for MultiExcerpt-Cloud.

Enabling these app modules will allow you to rename your MultiExcerpt macros (on Server/Data Center) by editing them in your Confluence Storage Format XML (SFXML) representation of your pages. During this renaming process, the MultiExcerpt macros will work on your Server/Data Center while using either the Server/Data Center or the Cloud macro names. After the renaming is completed for all pages you can migrate your pages from Server/Data Center to Cloud. The pages are immediately ready for service on your Cloud instance.

You have two options on how you choose to migrate. You can follow the longer manual process or you can use our migration tool. To use the migration tool you must have version 5.6.0 or newer

Consider these points before you prepare your MultiExcerpts and MultiExcerpt Includes

Your content may not be visible during this process
If you have updated your versions of Confluence or MultiExcerpt recently we recommend reindexing your site prior to this process. This is especially important if it was a large change in versions.
Average instances require a minimum of 10 minutes to process. Larger instances will take longer
We recommend you do these processes during off-hours
You should lockout page creation and editing during this process to avoid Macros being created and causing errors
The above is caused by the Server modules being disabled, renamed, and then the Cloud modules being enabled
You can avoid some pain points by processing space by space. This may take a little longer overall but will give you more control
Have you read Differences between the Server, Data Center, and Cloud MultiExcerpt App?
Do you have any templates that have a MultiExcerpt or MultiExcerpt include in them? Read the section on templates.

On your SERVER/DATA CENTER: you will need to verify that the migration tool is enabled. Do this prior to initiating a migration.
1. In the Confluence app manager, for "Multiexcerpt Plugin4", click on the "x of x modules enabled" link so you can verify that migration modules are enabled.
  1. verify that all of the "...Migration..." and "...-migrator" and "...-migration"modules are enabled.
You can access our MultiExcerpt Migrator two ways
1. Go to the MultiExcerpt Admin page and then click on migration settings
2. Go to the General Configuration Tools for Confluence administration then navigate to ATLASSIAN CLOUD → Migration Assistant
  1. Multiexcerpt adds a filter to the Migration Assistant tool so that if you navigate to it before all spaces are migrated you will see a page that summarizes the situation:
  2. You do not have to prepare your MultiExcerpts and MultiExcerpt Includes to continue to the Migration Assistant if you have other steps that you need to complete first. However, you will continue to see this message until you have prepared/migrated all spaces using the Multiexcerpt migrator.
We HIGHLY suggest you enable logging for these Java packages before using the Multiexcerpt migrator (see Configuring Logging):
1. net.artemis.plugins.conf.multiexcerpt4.migration (DEBUG or INFO level)
2. net.artemis.plugins.conf.multiexcerpt4.advanced.xhtml.replace (DEBUG level)
If anything goes wrong and you need us to help you troubleshoot we will need the Confluence server log files (see Downloading Confluence Server Log Files)
After navigating to the MultiExcerpt Migrator, click the "Prepare Migration" button:
Select the space or spaces you wish to prepare and migrate:
1. You can select all spaces but we recommend that you at least do one or two test spaces first. This is so that you understand how the process works and you can see if there are any complications that arise.
One final window will pop up to confirm that you would like to prepare your site or if you wish to cancel. If you would like to proceed click "Prepare Migration".
Your progress bar will now show
1. Keep in mind if you are doing a small space this may happen very quickly and you may have a moment or two where it doesn't look like any progress is occurring.
If you have other tasks you need to complete while this process is going you can navigate away from this page
There are two indications of success that are communicated to you
1. a pop up on any page that you are working on
2. The space will show on the list in the "Migration Settings" tab in the MultiExcerpt Admin tool as being prepared
If you have some error or issues you can roll back the changes by clicking the Rollback button for a space
1. you will see a similar progress bar and update when it has been completed
You have prepared your MultiExcerpt & MultiExcerpt Includes for your migration to Cloud!
1. Continue with this process, preparing and migrating all of the spaces that you are migrating to Cloud.
2. Check status of your MutiExcerpt &MultiExcerpt Include migration by viewing the list of prepared spaces on the "Migration Settings" tab for the MultiExcerpt Admin tool and also by viewing the page that is rendered by the filter for the ATLASSIAN CLOUD → Migration Assistant tool. If you have not prepared/migrated all spaces for Multiexcerpt then the filter for ATLASSIAN CLOUD → Migration Assistant will show you that:

MultiExcerpt Enhanced Permissions Macro

Cloud does not have a MultiExcerpt Enhanced Permissions macro and if you are using them they will not migrate. You will either need to convert them manually to regular MultiExcerpt or there will be an error once you move to cloud

Additional information on MultiExcerpt Enhanced Permissions

MultiExcerpt's in Templates

Currently, the migrator does not edit the macros that are in a template. If you have a template that has either a MultiExcerpt or a MultiExcerpt include in them you will need to manually edit the content. This can be done before or after the migration please see Cloud or the server/Data Center instructions. We have issue CMEP-315 Getting issue details... STATUS where we are working on making the changes so this extra step doesn't need to be done.

Additional Consideration

You can use the Cloud version of the App in Server without any concern
If you migrate space by space then you will have both the Cloud & Server modules enabled at the same time. This means that your users may not use the correct type of macro in a space.
- You can avoid this by preparing All of your space at a single time and then disabling the Server modules
- If you disable the server modules but still have them in place you will see an error
- We recommend a final review of all spaces once you are ready to complete preparation from migration and then disable the server macros

More information on modules

to review the modules
1. Go to Manage Apps
2. Click on MultiExcerpt
3. Click on expand button next to XX of 34 modules enabled
4. This will show you the list that is enabled or disabled
  1. Server modules to disable once preparation is complete
    1. multiexcerpt
    2. multiexcerpt-include
    3. multiexcerpt-enhanced-permissions
  2. Cloud modules to enable once preparation is complete
    1. multiexcerpt-macro
    2. multiexcerpt-include-macro

Troubleshooting

Problem	Solution
After running the migratory the names of the app does not change	Reindex your instance How to rebuild the index
A few of the MultiExcerpts don't change and break after the migration	Check to see if it is an Enhanced MultiExcerpt. Those can't be migrated. You will need to manually change them to MultiExcerpt
pages that contain "Multiexcerpt Include" display an error "No macro found named "xxx" on page "xxx" in space "xxx"."	The Multiexcerpt app requires that an excerpt be visited by viewing the page it is on in order to create the index that includes need in order to find the excerpt. For scenarios where a space is exported/imported or copied, or scenarios, where a page tree is copied the indexes for the excerpts, will not be built because the pages have not been visited yet. Until the pages with the excerpts on them are visited the includes will not be able to find the excerpts. WORKAROUND: Visit all-new pages with excerpts on them after you copy/import a space or page tree. This behavior will be improved for usability when MEPOD-71 is released in a future update. After that is delivered the indexes will be created automatically without requiring visitation of all excerpt pages.

When the edits are made to the macro name you will see the changes reflected in the page history as a revision.

The user will be reflected as whoever has run the assistant

There will also be one of the below comments noted

modified by MultiExcerpt to prepare for Cloud migration
modified by MultiExcerpt to rollback Cloud migration

If you find that you have one page only that has an unintended or undesirable outcome you can restore that page only to an earlier version. Then manually change the maco name as outlined in the manual migration.

Instructions for a manual migration (power users)

Click here to expand...

On your SERVER/DATA CENTER: enable the MultiExcerpt modules for MultiExcerpt macros with Cloud names
1. Navigate to 'Manage apps'
  1. Confluence Admin > Manage apps
2. Expand the section for your Multiexcerpt plugin
3. Expand the 'modules' section within the Multiexcerpt plugin section
4. Enable these two modules to turn on the macro names that will be used in Cloud:
  1. multiexcerpt-macro (xhtml-multiexcerpt-macro)
  2. multiexcerpt-include-macro(xhtml-multiexcerpt-include-macro)
  3. Note: there is no Cloud equivalent of the Server/Data Center macro for MultiExcerpt Enhanced Permissions
5. 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:
  1. multiexcerpt (xhtml-multiexcerpt)
  2. multiexcerpt-include (xhtml-multiexcerpt-include)
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
"multiexcerpt" "multiexcerpt-macro"
"multiexcerpt-include" "multiexcerpt-include-macro"
"PageWithExcerpt" "page"
"MultiExcerptName" "name"
1. The "PageWithExcerpt" and "MultiExcerptName" are parameters for the "multiexcerpt-include" macro. You will see those parameters when you find a "multiexcerpt-macro".
2. Atlassian has a free app for editing Storage Format markup: Confluence Source Editor
3. The advanced search tool in Confluence allows you to invoke CQL queries to find pages with macros on them:
4. 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
1. Export Confluence pages as XML from Confluence Server/Data Center and import into Confluence Cloud
2. Atlassian Confluence Support References:
  1. Cloud Migration Assistant for Confluence
  2. Migrate from Confluence Server to Cloud
3. Artemis reference for export/import:
  1. Export Space or Pages for Troubleshooting
4. 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
Limitations
1. Confluence Cloud does not have feature parity with Confluence Server. Some of the oddities/limitations of Confluence Cloud that affect MultiExcerpt are listed here:
  1. 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:
    1. Summary of Problems for Nesting Macros in Confluence Cloud
  2. 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
    1. We are pursuing this with Atlassian, trying to get them to provide 3rd party apps with an API for getting the CSS stylesheet
      1. https://artemis.atlassian.net/projects/MEPOD/issues/MEPOD-52
      2. https://jira.atlassian.com/browse/CONFCLOUD-69625
  3. 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.
    1. 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

Click here to expand...

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
"multiexcerpt"	"multiexcerpt-macro"
"multiexcerpt-include"	"multiexcerpt-include-macro"
"PageWithExcerpt"	"page"
"MultiExcerptName"	"name"

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:

Licensing

Atlassian has some guidance on the licensing policies for migrations here: Transfer your self-hosted license to cloud

See the section entitled "App licenses". The policy for app licenses is that there is no transfer or credit from Server/Data Center towards a Cloud license (sorry).

Application vendors rely on Atlassian for licensing and purchasing, for which Atlassian charges a percentage of the license fee. We are always happy to hear feedback on licensing policies but be aware that they are set and controlled by Atlassian and that feedback given directly to them about their policies is probably the best way to get it heard by the folks who set the policies.

Migrating MultiExcerpt from Server/Data Center to Cloud