Output.type in third-party macros when converting to export_view

In multiple of our apps (i.e. Scroll PDF/Word Exporter) we are using the Confluence REST endpoint /contentbody/convert/export_view to convert Confluence storage format to HTML for later conversion to other formats. Recently we noticed that some macros by other vendors were not converting as expected (either outputting nothing or outputting HTML that is not optimal for export conversions). This happens when a macro uses the {output.type} parameter and outputs different content based on that parameter.

If the macro is checking for output.type = pdf or output.type = word this only works correctly when using the Confluence-native PDF/Word export functionality. What we have now realised is that the output.type parameter in a macro will always be "email" when it is converted to export_view format through the REST API. The API does not provide any publicly documented way for us to change this output type either.

I think most macro vendors reasonably would not expect this property to be email when used through other apps. We actually didn’t even realize this until recently and the only hint to this that we found was in the documentation for the renderModes setting of dynamic content macros:

renderModes

email
This render mode will be used when your macro is being rendered during email rendering, and requesting the EXPORT_VIEW representation

Questions

Our questions now are if there are any plans to improve this in the future? Ideally we would like to see the following things:

  1. the ability to indicate the output type to the /contentbody/convert/export_view API so that macros receive this as their output.type parameter
  2. Even better would be if there was a way to also pass additional parameters to this endpoint. On server we have integrations with multiple 3rd-party macros and use the RenderContext to pass information about our apps to the macros for that.

In general it is currently a bit difficult for macros by other vendors to integrate with specific features of our apps on Cloud because of the lack of context information in the macro. For example we are currently in discussions with one macro vendor for improvements that are specific to one of our exporters and the workaround we had to come up with for this so far involves hidden macro parameters that our app would inject into the macro in storage format to transport additional information to the macro, which is obviously a bit hacky.

Example:

  1. Have a static content macro installed in Confluence Cloud that checks the {output.type} parameter in its request URL as described here
  2. Use the installed instance to convert a storage format snippet from storage format to export_view format, for example something like this:
curl --request POST \
  --url 'https://your-instance-name.atlassian.net/wiki/rest/api/contentbody/convert/export_view' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ "value": "<ac:structured-macro ac:name="your-test-macro" ...</ac:structured-macro>", "representation": "storage" }'

Result:
Macro will receive “email” as its output.type with no way for the calling side to indicate otherwise.

1 Like