Changes to Connect sub extension initialization

What is changing?

If you have an app which renders Dynamic Content Macros that have a rich-text bodyType, content created with the legacy Confluence editor (TinyMCE) can contain other macros within the macro body. If you use the Confluence Content body API to convert a macro body to HTML for rendering, and any nested macros are also Connect apps, then Connect will render a JavaScript snippet to bootstrap the nested Connect app’s macros. We have made a change to the way the nested bodied macros get bootstrapped which should not affect the functionality, yet will make the feature more secure. We are asking anyone who maintains macros with such functionality to keep an eye out for erroneous behavior and to let us know if you are affected by this change.

Why is it changing?

We are changing the initialization implementation to eliminate a security risk.

What do I need to do?

For most vendors, there is no action to take. If your app allows for nesting of bodied macros, please verify that this implementation change does not negatively affect current nested functionality and alert Atlassian if it does. Based on our testing, we do not expect it to and there should otherwise be no action to take.

By when do I need to do it?

November 16, 2020 : Changes will take effect in the Cloud Vendor First cohort of tenants. To enroll a Confluence tenant in this cohort, visit

November 20, 2020 : Changes will take effect for all tenants. Note this is a shorter deprecation period due to security implications.


Any more details what this is?


Apologies, let me put a bit more context in my original message.



Do you have any idea when this capability was introduced? I had no idea this worked, honestly, but it’s game changing. We have had some macros that have been around for years that do this very thing, but when they were written this sub iframe capability did not exist, so we currently rewrite the SFXML before rendering to prevent nested connect macros from being loaded to prevent what was once ugly errors that would be rendered in their place. I will look into testing our app without that protection enabled.

Is there documentation on this behavior on the Connect site anywhere? I couldn’t find any, but perhaps I am not using the right search terms? Details in the documentation would be greatly appreciated if it can be added (or if I am just missing it!).


I’m with @BobBergman!! :mindblown: We have been asking for this functionality for years and always told that it can’t work. Docs please!


I created two macros in the legacy editor, one inside another, and published them.

I’m seeing that the outer macro behaves normally, but the request to get the nested macro is missing a number of parameters including space key, page id and page version

I tried hardcoding some values to get it to render and checking AP.getContext on the client side in case the values were accessible there, but no luck. I agree with others that some documentation would be good here.

Outer macro:

Inner macro:


We have implemented this security fix instead of deprecating this capability to enable an easier migration pathway from Server to Cloud. Despite this change, there is still only a limited ability to nest bodied macros, and only within the TinyMCE editor. This capability is not supported in the Fabric editor, so please do not rely on it for future development. Instead, we are developing equivalent functionality with an improved user experience in Forge to support interaction across native features and apps in the Fabric editor. This work is still in development, but as we get nearer to release of the capability, we will absolutely publish documentation for this fully supported functionality.

That all being said, we want to keep our communications channels open, so please reach out to us if you have use cases that require such functionality and we can schedule some time to discuss more. We look forward to your input for us to shape the future of editor extensibility together.


We haven’t confirmed this is due to these changes (unsure how we would) but since this was introduced it’s been reported:

  • that in some cases scroll appears on nested macros when it is not expected (instead of showing the whole macro)
  • nested macros in some cases not shown
  • nested macros missing the intended look and styling

Is there anyway for us to test if these issues are due to this change?