Setup & User Guide

Bespoke Charts & Reports for Confluence and Jira · Last updated 14/09/2026 · Applies to the current Marketplace release

This guide walks a Confluence admin through installing Bespoke, and walks every user through the one-time Connect to Jira step, building a chart, and what viewers see. Nothing here needs an API key, a settings page, or any configuration outside the macro itself.

1. Before you start

Bespoke is a Confluence macro that charts live Jira data. Check these four things once:

• Confluence Cloud and Jira Cloud on the same Atlassian site. Both products must live under the same site URL (for example yourcompany.atlassian.net). Bespoke reads Jira from that same site; it cannot chart a different Jira site.
• Confluence admin permission to install. Installing any Marketplace app needs a Confluence or site admin. Everything after installation works without admin rights.
• Jira product access for everyone who builds or views charts. Bespoke reads Jira as the person looking at the page. Someone with no Jira access on the site sees a Connect to Jira card instead of a chart (see §9).
• Something to chart. A Jira project, a saved filter you can see, or a JQL search that returns work items.

2. Install from the Atlassian Marketplace (admin)

1. Open the Bespoke listing on the Atlassian Marketplace and click Get it now.

   You must be signed in as a Confluence admin (or site admin) for the site you want to install on.

2. Choose the Confluence site, then confirm.

   Atlassian shows the app's permissions before you confirm. Bespoke asks for exactly two read-only Jira scopes: read:jira-work and read:jira-user. It requests no write, admin, storage, or external-network permissions.

3. Start the free trial (paid tiers only).

   Sites with up to 10 users are free with no trial needed. Larger sites start a 30-day free trial automatically; billing is handled entirely by the Atlassian Marketplace.

4. Connect the app to Jira (admin, one time per site).

   Bespoke's home is Confluence, and it reads Jira through a site-level connection an admin approves once. If the install flow offered to connect Jira and you accepted, you are done. Otherwise: open Atlassian Administration (admin.atlassian.com) → choose your site → Connected apps → find Bespoke Charts & Reports → View app details → Connections tab → on the Jira Apps row click Connect, review the permissions panel, and click Connect again. The row now reads Connected. (From Confluence, Settings (⚙) → Apps → Manage apps → Take me there opens the same Connected apps page.)

5. Done. There is nothing else to configure.

   Any Confluence user who can edit a page can now insert the macro. There is no settings page and no API key.

3. Connect to Jira (one time per person)

Bespoke never reads Jira with an app-level account. It reads Jira as you, so every chart is limited to the work items you can already see in Jira. Atlassian requires each person to approve that once. Here is exactly what happens the first time you use the app:

1. Insert the macro (or open a page that already has a chart).

   In the chart editor, a banner at the top reads "Connect to Jira so this chart can read your work items." On a published page, the chart shows a card titled "Couldn't load this chart" with the line "Connect to Jira to see this chart." Both carry a Connect to Jira button.

2. Click Connect to Jira.

   Atlassian opens its standard app-permission dialog. It names the app and lists the two read-only Jira scopes it will use on your behalf.

3. Click Allow access.

   The banner disappears, the editor loads your Jira fields, and the preview or chart renders. If the dialog does not appear, check that your browser is not blocking pop-ups for atlassian.net, then click Connect to Jira again.

4. That's it. You will not be asked again on this site.

   The approval is remembered for your account. Every other person who builds or views a Bespoke chart on the site goes through the same one-time step, which is how the app guarantees nobody ever sees a colleague's restricted work items.

4. Build your first chart

1. Edit a Confluence page and insert Bespoke Jira Chart.

   Place your cursor where the chart should go, type / and choose Bespoke Jira Chart, or use the + insert menu. A fullscreen chart editor opens.

2. Connect to Jira if prompted.

   First time only, per person. See §3.

3. Pick a Source in the toolbar.

   Choose Project, Saved filter, Custom JQL, Project type, or Project category. Project and filter pickers search as you type, so there are no IDs to remember. Custom JQL autocompletes fields, operators, and values, and shows a green Valid JQL check or Jira's own error message. Details in §5.

4. Pick a chart Type: Pie, Donut, Bar, Stacked, or KPI.

   Then pick a Chart by field (any field, including custom fields, via a searchable picker). Stacked bars also take a Stack by field. KPI needs no field at all. The live preview in the middle of the editor updates a moment after each change.

5. Adjust options in the right-hand rail.

   Title, how many groups to show before the rest roll into Other, legend and data-label toggles, a color per group, chart height, and Compact spacing. Details in §7.

6. Click Save chart, then publish the page.

   The chart now renders live for every viewer, rebuilt from Jira on each page load and filtered to that viewer's own permissions.

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 from the list.
Saved filter	Whatever the filter's current JQL returns. Editing the filter in Jira updates every chart built on it.	Start typing the filter name and choose it. You can only pick filters that are shared with you.
Custom JQL	Any Jira Query Language search, for example project = ABC AND statusCategory != Done.	Type in the JQL box. Fields, operators, and values autocomplete from your site; 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 dropdown.
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, e.g. work items by status.	Chart by
Donut	Same as Pie, with the total count in the center.	Chart by
Bar	Comparing counts across groups. Largest first.	Chart by
Stacked (stacked bar)	Comparing groups while breaking each one down by a second field, e.g. status stacked by assignee.	Chart by + Stack by
KPI	One large number: how many work items match the search right now.	None

