← Readout
DocumentationPrivacyEULASupport

Readout documentation

Get started

  1. Install Readout from the Atlassian Marketplace (Jira admin). Every site gets a 30-day free trial. After that it is $6 a month for up to 10 users, then billed per user.
  2. Open a Jira dashboard and add a gadget (on the new Jira dashboards: add a widget). Search for "KPI". Readout adds four:
    • KPI Gauge (Readout)
    • KPI Number (Readout)
    • KPI Target (Readout)
    • KPI Bar Chart (Readout)
  3. A new gadget says "Edit this gadget to choose a saved filter or JQL". Open its settings, pick a saved filter or type JQL, and save.

Readout works on both the classic Jira dashboards and the new Jira dashboards. On the new dashboards the settings open in the dashboard's edit panel, changes show in the widget as you make them, and the dashboard's own Save keeps them. On classic dashboards, click Save at the bottom of the settings.

Classic Jira dashboards and their gadgets stop working on 17 May 2027, when Atlassian retires them. Before then, add the widget to a new Jira dashboard and pick the same settings.

Choosing the issues

Under Issues, choose:

  • Saved filter: type part of a filter's name in Find a filter by name, or paste its link or number. Your starred filters show first, marked with a star. You can also paste a filter link or its number. The gadget keeps a reference to the filter, so later edits to the filter flow through.
  • JQL: type any JQL and click Check JQL to have Jira validate it. Any ORDER BY clause is ignored.

If you paste a filter that isn't shared with you, Readout says so and suggests asking its owner to share it.

Measure

Pick Count of issues, or Sum of, Average of, Minimum of or Maximum of a number field. Number fields include custom number fields such as story points, and time tracking fields, which are shown in hours.

For the Gauge, Number and Target gadgets, Show as a percentage of these issues turns the value into a share. Enter the Part to measure (JQL added to the issues above), for example statusCategory = Done, click Check, and give it a Label such as "Done". The gadget then shows the percentage and "x of y Done".

The four gadgets

KPI Gauge

A speedometer with color zones. Set Gauge minimum and Gauge maximum (0 to 100 by default; these are hidden when you show a percentage).

KPI Number

One big number. Options:

  • Target: shown under the number.
  • Compare with: No comparison, Yesterday, 7 days ago, 14 days ago or 30 days ago. The gadget shows the change since that day and a small trend line. Trends are kept per person: each viewer's history starts the first time they view the gadget, which shows "Trend starts building today".

KPI Target

Progress toward a goal as a bar with a target marker. With a percentage it shows "x of y" and the target percentage; with a plain value it shows how far you are as a percentage of the Target.

KPI Bar Chart

Issues grouped by any field. Under Bars:

  • Group by: system fields (Status, Status category, Assignee, Priority, Work type, Project, Labels, Components, Fix versions, Resolution, Sprint, Created, Resolved, Due date and others) and custom fields, marked "(custom)", including select lists, cascading selects (shown as "Parent / Child"), numbers and dates.
  • Period: for date fields, Day, Week, Month, Quarter or Year. Periods are in date order and empty periods show as zero.
  • Stack by (optional): a second field, with a legend.
  • Direction: Horizontal bars or Columns.
  • Order: Largest first, Smallest first, A to Z, or Jira order (for example workflow order for statuses).
  • Most bars shown: 3 to 50. The rest are combined into "Other".
  • Bar color.
  • Show issues with no value, Show percentages, and Color bars by the thresholds below.

Bars only include values that appear on the matched issues, so you never see empty options from other projects or "N/A". People show as display names.

Click through to the issues

Click any number, gauge, target, bar or stacked segment to open Jira's issue search with JQL that returns exactly the issues it counts. "Other" is clickable too, except for fields where one issue can have several values (labels, components, multi-selects, sprints). Open issues in a new tab controls whether this opens in a new tab.

Targets and colors

  • Which way is good?: Higher is better (red, then yellow, then green) or Lower is better (green, then yellow, then red), for example for open bugs or SLA breaches.
  • Yellow from and Green from (or Red from when lower is better). Leave both empty for a single color.

Display

  • Title shown in the gadget (up to 80 characters) and Footer text (up to 200), for example to explain what the number means.
  • Prefix and Suffix, such as "$" or " pts".
  • Decimals: 0 to 4.
  • Short numbers (1.2k).
  • Refresh on wallboards: Off (use the dashboard refresh), or every 5, 10, 15 or 30 minutes, or every hour.

The settings screen shows a live Preview.

Who sees what

Every gadget runs as the person viewing the dashboard. Issues they can't see are never counted, so two people can see different numbers on the same dashboard.

Messages you might see

  • Partial result: a sum, average or bar chart over more than 10,000 issues reads the first 10,000 and says so. Narrow the filter for an exact value.
  • About this many: counts above 20,000 use Jira's estimate.
  • A deleted or unshared filter, a deleted number or grouping field, or invalid JQL: the gadget says what is wrong and how to fix it, instead of spinning.

Licensing and trials

Readout is paid through Atlassian, with a 30-day free trial. If the license is not active, gadgets show "The Readout license for this site is not active" instead of data, and the settings screen shows the same notice. Your gadget settings are kept and work again as soon as the license is renewed in Apps > Manage your apps.

Permissions and data

  • Readout runs on Atlassian's Forge platform. It has read-only access to Jira, no external network permissions, and sends nothing outside Atlassian.
  • Gadget settings are stored by Jira with the dashboard. Readout itself stores only the per-viewer trend points for Number gadgets (one value per day, kept for 90 days) and whether you dismissed the review prompt.
  • The gallery previews on the new dashboards use built-in sample data and don't read your Jira.

Limits and known gaps

  • Sums, averages and bar charts read up to 10,000 issues per refresh; exact counts go up to 20,000.
  • Issues with several values in the grouped field are counted once per value.
  • Trends are per viewer and start on first view.
  • Dashboard-level filters on the new Jira dashboards are not applied to Readout widgets yet.

FAQ

I can't find my filter in the picker. Type any part of its name, or paste its link or number. Starred filters show first.

Can I click a gauge or bar to see the issues? Yes. Every value, bar and segment opens exactly the issues it counts.

Can it show something other than issue counts? Yes: sum, average, minimum or maximum of any number field, including story points and time spent in hours.

Can I chart by week or month? Yes. Group by any date field per day, week, month, quarter or year.

Can colors go the other way for targets like "fewer is better"? Yes: choose Lower is better.

Does it work on wallboards? Yes. Set Refresh on wallboards and the gadget refreshes on its own. Errors show as text, not an endless spinner.

Why use this instead of the charts on the new Jira dashboards? Readout takes any saved filter or JQL, groups and sums by custom fields, adds gauges, single numbers and targets with thresholds, and opens the exact issues behind every value. It works on classic and new dashboards.

Uninstalling and your data

When the app is uninstalled, the gadgets stop showing and Atlassian deletes Readout's stored trend data for your site.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing) or email hello@greatwork.company. First response within 1 business day.