Make your App's Macros Display Properly in Exports

By default, Scroll Word Exporter will export most third-party macros without issue.

However, occasionally some third-party macros will not be exported correctly. Normally, this is because the macro has been designed to be displayed in Confluence which behaves differently from a Word file. Therefore, some macros can be displayed differently in the export because: 

• The dimensions do not match – a Confluence page is presented in a landscape format, whereas a Word file is normally in a portrait orientation. 
• The browser for a Confluence page displays scroll bars – a Word file cannot display this information. 
• The macro may lazy-load some data in the browser using a REST interface in order to speed up the original page loading times in Confluence, or because the user first needs to interact with it

This article describes how you, as an app developer, can make sure your macros display properly in Word exports.

Required steps

To avoid macros being displayed incorrectly, developers must ensure that macros are adaptable so that they are properly displayed in both the Confluence page view and the exported Word file. This can be achieved by the macro implementing the correct render modes which will then be used by the exporter.

Connect apps

• If your macro is a Dynamic Content Macro provided by a connect app, you need to implement and declare a static render mode.
  Please make sure to either implement either an endpoint for the email or default render modes. The render modes pdf and word are not usable by 3rd party apps and therefore will NOT be called when exporting content with any Scroll Exporter app.
• If your macro is a Static Content Macro you don't need to implement another endpoint.

Forge apps

If your macro is a Forge macro and is using Custom UI you need to implement and declare an export function property in the manifest. If your macro is just using UI Kit instead it should already work by default and you only need an export function property if your macro should display differently in the export than in the browser.

Implementation hints

• The connect endpoint or forge function must return standalone HTML with embedded styling if necessary.
• If images from external sources (not the Confluence instance) are referenced, they must either be publicly available without any authentication, or the image link must contain authentication data (e.g. temporary access tokens).
• The macro implementation should be as fast as possible. That's because Atlassian imposes a 30 second rendering timeout on the REST API used by Scroll Exporter apps when the content of a page is being rendered. Depending on how many macros have been put on a page by an end user, and depending on the individual macro instance rendering time, this timeout can be exceeded, resulting in a broken export.

Macro context

In contrast to Server / Data Center it is not possible for the Scroll Exporter apps to provide additional context in the macro invocation context on Cloud. If you want to optimize the output for individual export formats, please reach out to us.

In the past we've worked around this limitation with other vendors by injecting additional (hidden and optional) macro parameters into the macro invocation. This needs to be enabled on a per app / macro basis to avoid breaking macros.