Embedded Forge Macros EAP

Forge Forge UI Kit and Custom UI
, ,
1

Hi everyone,

We’re excited to announce the Early Access Program (EAP) for a new Forge platform capability: Embedding Forge Macros within Confluence pages. This EAP aims to support Connect to Forge migration, enabling richer macro experiences and more powerful integrations for your apps.

What’s new?

  • Embed Forge macros inside other Forge macros: Developers can now render Forge macros within the body of other macros, unlocking new composability and extensibility scenarios.

  • Support for UI Kit and Custom UI: The solution works for both UI Kit and Custom UI macros, with a new renderer package and FAUS service route to handle rendering and communication.

  • Bridge methods supported for embedded macros
    Most core bridge methods are now wired to work from embedded macros in Confluence (for example showFlag, invoke, invokeRemote, requestConfluence, requestJira, router methods, and view methods). See documentation for all bridge methods currently supported.

Learn more in the documentation.

Note: This capability isn’t a 1:1 replica of Connect platform, nested bodied macros. Hence Custom UI apps may experience some performance trade‑offs compared to Connect, while UI Kit apps are expected to remain performant.

To join this Early Access Program, please complete the Forge EAP sign-up form.

We’re looking forward for your feedback! Please leave any feedback on this post or via your individual EAP tickets submitted.

2

Hey @VickyHu, just curious, will this EAP allow bodied macros to be rendered on published pages as actual native ADF, rather than in rendered iframes? Or is there a separate request for that? I ask because we use a lot of bodied macros at our company and rendering the content stored within those bodied macros via separate iframes creates a heavy load on our pages.

3

Hey @VickyHu,
this is great news and closes some gaps we’re facing wrt. migrating our bodied macros to forge.

Are there any plans to also support Connect macros embedded in Forge macros?
Because if we would migrate our bodied macros to Forge right now, we’d have a lot of customers rightfully complaining that other macros are not rendered anymore in their existing content.
This means that as long as other macros (from other vendors) are not yet migrated to Forge, we cannot migrate our bodied macros to Forge.
But at least with this EAP we will be able to migrate our inline macros to Forge.

4

Hey Peter!
Sorry for the delayed response, I definitely understand the need for connect macros to render in Forge. Unfortunately at this time we’re unable to support this but this is something I’m exploring. Will provide an update on this EAP post when we come to a conclusion on this.

5

Hi @QuinnSouther ,

If you are using Custom UI as the bodied macro then the content has to be rendered within an iframe. If you use UI Kit as the bodied macro then it will be much faster as is it won’t have to render an addition iframe wrapper for the bodied macro content.

If you have to have to use Custom UI as the bodied macro then the content will be first rendered in a wrapping iframe then each macro will be rendered either in an iframe if it is a Custom UI macro or not if it is UI Kit.

This is what the ADF document would look like for a Custom UI Bodied macro with a Custom UI macro inside.

Does that answer your question?

