Hello there Atlassian Partner Developers,
During the last few months, we have been focused on addressing a key functionality gap between Confluence Server and Confluence Cloud - specifically support for nesting bodied macros in the Fabric editor. Nesting bodied macros allows customers in Server to compose elaborate macro structures which can easily pass their content upward to an outer macro. While we continue to encourage customers and apps towards the Cloud, these structures will not all work as is in the Fabric editor in Cloud and will need to be updated. This is because the macros themselves are sandboxed within an iframe, making data communication between nested bodied macros more difficult than would be than on the Server.
In order to support this functionality, we have begun building a new technical architecture to provide a more WYSIWYG experience than was available in Server. This architecture will allow users to create references from one macro to another, including Dynamic Content macros. This new technical foundation, as well as new user experience of referencing, will help users address the use cases that they relied on nesting bodied macros to compose, aiming to provide equivalent functionality with a better user experience.
We would like to take this opportunity to show you what is coming soon to support Nested Bodied Macros, to keep you informed of our engineering progress and to get feedback on what is coming down the pipe in the months ahead. We are calling the capability Referentiality (for now), and we are excited for the possibilities it can bring for Partners, but we also want to hear from all of you what you think about this before we get too far down the line.
What are the problems we are trying to solve for?
As more customers migrate over from Server to Cloud, end-users expect similar functionality as they have had in Server with nested bodied macros. As content creators create more pages within the new Editor, they will still want a way to easily chain macros together regardless of whether it is a native Confluence macro, or a Connect or Forge macro.
And as Partner developers have already invested in the Connect ecosystem, we know that you want to easily adapt your existing Connect macros to empower content creators to continue using your macros in the Cloud. We hear you and understand that it will take time to update your app to Forge, and that you need an intermediary solution.
What is our vision for tackling this?
Our solution includes building a Referentiality model to allow data sharing between different types of macros within Confluence, whether it be an existing Connect macro, a native Confluence macro, or a Forge app. All of these would be able to be chained (rather than nested), linking them together interchangeably via an internal message broker. With a few minor modifications within the macro and to your Connect Descriptor or Forge Manifest, your macro would be able to publish, subscribe, and react to changes based on the data coming from another macro (both native or Marketplace app), similar to what you had in the Server world with nested bodied macros.
For our initial release, we are adding a Connect and Forge extension point in the Contextual Toolbar which you can add to your macro. Each subscribing macro will be included as a Contextual Toolbar Item to ingest the data from the publishing macro. Here is an example of an existing Table Macro using the Contextual Toolbar which includes the option to inject a dynamic pie chart with its data binded to the table.
Our longer-term North Star will include additional features such as the ability to name and reference macros, to visualizing a navigable macro chain, to allowing multiple macros from different pages to be chained and rendered in a WYSIWYG fashion. Having a WYSIWYG experience will reduce user uncertainty by rendering the same view within the Editor and Renderer. This allows the content creator to be able to experience what the published version of the page looks like without having to publish the current page being edited, ensuring a much better user experience for the content creator and content consumer alike.
This can all be configured using the Right Context Panel. Content creators would be able to configure the macro chain, how each macro fits within the data chain, and set the view settings for the individual macros within the chain as shown on the diagram below. Imagine how much happier content creators will be with the new WYSIWYG experience in Cloud; they would have wished they migrated to the Cloud sooner.
How will it work and what are some of the changes required?
Your descriptor or manifest will need to be updated with a new refDataSchema property dictating the data ingress and data egress types of each of the macros. While this allows for any unstructured data types to be freely used, we are starting with an initial rollout to support our most common use case, Tables. For your macro to support data flows to and from Tables, you can use either the table-adf or table-json schema types. To support Connect macros, we have created a new API for your macros to emit data - AP.dataProvider.emitToDataProvider - and register for data changes with the data_provider topic.
Why not just migrate my existing Connect application to Forge?
While we would like for all our Partners to migrate and rewrite all their apps with Forge eventually, we know that this undertaking will be significant and will not happen overnight. So we made these changes to ease this transition phase for Partners while allowing our end users to fully adopt the new Fabric Editor. If you are interested in migrating your Connect application to Forge, you can read more about our Connect-on-Forge path here https://blog.developer.atlassian.com/unifying-atlassian-connect-and-forge-an-update .
What’s next?
We expect an initial release for our Partners in the Ecosystem Beta Group to land later this year. In the meantime, if you haven’t joined the Ecosystem Beta Group, consider joining by reaching out to your Technical Program Manager. Also, look forward to the next post detailing the specific changes required to take advantage of Referentiality within Confluence, and a demo of how you can enable Referentiality.
Let us know what you think of what’s coming!
