JIRA Chart Macro
If your Confluence site is connected to a JIRA application, you can display issues as charts on Confluence pages. You can connect Confluence to any JIRA application, including JIRA Software and JIRA Service Desk.
Before you can use this macro, your Confluence and JIRA applications must be connected via Application Links. People viewing the page will see charts for publicly accessible issues. If your JIRA application has restricted viewing (that is, people need permission to view issues) then they'll need to authenticate before seeing the charts. This macro is compatible with JIRA 5.x and later.
On this page:
Adding the JIRA Chart macro to a page
To add a JIRA chart to your page:
- In the editor choose Insert > Other macros > JIRA Chart.
- Choose the type of report you want to create (for example Pie, Created vs Resolved)
Select your JIRA server.
If you have multiple JIRA servers linked to Confluence the drop down will default to the primary application link.- Search for issues - you can enter the query in JQL or paste a JIRA URL directly into the search field.
- Choose Preview to generate the chart.
- Choose Display Options to further control how your chart appears.
- Choose Insert.
To find out more about searching for issues see Displaying issues using JIRA Query Language (JQL).
Screenshot: The JIRA Chart Macro in the macro browser
Pie chart
Pie charts can be used to report on issue status, priority, assignee and more.
To further control how this chart appears on your page. Choose Display options:
- Chart by - select the field you want to segment the pie chart by such as:
- Status
- Fix version
- Assignee name
- Priority
- Component
- Issue type
- Width - define the total width of the chart area. You can enter values in pixels, percent or leave blank to auto fit.
- Show border - add a border around the chart area.
- Show chart information - include a text summary under the chart with the total issues count and chart by value.
Created vs Resolved chart
Created vs Resolved charts can be used to show the difference between the number of issues created versus the number of issues resolved over time.
To further control how this chart appears on your page choose Display options:
- Period - choose a time frame to report by (week, month, quarter etc).
- Days previously - the total number of days to report on (counting back from today).
- Cumulative totals - choose to progressively add totals or report individual values for each period.
- Show unresolved trend - add a subplot showing unresolved issues over time.
- Show versions - indicate version release dates as a vertical line on the chart.
- Width - define the total width of the chart area. Enter values in pixels, percent or leave blank to auto fit.
- Show border - add a border around the chart area
- Show chart information - include a text summary under the chart with the total issues count and chart by value.
Two Dimensional Chart
Two Dimensional Charts can be used to show issue statistics in a matrix. You can configure the X and Y axes to display these issue fields:
- Status
- Priority
- Assignee
- Fix version
- Component
- Issue type.
For example you could use the chart to show issue types by status (as shown above).
To configure the chart axes choose Display options:
- X Axis - the issue field to display on the X axis (columns).
- Y Axis - the issue field to display on the Y axis (rows).
- Rows to display - the maximum number to display in the chart.
Disabling the JIRA Chart macro
The functionality is provided by an add-on (plugin) called 'JIRA Macros'. This macro is also used for the JIRA Issues macro. To make the macro unavailable on your site, you can disable the add-on. See Disabling and enabling apps.
Notes
HTTPS: The JIRA Chart macro can access a JIRA site running under SSL provided the Confluence server is configured to accept the JIRA SSL certificate. See Connecting to LDAP or JIRA applications or Other Services via SSL.
Authentication: If the query includes issues that require authentication (issues that are not visible to anonymous users in JIRA), users will be prompted to authenticate to view charts on the Confluence page.
In order to search for issues in the macro browser you may need to authenticate. With JIRA 5.x you will be able to search for unrestricted issues as an anonymous user, however with JIRA 6.x you must be authenticated to search for any issues.
Code examples
The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page.
Macro name: jirachart
Macro body: None.
The following parameters are available in storage format. Note that some parameters are only available for specific chart types.
Parameter name | Chart type | Required | Default | Parameter description and accepted values |
|---|---|---|---|---|
| all | Yes | Pie | Type of chart to display. Chart types include:
|
showinfor | all | No | False | Displays text information about the data below the chart. Includes the Total value and the Chart By value. |
jql | all | Yes | JQL query for the chart to display. | |
width | all | 600 | (blank) | This is the total width of the chart area. Width can be entered in pixels, percent or left blank to fit to the available space. |
border | all | No | False | Displays a border around the chart area. |
statType | pie | Yes | Statuses | The JIRA field to segment the pie chart by:
|
periodName | createdvsresolved | Yes | Time frame to report by. Options are There is a limit to the number of days the report can generate for each period. For example you can report hourly for a maximum of ten days, and report daily for a maximum of 300 days. | |
daysprevious | createdvsresolved | Yes | False | Number of days, counting backwards from today, to include in the report. Note that maximum days limits might apply depending on the Period you have chosen. |
isCumulative | createdvsresolved | No | False | If true, the chart will progressively add data. If false the chart will show individual values for each period. |
showUnresolvedTrend | createdvsresolved | No | False | Include a subplot showing unresolved issues trend. |
versionLabel | createdvsresolved | No | None | Indicate version release dates with a vertical line. Values include major, all and none. |
xstattype |
| Yes | Status | JIRA field for the X axis (columns) of the chart. These are the same issue fields that are available in the |
ystattype | twodimensional | Yes | Assignee | JIRA field for the Y axis (rows) of the chart. These are the same issue fields that are available in the |
numberToShow | twodimensional | No | 5 | Maximum number of rows to include in the chart. |
Storage format example - Pie Chart
Example chart by Issue Type - note that Confluence will insert the server and serverId parameters, based on settings in Application Links:
<ac:structured-macro ac:name="jirachart">
<ac:parameter ac:name="chartType">pie</ac:parameter>
<ac:parameter ac:name="statType">issuetype</ac:parameter>
<ac:parameter ac:name="showinfor">true</ac:parameter>
<ac:parameter ac:name="jql">project%20%3D%20CONF%20and%20fixVersion%20in%20('5.3')</ac:parameter>
<ac:parameter ac:name="width">600</ac:parameter>
<ac:parameter ac:name="server">JAC</ac:parameter>
<ac:parameter ac:name="serverId">144880e9-a353-312f-9412-e5028e8166fa</ac:parameter>
<ac:parameter ac:name="border">true</ac:parameter>
</ac:structured-macro>Storage format example - Created vs Resolved
Example chart - note that Confluence will insert the server and serverId parameters, based on settings in Application Links:
<p><ac:structured-macro ac:name="jirachart">
<ac:parameter ac:name="isAuthenticated">true</ac:parameter>
<ac:parameter ac:name="versionLabel">all</ac:parameter>
<ac:parameter ac:name="jql">project%20%3D%20confluence%20and%20component%20%3D%20documentation</ac:parameter>
<ac:parameter ac:name="showUnresolvedTrend">true</ac:parameter>
<ac:parameter ac:name="width">450</ac:parameter>
<ac:parameter ac:name="daysprevious">30</ac:parameter>
<ac:parameter ac:name="isCumulative">true</ac:parameter>
<ac:parameter ac:name="chartType">createdvsresolved</ac:parameter>
<ac:parameter ac:name="showinfor">false</ac:parameter>
<ac:parameter ac:name="server">JAC</ac:parameter>
<ac:parameter ac:name="serverId">144880e9-a353-312f-9412-e5028e8166fa</ac:parameter>
<ac:parameter ac:name="border">true</ac:parameter>
<ac:parameter ac:name="periodName">daily</ac:parameter>
</ac:structured-macro></p>Storage format example - Two Dimensional Chart
Example chart - note that Confluence will insert the server and serverId parameters, based on settings in Application Links:
<ac:structured-macro ac:name="jirachart">
<ac:parameter ac:name="chartType">twodimensional</ac:parameter>
<ac:parameter ac:name="ystattype">issuetype</ac:parameter>
<ac:parameter ac:name="sortBy" />
<ac:parameter ac:name="isAuthenticated">true</ac:parameter>
<ac:parameter ac:name="jql">project%20%3D%20CONF%20and%20Component%20%3D%20Documentation</ac:parameter>
<ac:parameter ac:name="width" /><ac:parameter ac:name="server">JAC</ac:parameter>
<ac:parameter ac:name="numberToShow">10</ac:parameter>
<ac:parameter ac:name="sortDirection" />
<ac:parameter ac:name="serverId">144880e9-a353-312f-9412-ed528e8166fa</ac:parameter>
<ac:parameter ac:name="xstattype">statuses</ac:parameter>
</ac:structured-macro>