Migrating Confluence Macros from a P2 Data Center App to a Forge Cloud App

There is a migration path from Confluence Data Center app with macros to Forge apps in Cloud. Macros will be migrated and usable in cloud. Editable macros will be automatically converted from the P2 Data Center 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 Data Center App

Ensure your app is using at least version 1.8.0 of the atlassian-app-cloud-migration-listener.

You will need to implement the ConfluenceAppCloudMigrationListenerV1 interface on the same class that implements DiscoverableForgeListener. There should be only one class implementing these interfaces for each Forge App ID that you support migrating. The method to be implemented is:

Example

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

Preparing your Forge App

If you enable this feature by implementing the above interface in your Data Center 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.

Declare the Forge macro in your manifest

Declare the Forge macro module in your Forge app's manifest. Make sure the Forge macro key matches your Data Center macro name as returned by getServerToForgeMacroMapping.

1
2
modules:
  macro:
    - key: my-forge-app-macro-name # Forge macro key - must match the value in your DC app's getServerToForgeMacroMapping map.
      resource: main
      # ...

Macro lifecycle

After migration, your Data Center macros are stored in Confluence in an intermediate storage format. Note that the intermediate format uses an extensionType of com.atlassian.confluence.macro.core:

1
2
{
  "type": "extension",
  "attrs": {
    "extensionType": "com.atlassian.confluence.macro.core",
    "extensionKey": "my-forge-app-macro-name",
    "parameters": {
      "macroParams": {
        "myDCField": {
          "value": "some text"
        }
      }
    }
  }
}

When a user views a page with a migrated Data Center macro, Confluence looks for the corresponding macro with a matching key in your Forge app, and renders it. Even though the macro hasn't been fully migrated to the Forge format yet, the existing Data Center config parameters are provided to your Forge macro.

Only when a user edits the configuration of the macro and publishes the page does the storage format get migrated to the Forge format. Note that the Forge format uses an extensionType of com.atlassian.ecosystem, and the extensionKey is now prefixed with your app ID (aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee in the example below):

1
2
{
  "type": "extension",
  "attrs": {
    "extensionType": "com.atlassian.ecosystem",
    "extensionKey": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/static/my-forge-app-macro-name",
    "parameters": {
      "guestParams": {
        "myForgeField": "some text"
      },
      "macroParams": {
        "myDCField": {
          "value": "some text"
        }
      }
    }
  }
}

Note that the type of the macro (extension for default block layout, bodiedExtension for bodied, inlineExtension for inline), is preserved during migration, even if the Forge macro declares a different type in the layout parameter.

You can revert the macro to the intermediate format by restoring an older version of the Confluence page from the page history view. This can be useful during development and testing of Data Center macro data migration, covered in the next section.

Accessing and migrating Data Center macro data

The method to access data from your migrated Data Center macros is the same as accessing configuration data for a Forge app.

The first time a user edits a migrated Data Center macro using Forge, all existing Data Center parameters are available through the provided config object.

Then, when the user saves the macro, only the parameters explicitly declared by your Forge app are stored. Only these parameters are available in the config object on subsequent macro edits. Any other Data Center parameters will no longer be available to the Forge app. You can think of this as a one-time migration of Data Center parameters to Forge parameters.

You can choose to use the same parameter keys in your Forge app as in your Data Center app, or you can rename them. Renaming is recommended if you have to transform the values to be compatible with your Forge app.

1
2
import React from "react";
import { view } from "@forge/bridge";
import ForgeReconciler, { Textfield } from "@forge/react";

const Config = () => {
  const [context, setContext] = useState(undefined);

  useEffect(() => {
    view.getContext().then(setContext);
  }, []);
  const config = context?.extension.config;

  return (
    <>
      {/* Keep an existing Data Center field as is.
       * This will automatically be populated with the parameter from your migrated Data Center macro, if it exists */}
      <Textfield name="myDCField" label="My DC Field" />
      {/* Add a new Forge field, with a transformed value from the Data Center macro, if it exists */}
      <Textfield
        name="myForgeField"
        label="My Forge Field"
        defaultValue={config?.myOldDCField?.replace("old", "new")}
      />
    </>
  );
};
ForgeReconciler.addConfig(<Config />);

Migrated macro parameters

Migrated Data Center macro parameters maintain their existing format when passed to a Forge macro module, and do not undergo any automatic conversion.

Here are some notable differences to be aware of:

• A Data Center parameter represents an array as a comma-separated string, such as VALUE1,VALUE2.
  • If the values your Data Center app stored in the array contained a literal comma (,) this is not automatically escaped, so special handling is needed.
  • Forge supports arrays natively, and can store this data with no special handling required.
• If the Data Center macro stores the value representing the "Current Space" for the spacekey parameter type, the Forge app receives the string "currentSpace()", instead of the literal space key.

Parameter type mapping

The below table shows how various Data Center macro parameter types are passed to Forge macro modules. Note that values are always passed as strings, regardless of the original type.

The below table lists some special cases, and how they can be accessed from Forge macro modules:

Product context parameters

Many context parameters available to Data Center macros are still accessible via Forge product context.

The following table lists the mappings between these parameters:

Limitations and differences

General

• macroId is not available for newly created Forge macros. You can use the more generic localId instead.
• Forge macros are not supported in the legacy Confluence editor.
  • Migrated macros cannot be rendered in the legacy editor once migrated to Forge, however if they define an adfExport function, that static content will be shown.
  • Migrated macros cannot be edited in the legacy editor once migrated to Forge. Convert the page to the new editor to be able to edit Forge macros.
  • New Forge macros cannot be created in the legacy editor.

Macro layout

• Forge macros do not support adding plain text or multi-bodied macros.
  • Reading existing plain-text bodies from migrated Data Center macros is supported through the __bodyContent key in the config object.
  • If you want to provide a similar experience to plain text macros in your Forge app, you can use a TextArea component in your macro configuration.
• You cannot change the body type of an existing macro as part of the migration, even if the Forge macro declares a different type in the layout parameter.
• Forge macros can be children of rich bodied macros, with some limitations:
  • Forge child macros support rendering static content only, via an adfExport function.
  • The parent macro must obtain this exported static content via the Confluence's content conversion APIs and render it in the rich bodied macro.

Configuration data

• If a user has not changed parameter values from the default values specified in the Data Center app, the parameter values are not saved with the macro and will not appear in the migrated configuration data.
  • If you want the default parameter values set in your Forge app, set the defaultValue properties of your Forge fields to match the default values in your Data Center app.