Leveraging bodied macros to improve our app

[#1]

Atlassian's introduction of bodied macros was a game changer for Confluence Cloud. Before, macros were limited to referencing content externally, which could lead to a fragmented user experience. But with bodied macros, that all changed. Now, macros can encapsulate content directly within the macro body, making it easier for users to work with complex data and tools. We've seen this firsthand with our own Table Enhancer app, which has undergone a significant transformation thanks to bodied macros.

History and Evolution of Table Enhancer

Table Enhancer's journey began as an open-source app for Confluence Server, initially providing basic features like row numbering. Over time, it evolved to include sorting, totals, and sticky rows/columns. When Atlassian announced its cloud-first strategy, we saw an opportunity to take Table Enhancer to the cloud. We developed a cloud version and even before the forge migration assistant was available worked closely with Atlassian to implemented a semi-automatic Data Center to Cloud migration process for our customers' macros to ensure a smooth transition. Without bodied macros the original cloud app had to make some compromises, but it laid the groundwork for significant improvements to come. With the introduction of bodied macros, we were able to enhance the app's functionality and user experience.

Challenges of Non-Bodied Macros

Before the introduction of bodied macros, Table Enhancer faced several challenges. Tables had to be referenced via their index in the page, leading to issues like "No table found" warnings due to accidental deletions or edits. Additionally, when macros were migrated from Data Center the tables had to be extracted. These limitations not only affected the user experience but also made it more difficult for us to maintain and update the app.

Non-bodied Table Enhancer. The table had to be referenced by its index and two tables (the original one and the enhanced) would be rendered.

Leveraging Bodied Macros

The introduction of bodied macros by Atlassian presented an opportunity for Table Enhancer Cloud to overcome its existing limitations. By having the table to be enhanced in the macro body, error-prone configuration by table indices is no longer necessary. This change allows users to update the table in the same location as the macro configuration, streamlining the process. Additionally, it enables us to render only one table in view mode, enhancing the overall user experience. This change also aligns the experience of the app with the Data Center version and allows for a more automatic migration, as the tables can be kept in the macro body when migrating.Bodied Table Enhancer. The table is placed in the body of the macro. Only the enhanced table will be rendered.

Deep Dive: Migrating non-bodied macros to bodied macros

We decided to migrate non-bodied macros to bodied macros to ensure a consistent user experience and reduce maintenance costs. To achieve this, we considered several options: migrating when a page or draft is viewed, providing a trigger to initiate migration, or migrating all pages. We chose to migrate all pages.

To find the macros, we used CQL search to query pages containing "Table Enhancer" and then searched the ADF of these pages for extension nodes that are Table Enhancer nodes. However, we found that a more direct way to search for macros using CQL would be beneficial. Currently, the lack of a straightforward method to search for macros using CQL adds complexity to the migration process.

Another challenge we faced was the inability to use an update task to trigger the migration, as the app update did not have any changes that would make Atlassian classify it as a new major version. The ability to manually designate a version as a major version would have given us more control over the update process, allowing for better migration management.

To work around these limitations, we used an hourly trigger to initiate the migration until all pages were migrated. We also set a page property after a page was processed to exclude pages from future CQL searches, which helped to prevent unnecessary re-processing of already migrated pages. During the migration, we set the macro to be bodied and moved the configured table into its body.

When updating the page, Atlassian rebases the content of the draft to the page, which can cause issues if the content in the draft has been reordered. To avoid this, we retrieved both the ADF of the page and its draft, performed the update process for both, and then updated the page and draft sequentially.

By sharing our migration experience, we hope to provide valuable insights for other app vendors who may face similar challenges. Our approach can serve as a reference point, and we're open to suggestions and feedback from others who have undergone similar migrations.

[Mia Tamm]

Thanks so much for sharing this deep dive @Lina Kuhn _TNG_ — really appreciated how transparently you walked through the technical decisions and challenges. The switch to bodied macros has definitely been a game changer for all of us building on Confluence Cloud.

At Simple Table, we faced a similar situation and decided to offer two macros to support different use cases:

• Simple Table for non-bodied setups, where users might want to use XLS, CSV or JSON type data
• and Simple Table with Body to take full advantage of the new bodied macro capabilities — keeping content and configuration together, with smoother editing and rendering.

This dual approach gave us the flexibility to support both legacy and modern workflows without breaking compatibility, and it’s been well received by teams who appreciate the choice.

It’s great to see how other vendors like you are tackling this shift so thoughtfully — we’re all learning from each other! 🙌

— Mia Tamm from Simpleasyty