How to bypass the caching mechanism for Jira Issues Macro in Confluence
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
When a page with a Jira Issue Macro is loaded, the response from Jira is stored in Confluence's cache.
This cache has a time to live (TTL) based on what is configured in <Confluence Base URL>/admin/jim/cachesettings.action. The default value is 5 minutes.
If the same Jira Issue Macro is loaded within this time, then Confluence will get the information from the cache instead of going to the Jira server.
If any issue from the target JQL changes within that interval, then you won't get the update in the Confluence page, since it will be relying on the cache.
Solution
There are several ways we can bypass the caching mechanism for the Jira Issues Macro:
Macro Refresh Button
The Confluence user may click on the Refresh button within the macro – this is not the browser's refresh button.
When that button is clicked, it will send the request directly to Jira and then update the Confluence cache with recent information.
Cache Parameter
The Jira Issues Macro has a configuration parameter on the macro level that tells Confluence to bypass the cache and always contact Jira when loading information.
This parameter is not available in the UI and can only be added or changed if editing the page with the Confluence Source Editor App.
As explained in Jira Issues Macro:
| Parameter name | Required | Default | Parameter description and accepted values |
|---|---|---|---|
| cache | No | on | The macro maintains a cache of the issues which result from the Jira query. If the 'cache' parameter is set to 'off', the relevant part of the cache is cleared each time the macro is reloaded. (The value 'false' also works and has the same effect as 'off'.) Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The macro browser does not offer this parameter. |
Example of the storage format for a Jira Macro with the cache parameter set to false:
<ac:structured-macro ac:macro-id="4cbe8338-d55c-4298-970e-76f699b326fd" ac:name="jira" ac:schema-version="1">
<ac:parameter ac:name="server">Jira</ac:parameter>
<ac:parameter ac:name="serverId">d0cc468a-9f3a-3e58-9252-9728b6f22732</ac:parameter>
<ac:parameter ac:name="key">TEST-1</ac:parameter>
<ac:parameter ac:name="cache">false</ac:parameter>
</ac:structured-macro>
Global Settings
If the Confluence Administrator is fine with bypassing the cache for all Jira Issues Macros within the Confluence instance, then the cache time to live can be set to 0 in <Confluence Base URL>/admin/jim/cachesettings.action.
Note that this can degrade Confluence and Jira performance since it will reach the Jira server through the network every time a Jira Issues Macro is loaded.
Any change on this page will require Confluence to be restarted so it uses the new value.