Migrating Confluence Macros from a P2 Server App to a Forge Cloud App

If you're migrating a Confluence server app which has some macros to your Forge app in Cloud, we have added support for your macro to be rendered by your Forge app after migration. App vendors have some required setup steps to use this new feature.

App vendors who use this feature will not only be able to render their server Macros with their Forge apps, but editable macros will be automatically converted from the P2/Connect storage format to the Forge storage format the first time that a user edits the macro on Cloud.

The rendering and updating capabilities introduced in this feature are only compatible with the modern Confluence Editor. Migrated P2 macros cannot be rendered or updated in the Confluence Legacy Editor.

Preparing your Server App

Starting in version 1.8.0 of the atlassian-app-cloud-migration-listener: you will also need to implement the ConfluenceAppCloudMigrationListenerV1 interface in addition to DiscoverableForgeListener. The methods to be implemented are:

Example

1
2
@Override
public Map<String, String> getServerToForgeMacroMapping() {
    Map<String, String> macroMappings = new HashMap<>();
    macroMappings.put("my-server-app-macro-name", "my-forge-app-macro-name");
    return macroMappings;
}

Preparing your Forge App

If you enable this feature by implementing the above interface in your server app, the App Migration Platform will migrate your Confluence Macro with necessary metadata for the Confluence Editor to understand that your Forge app is responsible for rendering the migrated macro.

Since a migrated P2 server macro is stored in the same format as a Cloud Connect Confluence Macro after migrating, we have re-used the Connect to Forge Macro conversion path.

In order to facilitate the correct rendering and upgrading of the migrated P2 Macro using your Forge app, your Forge Macro module must be prepared to receive the P2 Macro config parameters. See this section for more details on how to prepare your Forge App.

Notes

Since the migrated P2 Macros are stored in the same format as Cloud Connect Macros, we are constrained to the same limitations as the Connect to Forge Macro rendering feature.

Notably, the migrated P2 macros cannot be rendered or edited in the Legacy Editor.