Child pages
  • Future Macro

Skip to end of metadata
Go to start of metadata

On this page


The future macro improves page display performance by rendering the body contents in the background while allowing the rest of the page to be displayed. It should be used around sections of a page that take a long time to display because they access external data, run reports or scripts, or gather and summarize metadata. A manual mode is also available that defers the rendering of the section until specifically requested by the user. The future macro shipped in the Cache for Confluence is compatible with the original macro and will be migrated to a native Confluence macro.

The future macro can be a handy way to avoid Confluence's default rendering timeout (normally 120 seconds) for request that are known to be long running any may sometimes exceed the limit. In these cases, it is best to also use with the Cache Macro to minimize the need for the extra processing.

May not work with some specific macros


Originally an Atlassian ShipIt project, it was not maintained and eventually fell behind the times with Confluence 4. It has been spiffed up, fixed up, enhanced, and included with Cache for Confluence starting with release 6.0.

Here is a quote from Chrisopher Owen, the original author:

For Atlassian’s 7th ShipIt Day I implemented a Confluence macro that would defer rendering its body until the full page was received by the client. The body of the macro would then be sent back to Confluence for rendering via AJAX while the user was presented with a loading placeholder. As the rendering of the body occurs in the future with respect to the original page rendering pipeline, I called this functionality the Future Macro. It is ideally suited for rendering content that is retrieved from external sources where high latency can hold up the delivery of other content on the page.


ParameterDefaultMacro BrowserDescription
titleLoad or LoadingTitle

Text displayed before rendering completes. Also will appear on the manual button. Helps user understand what information is going to appear.

Prior to release 6.7, the default text would appear followed by the user provided title. After release 6.7, by default, only the user provided title will appear if it is not blank. There is an administrator option to control the behavior. See the incompatibility notice.

manualfalseManualWhen specified, the section will only be rendered after the user presses the load button. The rendering proceeds in the background until available.
timeout120 secondsMaximum number of seconds to render sectionTimeout in seconds before the section rendering is abandoned. Once abandoned, a timeout error message will be displayed.
delay0Delay in secondsRendering will be delayed by the number of seconds requested. The client browser will delay sending the request to the server to render the body. This applies only to manual=false cases. This can be used in cases where there are multiple future macros on the same page and it is more important to render some of these more quickly than others so the results for those will appear quicker. Since 6.7.
retryIntervalDefaultRetry interval in seconds

When greater than 0 and the rendering of the body indicates an error that can be retried, the client will wait and then retry the request. See Retry Feature. Default uses the default setting configured in administration. Since 6.8.



 Default loading message

Manual load

Macro browser preview loading

Note that in macro browser preview, only the loading message will show. The body will not be rendered in the preview window.



SQL Example

select * from products




  • No labels


  1. Hi,

    I get an error in combination with the security macro:

    Error rendering macro 'future' : Security restricted macro is not allowed. An edit restriction is required that matches the macro authorization list.

    Have you heard others about this? Is there a solution?

    1. The future macro is use controlled when macro security is enabled for an installation. See Macro Security Managed Macros. You will need to add a configuration entry for it.

  2. Hi,

    I got an error when using sql query macro inside the future macro:

    Error rendering macro 'sql-query' : java.sql.SQLException: Incorrect syntax near '&'.

    The query was fine in the edit page, but after i saved it, the error came out.

    I tried many times any I found the problem might be caused by the string character inside the query.


    select * from tableA

    where colA = 'abc'

    ===>   error

    select * from tableA

    where colB = 5

    ===>  works

    Is that a bug?


  3. Is there a method to centrally manage / configure the (default) "timeout" value of 120 seconds (xml file or similar will suffice)? I have a scenario where I'd like to increase this value across my entire confluence instance (where Default has been specified as the timeout parameter for this macro)? 

    1. Currently no, that is not configurable. That is a valid request and something anticipated when we used the default setting. Please open an issue.

      1. Thanks Bob. I've created an improvement request: CACHE-84, Feel free to enrich/refine as you see fit. 

  4. Hi,

    I am trying to put an Include Page Macro within the body of Future Macro. The Page I am trying to include has a pdf image within it. When I set manual= true for the Future macro and press the "Load" button, the pdf image thats present in the page included in the Include Page and Comments macro doesnt show up. I looked at the documentation of the interoperability of Future macro with other macros here : https://bobswift.atlassian.net/wiki/display/CACHE/Future+macro+-+interoperability

    but it looks like there is no scenario supported with outer macro as future and inner macro as Include Page and Comments. Any idea on how do I fix the issue I am facing?

    1. This scenario works, but you need to have Cache 6.4 installed and be on Confluence 5.4.3 or higher.