All chart types are count-based: the app counts matching work items per group. It does not sum story points, time, or other numeric fields. Work items with no value in the Chart by field are counted in a None group, shown last.

7. Options, colors, 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: toggles.
• Colors: once your search returns results, a swatch appears per group. The default palette is colorblind-checked; click any swatch to change that group's color.
• Chart height: Small, Medium, or Large.
• Compact spacing: trims the padding around the chart so several charts fit side by side in Confluence page columns.

8. Edit, copy, or remove a chart

• Edit: in page edit mode, click the chart and choose Edit from its macro toolbar (or double-click it). The same editor reopens with your saved settings.
• Copy: copy and paste the macro like any other Confluence content, including to another page. Its configuration (source, chart type, grouping, colors) travels with it.
• Remove: delete the macro from the page. Because Bespoke stores nothing outside the page, nothing else needs cleaning up.

9. What every viewer sees

1. First visit: a one-time Connect to Jira card.

   A person who has never used Bespoke on the site sees a card reading "Connect to Jira to see this chart." They click Connect to Jira, then Allow access, and the chart renders. They are not asked again (§3).

2. Each viewer's own Jira permissions apply.

   The chart re-runs its search as the viewer on every page load. Two people looking at the same chart can see different totals and segments if their Jira project permissions differ. Nobody sees data they could not already see in Jira.

3. No Jira access, no data.

   Someone with no Jira product access on the site keeps seeing the Connect to Jira card rather than a chart or an error. They never see another person's numbers.

4. Always current.

   Every page load re-runs the search, so the chart reflects Jira right now. There is no snapshot to refresh.

10. Permissions and data handling

• Scopes: read:jira-work and read:jira-user only. Both read-only.
• How data is read: on the viewer's behalf, with the viewer's own Jira permissions, after the viewer's one-time Allow access. There is no app-level or shared access mode.
• Storage: none. Jira data is aggregated in memory and discarded after each render. The chart's configuration lives in the Confluence page's own macro parameters, stored by Atlassian like any other page content.
• External egress: none. No analytics, telemetry, AI, or third-party calls. The only network calls are to Atlassian's own Jira REST API inside Forge.

Full detail: Privacy policy and Security information.

11. Limits

Limit	Value
Work items scanned per chart	5,000. If a search matches more, the chart is built from the first 5,000 and shows a note with a Refresh button.
Aggregation	Count only. No sums or averages of numeric fields.
Groups shown before rollup	First 10 by count (configurable 1 to 50); the rest combine into Other.
Chart types	Pie, Donut, Bar, Stacked bar, KPI.
Scope of a chart	One chart is one search. No space-level rollups or trend-over-time views.

12. Troubleshooting

What you see	What it means	What to do
Banner: "Connect to Jira so this chart can read your work items." (in the editor) or card: "Couldn't load this chart" — Connect to Jira to see this chart. (on the page)	You have not yet granted the app permission to read Jira as you, or you have no Jira access on this site.	Click Connect to Jira, then Allow access. If the card stays after allowing access (or no dialog appears), the app is not yet connected to Jira at the site level: ask an admin to do §2, step 4 (Atlassian Administration → Connected apps → Bespoke → Connections → Jira Apps → Connect). Also confirm you have Jira product access on this same site. Still stuck? Email support@taskhooker.com with your site URL.
"Configure this chart" — Edit this macro to pick a work item search and a chart type.	The macro was inserted but never saved with a source.	Edit the macro, pick a source and chart type, and click Save chart.
"No work items found"	The search returns zero results for the current viewer.	Check the search in Jira directly or widen it. Two viewers can get different results (§9).
"Couldn't load this chart" — There's a problem with the search behind this chart.	The JQL is invalid. Jira's own error text appears under the message.	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 the viewer is not shared on it.	Recreate or share the filter, or point the macro at a different source.
"Couldn't load this chart" — This chart isn't configured correctly.	The saved configuration is invalid or from an incompatible version.	Edit the macro and save it again.
"Couldn't load this chart" — Something went wrong while loading this chart.	A temporary problem talking to Jira.	Click Try again. If it persists, check Jira's status page.
"Showing the first 5,000 matching work items."	The search matches more than 5,000 work items.	Informational. Narrow the search, or click Refresh to re-run it.
A group you expect is missing and its work items land under None	Some app-provided or unusual custom field types cannot be read for grouping yet.	Group by a different field, or email support with the field name.

13. Uninstall

A Confluence admin removes the app from Confluence → Settings (⚙) → Apps → Manage apps. Existing macros on pages stop rendering. Because the app stores nothing of its own, there is no data to delete; chart configurations remain in page content as inert macro parameters until you remove the macros.

14. Support

• Email: support@taskhooker.com
• Privacy: bespoke.taskhooker.com/privacy · Security: bespoke.taskhooker.com/security
• Vendor: Taskhooker, Melbourne, Australia · taskhooker.com