Migrate a macro module from Connect to Forge (EAP)

This page describes how to migrate Confluence content macros from Connect to Forge.

It also describes the differences between Connect and Forge custom macro data.

After migrating your Connect app's staticContentMacro and dynamicContentMacro modules to Forge macro modules, the Connect macros saved within Confluence pages will invoke the corresponding Forge macro module, along with a migrated version of the Connect app's stored custom data.

Use the same macro key

To display a Connect macro's data with a Forge macro module, make sure your Forge macro key matches the Connect macro key.

For example, if your Connect app has a macro with key static-macro-key, your manifest should include this in modules.macro[].key, like this:

1
2
modules:                       
  macro:
    - key: static-macro-key   ## Forge macro key - matches Connect macro key
      function: main
      # ...
remotes:
 - key: connect
   baseUrl: https://hello-world-app.example.com
 app:
   id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
   connect:
     key: hello-world         ## Target connect app key
     remote: connect

Accessing the Connect app macro data

You can access the Connect app macro config data from your Forge app using the useConfig hook.

When the Forge macro is invoked, the useConfig hook returns the key-value pairs of both migrated Connect custom data and the Forge configuration data.

1
2
import { useConfig, Text } from '@forge/ui';

const defaultConfig = {
  // Connect stores and sends custom data as a string
  connectUsers: 'd937s5q89n47okrxdzv854d5,3stlhnx34at4uusanwtbwnev',
  // Forge supports array type custom data
  forgeUsers: ['d937s5q89n47okrxdzv854d5','3stlhnx34at4uusanwtbwnev']
};

const App = () => {
  // Retrieve the configuration
  const config = {
    ...defaultConfig,
    ...useConfig()
  }
  
  // Use the configuration values
  return <SectionMessage>
    <Text>Old value from connect : {config.connectUsers}</Text>
    <Text>Forge value : {config.forgeUsers.join(',')}</Text>
  </SectionMessage>;
};

Connect macro parameters

Connect custom macro parameters keep their format when passed to a Forge macro module.

For example,

• A Connect parameter represents an array as a comma-separated string, such as VALUE1,VALUE2.
  • If the values your Connect app stores in the array contained a literal comma (,) this is not escaped, so special handling is needed.
  • Forge fully supports arrays and other arbitrary JSON for config parameters, and can store this data with no special handling.
• If the Connect macro stores Current Space for the spacekey parameter type, the Forge app receives the string currentSpace(), instead of the literal space key.

Connect macro variables and product context parameter

Rollback to Connect macro

Stored Connect macro data is only converted to the Forge macro format when a user edits the macro and publishes the page.

This means that while it's possible to rollback to a Connect macro module on Forge, only macros that have not been edited by a user can be rolled back to a Connect macro module.

To rollback to a Connect macro module, define the Connect module in your Forge manifest, like this:

1
2
connectModules:
  'confluence:staticContentMacros':
    - key: static-macro-key # Add connect macro module back
      url: /view_macro
      ... 
modules:                       
#  macro:    # Remove the Forge macro to rollback
#    - key: static-macro-key
#      function: main
#      ...
  ...
remotes:
 - key: connect
   baseUrl: https://hello-world-app.example.com
 app:
   id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
   connect:
     key: hello-world
     remote: connect

Limitations and issues

• Macros with a rich-text body are not supported in Forge.
• macroId is no longer available.
• Forge macros support page exports, with some caveats.
  • See the export property of Macro module properties for details.
• Stored Connect macro data is only converted to a Forge module when the macro is edited and the page is published.
• If a user has not changed parameter values from the default values specified in Connect, the parameter values are not saved with the macro and appear undefined when migrated.
  • If you want the default parameter values set in your Forge app, set them in Forge to match the default values in your Connect app.
• Also read more about Limitations and differences when adopting Forge from Connect

How to adopt Forge from Connect

See Adopting Forge from Connect for all the steps to incrementally start using Forge.