Last updated Sep 1, 2022

Forge’s EAP offers experimental features to selected users for testing and feedback purposes. These features are not supported or recommended for use in production environments. They are also subject to change without notice.

For more information, see Forge EAP, Preview, and GA.

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:

    - key: static-macro-key   ## Forge macro key - matches Connect macro key
      function: main
      # ...
 - key: connect
   id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
     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.

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 = {
  // Use the configuration values
  return <SectionMessage>
    <Text>Old value from connect : {config.connectUsers}</Text>
    <Text>Forge value : {config.forgeUsers.join(',')}</Text>

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 parameterExampleParameter name
attachmentfile_name.txt,file_name.jsonSame as the Connect parameter identifier
booleantrue,falseSame as the Connect parameter identifier
confluence-content~123456:SPCKEY:Space Title,~123459:SPCKEY2:Space2 TitleSame as the Connect parameter identifier
enumOPTION_1,OPTION_2Same as the Connect parameter identifier
spacekeycurrentSpace(),SPACEKEYSame as the Connect parameter identifier
username5e68dltko888jugaukrgg55e,5d33vdjq0ilg19qyy25ik45vSame as the Connect parameter identifier
stringExample input stringSame as the Connect parameter identifier
urlParameter from autoconvert
plain-text macro body{\n \"foo\": \"bar\"\n}__bodyContent
rich-text macro body<h1 id="pagetitle-RichTextBody">Rich Text Body</h1><p>Congratulations!</p>Not supported

Connect macro variables and product context parameter

Connect macro variable Forge product context Description
macro.idextensionContext.connectMetadata.macroIdThe unique ID of the Connect macro. Only exists for migrated Connect macros.
macro.bodyNot supportedThe macro body, truncated to 128 characters
macro.truncatedNot supportedTrue if the macro body was truncated, false if not
page.idcontentIdThe ID of the content this component appears in
page.titleNot supported, page information can be fetched using the Confluence API with the contentId.The page title
page.typeThe page type
page.versionThe page version
space.idThe space ID
space.keyspaceKeyThe space key
output.typeNot supportedThe output type. For example, display or preview
Not supportedaccountIdThe Atlassian ID of the user that interacted with the component
Not supportedlocalIdA unique ID for this instance of this component in the content
N/AinstallContextThe ARI identifying the cloud or product context of this component installation
N/AextensionContextContextual information about the current environment that relates to the extension
Not supportedlicenseWhether a paid app is licensed in the installation context. This field is only present for paid apps in the production environment.

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:

    - key: static-macro-key # Add connect macro module back
      url: /view_macro
#  macro:    # Remove the Forge macro to rollback
#    - key: static-macro-key
#      function: main
#      ...
 - key: connect
   id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
     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.
  • 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.

Rate this page: