Documentation

Last updated 03/11/2026. Chartsmith is a Confluence Cloud app that puts live charts of Jira data on Confluence pages. This guide walks an admin through installing it and connecting Jira, and walks every user through the one-time Allow access step, building a chart and what viewers see.

1. Before you start

Confluence Cloud and Jira Cloud on the same Atlassian site (the same site address, for example yourcompany.atlassian.net). Chartsmith charts Jira data from that same site.
A Confluence or site admin to install the app and connect it to Jira once. Everything after that works without admin rights.
Jira product access for everyone who builds or views charts. Chartsmith shows each person the Jira data they are allowed to see.
Something to chart: a Jira project, a saved filter shared with you, or a JQL search that returns work items.

Two one-time approvals, nothing else: an admin connects Chartsmith to Jira once per site (section 2), and each person clicks Allow access once (section 3). There is no settings page and no API key.

2. Install and connect Jira (admin)

Sign in as a Confluence admin or site admin. In Confluence, open Settings (⚙) → Apps → Find new apps, or open the Atlassian Marketplace website. Chartsmith is coming soon to the Marketplace.
Search for Chartsmith, open Chartsmith - Charts for Confluence with Jira Data and choose Get it now (or start the free trial).
Choose your Confluence site and review the permissions. Chartsmith asks for two read-only Jira permissions: read work items and read user names. It asks for no write permissions. Confirm.
Sites with up to 10 users are free. Larger sites start a 30-day free trial; billing is handled by the Atlassian Marketplace.
Connect Chartsmith to Jira (once per site). If the install offered to connect Jira and you accepted, skip to step 6. Otherwise open Atlassian Administration (admin.atlassian.com) → choose your site → Connected apps → Chartsmith → View app details → Connections tab. On the Jira Apps row choose Connect, review the permissions panel and choose Connect again. The row now reads Connected.
Done. Anyone who can edit a Confluence page can now insert a chart.

If step 5 is skipped, people keep seeing a Connect to Jira card even after they click Allow access, or no permission dialog appears at all. The fix is the site connection in step 5, not anything on the user's side.

3. Allow access (once per person)

Chartsmith reads Jira as you, so every chart only ever shows work items you can already see in Jira. Atlassian asks each person to approve that once.

Insert the macro, or open a page that already has a chart.
In the chart editor a banner reads "Connect to Jira so this chart can read your work items." On a published page the chart shows a card, "Couldn't load this chart", with the line "Connect to Jira to see this chart." Both have a Connect to Jira button.
Choose Connect to Jira. Atlassian's standard permission dialog opens and names the app and its read-only Jira access.
Choose Allow access. The banner disappears, your Jira fields load and the chart appears.
That's it. You are not asked again on this site. You can revoke the access at any time from your Atlassian account's connected apps page.

If no dialog appears, a notice under the button reads "No permission dialog appeared? This app isn't connected to Jira on your site yet…" with a How to connect link back to section 2. Ask your admin to complete step 5.

4. Build your first chart

Edit a Confluence page and place your cursor where the chart should go.
Type /Chartsmith Jira Chart and press Enter, or choose Chartsmith Jira Chart from the + insert menu. A full-screen chart editor opens.
Allow access if prompted (first time only, section 3).
Pick a Source: Project, Saved filter, Custom JQL, Project type or Project category (section 5).
Pick a chart Type: Pie, Donut, Bar, Stacked or KPI, then a Chart by field. Stacked bars also take a Stack by field. KPI needs no field.
Adjust the options in the right-hand panel: title, how many groups to show, legend, data labels, colors, height and spacing (section 7). The live preview updates a moment after each change.
Choose Save chart, then publish the page. The chart is now live for every viewer.

5. Data sources

Source	What it charts	How you pick it
Project	Every work item in one Jira project.	Start typing the project name or key and choose it.
Saved filter	Whatever the filter returns right now. Editing the filter in Jira updates every chart built on it.	Start typing the filter name and choose it. Only filters shared with you are listed.
Custom JQL	Any Jira search, for example `project = ABC AND statusCategory != Done`.	Type in the JQL box. Fields, operators and values autocomplete; a green Valid JQL check or Jira's own error message appears under the box.
Project type	Every Software, Service management or Business project on the site at once.	Choose the type from the list.
Project category	Every project in a Jira project category.	Start typing the category name and choose it.

6. Chart types

Type	Best for	Fields needed
Pie	Share of a whole across one field, for example work items by status.	Chart by
Donut	The same as Pie, with the total count in the center.	Chart by
Bar	Comparing counts across groups, largest first.	Chart by
Stacked bar	Comparing groups while breaking each one down by a second field, for example status stacked by assignee.	Chart by and Stack by
KPI	One large number: how many work items match the search right now.	None

Every chart counts matching work items per group. It does not sum story points, time or other number fields. Work items with no value in the Chart by field are counted in a None group, shown last.

7. Options, colors and size

Title: shown above the chart on the page. Optional.
Show top: how many groups to show before the rest are combined into Other. 1 to 50, default 10.
Show legend and Show data labels: on or off.
Colors: once your search returns results, a swatch appears for each group. The default palette is colorblind-checked; select any swatch to change that group's color.
Chart height: Small, Medium or Large.
Compact spacing: trims the space around the chart so several charts fit side by side in Confluence page columns.

Hovering over a slice or bar on the page shows its count and percentage.

8. Edit, copy or remove a chart

Edit: in page edit mode, select the chart and choose Edit from its toolbar (or double-click it). The editor reopens with your saved settings.
Copy: copy and paste the macro like any other Confluence content, including to another page. Its settings travel with it.
Remove: delete the macro from the page. Chartsmith keeps nothing outside the page, so there is nothing else to clean up.

9. What every viewer sees

First visit: a one-time Connect to Jira card. The viewer chooses Connect to Jira, then Allow access, and the chart appears (section 3).
Their own Jira permissions: the chart is built from the work items that viewer can see. Two people can see different totals on the same chart. Nobody sees data they could not already open in Jira.
No Jira access, no data: someone without Jira product access on the site keeps seeing the Connect to Jira card, never another person's numbers.
Always current: each time the page opens, the chart reflects Jira right now. There is no snapshot to refresh.

10. Permissions and your data

Permissions: read Jira work items and read Jira user names. Both read-only. Chartsmith cannot change anything in Jira.
Whose access: each person's own, after their one-time Allow access. There is no shared or admin-level view of your data.
Storage: none. Chartsmith keeps no copy of your Jira data. A chart's settings are saved with the Confluence page like any other page content.
Nothing leaves Atlassian: no outside servers, analytics, tracking, AI or third parties. Chartsmith is eligible for Runs on Atlassian.

Full detail: Privacy and Security.

11. Limits

Limit	Value
Work items per chart	5,000. If a search matches more, the chart uses the first 5,000 and shows a note with a Refresh button.
What is measured	Counts of work items. No sums or averages of number fields.
Groups shown before Other	10 by default, adjustable from 1 to 50.
Chart types	Pie, Donut, Bar, Stacked bar, KPI.
Scope of a chart	One chart is one search. No space-wide rollups or trend-over-time charts.

12. Messages and fixes

What you see	What it means	What to do
"Connect to Jira so this chart can read your work items." (editor) or "Couldn't load this chart - Connect to Jira to see this chart." (page)	You have not allowed access yet, or you have no Jira access on this site.	Choose Connect to Jira, then Allow access. If the card stays, or no dialog appears, ask an admin to complete section 2, step 5, and check you have Jira access on the same site.
"Configure this chart"	The macro was inserted but never saved with a source.	Edit the macro, pick a source and chart type, and choose Save chart.
"No work items found"	The search returns nothing for you right now.	Check the search in Jira or widen it. Two viewers can get different results.
"Couldn't load this chart - There's a problem with the search behind this chart."	The JQL is not valid. Jira's own message is shown underneath.	Fix the JQL in Jira's search screen, then update the macro.
"Couldn't load this chart - The saved filter behind this chart is unavailable."	The filter was deleted, or it is not shared with you.	Share or recreate the filter, or choose a different source.
"Couldn't load this chart - This chart isn't configured correctly."	The saved settings are incomplete or out of date.	Edit the macro and save it again.
"Couldn't load this chart - Something went wrong while loading this chart."	A temporary problem reaching Jira.	Choose Try again. If it continues, check Atlassian's status page.
"Showing the first 5,000 matching work items."	The search matches more than 5,000 work items.	For information only. Narrow the search, or choose Refresh.
A group you expect is missing and its work items are under None	A few app-provided or unusual custom field types can't be used for grouping yet.	Group by a different field, or tell us the field name through support.

13. Uninstall

A Confluence admin opens Settings (⚙) → Apps → Manage apps.
Find Chartsmith and choose Uninstall.
Charts on pages stop showing. Chartsmith keeps no data of its own, so there is nothing to delete; remove the macros from pages whenever you like.

14. Get help

Support portal: Wattlebrooks Apps support
Email: support@wattlebrooks.com
More: Support · Privacy · Security