Child pages
  • Cache Macro

Skip to end of metadata
Go to start of metadata

On this page

Caches rendered data to improve page display performance.

Caches the rendered contents of the body of this macro. Very useful when using macros that might be slow to render content, but where it does not really need to be dynamically generated for each and every request. Specifically, this can improve performance for accessing dynamic data from SQLExcel, and similar macros. Cache will be refreshed if the body of the macro changes or if attachments to this page have been added, removed, or have newer versions. The cache applies to all users that view the page. The cached content can optionally be indexed for Confluence search.

User specific content

Do not use the cache macro around content that renders differently for different users. This is especially important for any content that is security sensitive.




Something to cache for a day
This will be cached for 30 minutes
{cache:refresh=2 hours}
The excel data will be cached for 2 hours
{cache:cron=30 * * * *|showRefresh=true|title=Refresh data from database}
This will be cached until 30 minutes past each hour of the day
select * from report
System.out.println("Hello world " + (new Date()) );

Advanced Examples

Tips and Techniques

Compatibility With Other Macros

See Interoperability

Cache Refresh

  • To force all cache macros on a page to refresh, use the refresh request attribute with value true
    • Example

  • To force a specific cache macros on a page to refresh, use refresh request attribute with value equal to the cache macro id. If not specified, it defaults to a sequence number based on position on page
    • Example



  1. Does the cache macro work with the include macro?
    If so, should cache be used

    • On the including page around the include macro or
    • On the page to be included around the entire body?
    1. Trial and error showed cache needs to be used in the page to be included to work properly, and not around the include macro itself.

      1. Either should work. Normally, it should be around the section of a page that has the expensive operation (like a query).

        1. Would it work with the iframe macro? I have a script running on a remote host that is being queried and the response loaded within an iframe on a confluence page. It would be nice to have that query run only once a while and not every time that page is requested.

  2. Please clarify this for me:

    What I am looking for is a mechanism that will run an SQL query (actually a series of them) every morning at about 4am and cache the results, so that these queries don't run every time the page that contains them is loaded. 

    After carefully reading the cron documentation you link to here, I conclude that this plugin does NOT do that: the refresh and cron parameters only allow you to specify a time at which the cache is considered stale, or a time interval after which the cache is considered stale.

    The queries themselves are only triggered when the page is loaded and the cache mechanism determines that the cache defined on that page is stale.

    Am I right about this? Is there some way to flush these caches AND rerun the queries without loading the pages?   thanks, R.M.

    1. Your understanding is correct (smile). Here is what you need to do for pages that fall into this category:

      1. use refresh=1d or similar with an interval higher than your automation interval below
      2. have automation that runs continuously or just at night if you just have daily update requests
      3. automation uses Confluence Command Line Interface or Curl or similar to render the pages causing the cache to be refreshed
        • CLI example
          ... --action "renderRequest" --space "spacekey" --title "pagetitle" --requestParameters "refresh=true" --file ""
        • Curl example - use the page url and add "?refresh=true"
      4. our production site uses:
        • a database table, updated through Confluence, that has space, page title, and refresh intervals (examples: 15, 60, 120 in minutes, daily, weekly, monthly)
        • a continuously running (via Bamboo) groovy script that uses timer tasks and similar techniques to run the CLI request at configured intervals for each page

      At some point, I will publish a How to, but this comment should suffice for now.

      1. Wow, thanks for the quick reply!

        I have one follow-up question which I know is further off topic, so all I'm looking for is a yes or no answer: would there be a way to put a username and password into the URL (to pass via cURL) in a way Confluence would accept?

        thanks again, R.M.

        1. Probably similar to an example I have for accessing Atlassian Plugin Studio which does an explicit login action, save cookies, then do your render request using saved cookies.

  3. How does cache interact with the run macro? If i have a run macro wrapped around a long running sql and I wrap cache around the sql (inside the run), will the cache macro refresh if the values passed by run have changed?

    1. Yes! A simple test is watching the date change only when the input value changes:

  4. I'm having a weird problem with this plugin, not certain what I did wrong.

    I'm using a simple cache


    but it seems to only work for an individual user.  The user who refreshes the data sees everything just fine and it stays cached for them but anyone else who views the page gets no data, curiously the update timestamp is correct.  If user two refreshes the cache then they will now see the data and user one now will get nothing.  Odd thing is I went to check the oscache.properties but can not find that file.  I have reinstalled the plugin several times and have tried it on two different installations 2.10.3 using ver. 2.3.1 and 3.4.6 using ver. 4.1 and can not find the properties file.

    I'm sure I'm missing something simple, anyone out there want to help me feel dumb?  :)

    1. Investigating. The property file is only needed if you want to change the default behavior, so that is not the problem.

      I cannot reproduce the problem. Create an issue with the minimal page markup that shows the problem and we can discuss further there.

      1. Did a little more investigating and figured out my problem, will create an issue.

        I am using sql queries to generate some charts; it seems that having the chart macro inside the cache causes the chart itself to only display for the current user though having dataDisplay=true will result in the data table being cached properly for all users.  The reason I was doing it this way was to allow showRefresh=true and showDate=true as the chart will not render with those features enabled.

        {chart:title=Prior Day Prices|type=bar|dataDisplay=true|width=1200|height=600|legend=true|dataOrientation=vertical|
        from DAILY_MISSING_PRICE WHERE trunc(UPDATE_DATE) = decode(TO_CHAR(UPDATE_DATE, 'DY'), 'FRI', TRUNC(SYSDATE \-3), trunc(sysdate \-1))
        order by UPDATE_DATE

        If I put the chart outside the cache I get the following error:

        chart:  com.atlassian.renderer.v2.macro.MacroException:  org.dom4j.DocumentException: Error on line 3 of document  : Open quote  is expected for attribute "border" associated with an  element type   "img". Nested exception: Open quote is expected for attribute "border"  associated with an  element type  "img". [|http://njstaro:8080/display/SOM/Test+of+Cache?refresh=2] Tue Apr 26 15:19:41 EDT 2011
        1. Look at Page display performance tips and techniques and the part dealing with charts specifically. http://confluence.atlassian.com/download/attachments/8444/statistics.txt shows examples with cached charts. You need to have the chart macro save the chart as an attachment.

  5. When doing an HTML export of a page using the cache macro, I get a NullPointerException:

            at uk.ltd.getahead.dwr.WebContextFactory$ProxyWebContext.getHttpServletRequest(WebContextFactory.java:102)
            at org.randombits.confluence.support.DWRServletInfo.getRequest(DWRServletInfo.java:30)
            at org.randombits.confluence.support.ServletAssistant$2.fetch(ServletAssistant.java:48)
            at org.randombits.confluence.support.ServletAssistant.fetch(ServletAssistant.java:70)
            at org.randombits.confluence.support.ServletAssistant.getRequest(ServletAssistant.java:46)
            at org.randombits.confluence.support.PageInfo.getRequest(PageInfo.java:172)
            at org.randombits.confluence.support.PageInfo.getRequestAttributes(PageInfo.java:126)
            at org.swift.confluence.cache.CacheMacro.getUniqueId(CacheMacro.java:410)
            at org.swift.confluence.cache.CacheMacro.execute(CacheMacro.java:106)
            at org.randombits.confluence.support.ConfluenceMacro.execute(ConfluenceMacro.java:54)
            at com.atlassian.renderer.v2.macro.ResourceAwareMacroDecorator.execute(ResourceAwareMacroDecorator.java:51)
            at com.atlassian.renderer.v2.components.MacroRendererComponent.executeMacro(MacroRendererComponent.java:203)
            at com.atlassian.renderer.v2.components.MacroRendererComponent.processMacro(MacroRendererComponent.java:169)
            at com.atlassian.renderer.v2.components.MacroRendererComponent.makeMacro(MacroRendererComponent.java:67)
            at com.atlassian.renderer.v2.components.WikiContentRendererHandler.handleMacro(WikiContentRendererHandler.java:18)
            at com.atlassian.renderer.v2.WikiMarkupParser.makeMacro(WikiMarkupParser.java:120)
            at com.atlassian.renderer.v2.WikiMarkupParser.handlePotentialMacro(WikiMarkupParser.java:100)
            at com.atlassian.renderer.v2.WikiMarkupParser.parse(WikiMarkupParser.java:60)
            at com.atlassian.renderer.v2.components.MacroRendererComponent.render(MacroRendererComponent.java:46)
            at com.atlassian.renderer.v2.V2Renderer.render(V2Renderer.java:53)
            at com.atlassian.renderer.v2.plugin.PluggableV2Renderer.render(PluggableV2Renderer.java:30)
            at com.atlassian.renderer.v2.V2RendererFacade.convertWikiToXHtml(V2RendererFacade.java:57)
            at sun.reflect.GeneratedMethodAccessor508.invoke(Unknown Source)
            at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
            at java.lang.reflect.Method.invoke(Method.java:597)
            at org.springframework.aop.support.AopUtils.invokeJoinpointUsingReflection(AopUtils.java:304)
            at org.springframework.aop.framework.ReflectiveMethodInvocation.invokeJoinpoint(ReflectiveMethodInvocation.java:182)
            at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:149)
            at com.atlassian.spring.interceptors.SpringProfilingInterceptor.invoke(SpringProfilingInterceptor.java:16)
            at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:171)
            at org.springframework.transaction.interceptor.TransactionInterceptor.invoke(TransactionInterceptor.java:106)
            at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:171)
            at org.springframework.aop.framework.JdkDynamicAopProxy.invoke(JdkDynamicAopProxy.java:204)
            at $Proxy58.convertWikiToXHtml(Unknown Source)
            at com.atlassian.confluence.importexport.impl.WikiExporter.exportWikiToXHtml(WikiExporter.java:124)
            at com.atlassian.confluence.importexport.impl.WikiExporter.exportWikiToXHtml(WikiExporter.java:82)
            at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
            at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
            at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
            at java.lang.reflect.Method.invoke(Method.java:597)
            at org.apache.velocity.util.introspection.UberspectImpl$VelMethodImpl.doInvoke(UberspectImpl.java:389)
            at org.apache.velocity.util.introspection.UberspectImpl$VelMethodImpl.invoke(UberspectImpl.java:378)
            at com.atlassian.confluence.velocity.introspection.AnnotationBoxingMethod.invoke(AnnotationBoxingMethod.java:28)
            at com.atlassian.confluence.velocity.introspection.UnboxingMethod.invoke(UnboxingMethod.java:31)
            at org.apache.velocity.runtime.parser.node.ASTMethod.execute(ASTMethod.java:270)
            at org.apache.velocity.runtime.parser.node.ASTReference.execute(ASTReference.java:252)
            at org.apache.velocity.runtime.parser.node.ASTReference.render(ASTReference.java:332)
            at org.apache.velocity.runtime.parser.node.SimpleNode.render(SimpleNode.java:336)
            at org.apache.velocity.Template.merge(Template.java:328)
            at org.apache.velocity.Template.merge(Template.java:235)
            at com.atlassian.confluence.util.velocity.VelocityUtils.renderTemplateWithoutSwallowingErrors(VelocityUtils.java:62)
            at com.atlassian.confluence.util.velocity.VelocityUtils.renderTemplateWithoutSwallowingErrors(VelocityUtils.java:68)
            at com.atlassian.confluence.util.TemplateSupport.processTemplate(TemplateSupport.java:77)
            at com.atlassian.confluence.importexport.impl.HtmlExporter.doExportEntity(HtmlExporter.java:186)
            at com.atlassian.confluence.importexport.impl.HtmlExporter.exportPage(HtmlExporter.java:88)
            at com.atlassian.confluence.importexport.impl.HtmlExporter.exportSpace(HtmlExporter.java:100)
            at com.atlassian.confluence.importexport.impl.AbstractRendererExporterImpl.doExport(AbstractRendererExporterImpl.java:91)
            at com.atlassian.confluence.importexport.impl.HtmlExporter.doExport(HtmlExporter.java:32)
            at com.atlassian.confluence.importexport.DefaultImportExportManager.exportAs(DefaultImportExportManager.java:106)
            at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
            at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
            at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
            at java.lang.reflect.Method.invoke(Method.java:597)
            at org.springframework.aop.support.AopUtils.invokeJoinpointUsingReflection(AopUtils.java:304)
            at org.springframework.aop.framework.ReflectiveMethodInvocation.invokeJoinpoint(ReflectiveMethodInvocation.java:182)
            at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:149)

    I "fixed" this locally with a try-catch in CacheMacro.getUniqueId().

  6. Hi Bob,

    Have you had any experience with using cache with the latex macro? I would have thought this would be perfect with the LateX macro which often slows down page loading substantially. From my experimenting, it seems to work ok when the cache macro is wrapped around one latex macro call, but having 2 calls to the cache macro on the one page makes only one of the equations render. Any idea why? I've also tried caching a whole page with 60+ equations and it renders, but I'm not sure the load time is much improved. I suppose if LateX saved its png output as attachments like the chart macro did, then things might be different.

    cheers, Phil

    1. Sorry, I have no experience with the latex macro.

  7. Great plugin!

    I was able to get it to work with the Advanced Search Plugin by putting the 


    around the top and bottom of the page. I even have a lot of formatting in the between. I can't see any issues so far in my searches.


  8. Hi Bob,

    Did you test the compatability of Cache macro with Confluence 4.1? I install the Cache plugin through UPM and I cannot find it in "Insert macros".

    However, if I use insert it into "wikimarkup" macro it works. Is the macro worked in rich text editor?


    1. Yes, see Confluence 4.0 compatibility for Table and other plugins.

      1. Is the plugin set to appear in the macro browser? because I am not able to find it in macro browser nor when I type "{" in the rich text editor.

        1. When a 4.x specific version is released, then it will.

  9. Hi Bob,

    We tested the Cache plugin (version cache-plugin-4.1.5) on our Confluence 4.0 server (staging), and it seemed to have crashed the server. This happened right about the time I was saving (or viewing) a page that invoked the macro, with index=true. Our server admins haven't directly linked the two, but because they have had to rebuild the server, they want to steer clear of this plugin; however, this could solve one of our biggest problems: the inability to search content that has been included. Have you had any issues regarding the plugin bringing down the server? The compatibility table above suggests that 4.1.5 is compatible with 4.0.

    Thanks in advance,


  10. That is unlikely, but your admins have access to the confluence log and can look for any reported errors. Normally the cause of the failure can be found there. They can also open a atlassian support ticket on the server crash and send in the log data for analysis.

  11. Hi. Tested on Confluence 4.0, 4.2.1 and 4.2.4. The macro doesn't appear under Edit Page. Is the plugin compatible with them? If not what could be the issue?

  12. You will need to use insert wiki markup until a new release is available - see Confluence 4.0 compatibility for Table and other plugins

  13. Would this plugin work with Scaffolding Data? Would it help with generation of reports using content-reporter or local-reporter?

    1. Yes, it works with almost any way rendered data is produced.

  14. I tried to use the Cache Macro in combination with the Scaffolding plugin from CustomWare. The caching of the rendered scaffolding data works fine, but when I try to edit the scaffolding data using Edit Contents, it gives me the cached content instead of the usual Scaffolding form.

    It seems logical to me that the caching does not work in this situation because both the read-only view and Edit Contents view are rendered from the same page source.

    I wanted to check if my findings are correct. Can someone confirm that these two plugins don't work together?

    1. It use to work just fine, but I haven't tried that for a long time. Perhaps someone with more recent experience could chirp in?