{
  "type": "doc",
  "content": [
    {
      "type": "bodiedExtension",
      "attrs": {
        "layout": "default",
        "extensionType": "com.atlassian.ecosystem",
        "extensionKey": "example-bodied-extension-key",
        "text": "custom-ui-bodied-macro (Development)",
        "parameters": {
          "layout": "bodiedExtension",
          "forgeEnvironment": "DEVELOPMENT",
          "extensionProperties": {
            "accountId": "example-account-id",
            "extension": {
              "appVersion": "3.13.0",
              "environmentType": "DEVELOPMENT",
              "consentUrl": "https://id.atlassian.com/outboundAuth/start",
              "dataClassificationPolicyDecision": {
                "status": "ALLOWED"
              },
              "type": "xen:macro",
              "environmentKey": "default",
              "environmentId": "example-environment-id",
              "appId": "example-app-id",
              "scopes": [],
              "id": "example-extension-ari",
              "installationId": "example-installation-id",
              "properties": {
                "layout": "bodied",
                "resolver": {
                  "function": "resolver"
                },
                "resourceUploadId": "example-resource-upload-id",
                "resource": "main",
                "description": "Inserts Hello world!",
                "title": "custom-ui-bodied-macro",
                "type": "xen:macro",
                "key": "custom-ui-bodied-macro-hello-world"
              },
              "key": "custom-ui-bodied-macro-hello-world"
            },
            "cloudId": "example-cloud-id",
            "contextIds": [
              "example-confluence-workspace-ari"
            ],
            "extensionData": {
              "type": "macro",
              "content": {
                "id": "example-page-id",
                "type": "page"
              },
              "space": {
                "id": "example-space-id",
                "key": "example-space-key"
              }
            }
          },
          "localId": "example-local-id",
          "extensionId": "example-bodied-extension-id",
          "extensionTitle": "custom-ui-bodied-macro (Development)"
        },
        "localId": "example-local-id"
      },
      "content": [
        {
          "type": "paragraph",
          "attrs": {
            "localId": "example-paragraph-local-id"
          },
          "content": [
            {
              "type": "inlineExtension",
              "attrs": {
                "extensionType": "com.atlassian.ecosystem",
                "extensionKey": "example-inline-extension-key",
                "text": "custom-ui-inline-macros (Development)",
                "parameters": {
                  "layout": "inlineExtension",
                  "guestParams": {
                    "myField": "test"
                  },
                  "forgeEnvironment": "DEVELOPMENT",
                  "extensionProperties": {
                    "accountId": "example-account-id",
                    "extension": {
                      "appVersion": "3.1.0",
                      "environmentType": "DEVELOPMENT",
                      "consentUrl": "https://id.atlassian.com/outboundAuth/start",
                      "dataClassificationPolicyDecision": {
                        "status": "ALLOWED"
                      },
                      "type": "xen:macro",
                      "environmentKey": "default",
                      "environmentId": "example-inline-environment-id",
                      "appId": "example-inline-app-id",
                      "scopes": [],
                      "id": "example-inline-extension-ari",
                      "installationId": "example-inline-installation-id",
                      "properties": {
                        "layout": "inline",
                        "resolver": {
                          "function": "resolver"
                        },
                        "resourceUploadId": "example-inline-resource-upload-id",
                        "resource": "main",
                        "description": "Inserts Hello world!",
                        "type": "xen:macro",
                        "title": "custom-ui-inline-macros",
                        "config": {
                          "resource": "macro-config",
                          "viewportSize": "max",
                          "title": "Config"
                        },
                        "key": "custom-ui-inline-macros-hello-world"
                      },
                      "key": "custom-ui-inline-macros-hello-world"
                    },
                    "cloudId": "example-cloud-id",
                    "contextIds": [
                      "example-confluence-workspace-ari"
                    ],
                    "extensionData": {
                      "type": "macro",
                      "content": {
                        "id": "example-page-id",
                        "type": "page"
                      },
                      "space": {
                        "id": "example-space-id",
                        "key": "example-space-key"
                      }
                    }
                  },
                  "localId": "example-inline-local-id",
                  "extensionId": "example-inline-extension-id",
                  "extensionTitle": "custom-ui-inline-macros (Development)"
                },
                "localId": "example-inline-local-id-2"
              }
            }
          ]
        }
      ]
    },
  ],
  "version": 1
}
6

We’ve been testing the view.createAdfRendererIframeProps EAP and wanted to share some of the issues we encountered:

  • We were unable to change the surface/background color of the iframe content.

  • Some Atlassian macros, such as the Child items Confluence macro, could not be rendered properly.

  • Smart Links and media content are currently not supported.

We hope these limitations can be addressed in future updates, as resolving them would significantly improve the rendering experience on our side.

Please let us know if there are any recommended workarounds or configuration changes we might have missed.
Previewing Image attachment

Also any idea when this EAP becomes GA ?

7

Hey Logan, thanks for the reply earlier.

What’s odd is that I was getting the iframe-based rendering even in a native UI Kit app, not a Custom UI app. Are you saying it should render directly on the page without an iframe wrapper at all if I’m using UI Kit? Or are you saying that there would still be an iframe container for the bodied macro to be rendered on the page natively with UI Kit, but that there’s some additional iframe layer/wrapper where Custom UI is used?

8

When rendering any macros nested or embedded inside forge macro will there be any size limit for the ADF doc?
Is there a limit number for multiple embeddings of macros?

9

Hi @VickyHu this sound very helpful for us and we’d like to use it as soon as possible. To help us set expectations with customers, are you able to give us an idea of when it will be GA?

10

Hey Everyone! Thanks for participating in our EAP.
We have released Embedded Macros into Preview. This can now be used in production instances with customers and any breaking changes can be expected to have a 3 month deprecation window.
Track our GA timeline on our public roadmap ticket!