Velocity Chart for Jira — Documentation

• Scrum boards, company- and team-managed, in projects you can browse in Jira; the picker reads the first 200 boards of the site. Team-managed boards are tagged “team-managed”.
• With more than 7 boards a search box filters by board name, project name or project key. Ticked boards stay visible while you search.
• Classic Kanban boards have no sprints and are not listed. A team-managed Kanban board may be listed but shows no closed sprints.
• New boards appear immediately; the picker is not cached.

Done only (top: 26.3 points, 81% say/do) and Done plus Ready for release (bottom: 29.4 points, 90% say/do).

• Issues without a value count as 0, except with Issue count.
• Without Pro the gadget uses the board's setting: its estimation field, or the issue count when the board estimates by issue count.
• Sub-tasks are left out unless you tick Include sub-tasks.

• Issues added after the start count toward Completed when they are done, but not toward Committed. Say/do can therefore be above 100%. This also holds for issues created directly in the running sprint and for issues that were removed before the start and added again afterwards. An issue added within one second after the start still counts as committed.
• Issues removed from the sprint before it closed are not counted at all, so Committed is lower when scope was removed mid-sprint. Jira's own report counts them as committed, so this is a difference to it.
• “Done” means the same at the start, when an issue is added and at the close: your Count as “Done” statuses (Pro), otherwise the board's Done column.
• Later estimate changes do not rewrite past sprints: committed uses the estimate from the start of the sprint, completed the one from its close. If Jira cannot deliver the full history in time, the chart uses current values and says “could not read the full sprint history”; click Refresh.
• Sprints that several boards share: each board counts only the issues of its own saved filter. If Jira does not return the board's configuration (after one retry), the chart shows an error with the cause instead of an unfiltered chart.
• The latest sprints are chosen by close date from all closed sprints of the board. If the list cannot be read completely, the chart shows an error instead of older sprints.
• Up to 200 issues are read per sprint.
• Results are cached for up to 5 minutes; Refresh recalculates right away. Your permissions are checked on every load, also when the numbers come from the cache (who sees which numbers).

• Keyboard: tab to the chart, move between sprints with the arrow keys, open with Enter or Space, close with Esc. Hover a bar or a label in the list for an explanation.
• In narrow gadgets and widgets the details of each issue move under its title; long lists scroll inside the panel.
• The list opens without asking Jira again; only the titles are loaded when you open it. If they cannot be loaded, the list stays complete and Retry loads them again.
• Without an active subscription, a click on a sprint shows the sprint's totals and a note that the details are part of Pro.

• The app reads the sprint as the app, then asks Jira for every load which of these issues you may browse (project permission and issue security level) and adds up only those. The answer is never cached.
• The 5-minute cache holds the sprint data of the board for everyone (issue IDs, keys, estimates and statuses, no titles and no people); it is filtered for each viewer before anything is shown.
• The hidden-issues line counts each issue once, also when it was carried over from one sprint to the next; the sprint details count it in every sprint it belongs to.
• An issue whose security level does not include Velocity Chart (Jira lists installed apps in the project role atlassian-addons-project-access) cannot be read by the app at all, so it is counted for nobody, also not for people who may open it, and the bars can be lower than in Jira's own velocity report. The line under the chart says how many such issues the sprints shown hold, never which ones. To include them, a Jira admin adds that project role to the security level (Project settings → Issue security); if the app may not browse the whole project, give the role the Browse Projects permission as well.
• The count is made for every load as you: one Jira search over the sprints shown (issue IDs and issue type only), and, only if it finds issues the cached sprint data lacks, the same search as the app. It belongs to you alone, is never cached or stored and does not change the numbers. If Jira does not answer in time, the line is left out without an error.
• After a Jira admin changes permissions or a security level, Jira can take a few minutes to apply the change everywhere, also in its own velocity report. Reload the dashboard after that.
• If Jira does not answer the permission check in time, the chart counts only the issues it could check and says “Velocity Chart could not check issue permissions; numbers may be incomplete”. Click Refresh after a moment.

• Count as “Done” lists the statuses of the first ticked board; the ticked names apply to every board.
• When you tick a fifth board, the first ticked board in the list is unticked.
• Velocity depends on each team's own estimation scale, so use it to follow trends rather than to rank teams.
• Without an active subscription a gadget with several boards shows only the first one.

The board has no completed sprint yet. Start and complete a sprint, or pick a board that already has closed sprints. Classic Kanban boards have no sprints and are not listed.

Your issues are estimated in a different field than the board's default. Open the gadget's Edit view, go to Estimation and choose the field your team actually uses (for example Story point estimate), or switch to Issue count. Estimation, Done statuses and sub-task handling are Pro settings.

Only Scrum boards (company- and team-managed) in projects you can browse are listed, taken from the first 200 boards of the site. Classic Kanban boards are excluded because they have no sprints. New boards appear immediately.

The gadget only shows boards whose project you can browse in Jira, so ask your Jira admin for access to the board's project. The message can also appear for a board you can open if Jira did not answer the check, for example during a short outage. Reload the dashboard after a couple of minutes and the app checks again.

Each person sees only the issues they can open in Jira. When a sprint holds issues of a project, or with a security level, that one of you cannot open, those issues are left out for that person, as in Jira's own velocity chart. The line “N issues hidden” under the chart tells you that this applies to you. See who sees which numbers.

Jira did not answer the permission check for your issues in time, usually a short rate limit or outage. The chart then counts only issues whose check went through, so nothing you may not see is shown, and the numbers can be lower than usual. Click Refresh after a moment. If it keeps happening, ask your Jira admin to check that Velocity Chart is installed and has access to Jira.

The board's estimation field is empty for some issues in the sprints shown, so Velocity Chart takes their estimate from the standard Story Points field instead. Jira's own velocity report counts 0 for these issues, so your bars can be higher than in Jira. The note names both fields and the affected sprints. To match Jira, fill the board's field or change the board's estimation setting to the field your team uses. The note appears only when such an estimate is actually counted.

Velocity Chart reads the sprints as an app. Jira hides an issue from it when the issue's security level does not include the project role atlassian-addons-project-access, the role Jira uses for installed apps. Such issues are counted for nobody, so the bars can be lower than in Jira's own velocity report. Only people who can open the issues see the note, with the number but never which issues. To include them, a Jira admin adds that project role to the security level (Project settings → Issue security). If the app may not browse the whole project, give the role the Browse Projects permission too. Jira can take a few minutes to apply the change.

Jira did not return the board's configuration (the message names the HTTP status), usually a short rate limit or outage. The app needs it to apply the board's saved filter, so it shows an error instead of a chart that could include issues of other boards. It already retried once. Click Refresh after a minute and check that the board opens in Jira. A similar message says the board's saved filter was not found: check in the board settings that the filter still exists.

Jira did not answer the request, usually a short rate limit or outage. Nothing is cached for such a result, so click Refresh or reload the dashboard after a minute.

Results are cached for up to five minutes. Click Refresh in the gadget to recalculate right away.

Only as committed. Completed counts the issues that were done when the sprint closed, as in Jira's own velocity report. An issue that was carried over unfinished counts as completed only in the sprint in which it was finished. An issue that was already done when it joined a sprint counts in neither bar.

Velocity Chart follows the same counting rules: committed is what was in the sprint at the start and not done then, completed is what was done when the sprint closed, with the estimates from those two moments. Differences remain when you choose your own Done statuses or estimation field (Pro), when issues were removed from a sprint before it closed (Jira counts them as committed, the app cannot see them), when the board's estimation field is empty for some issues (Jira counts 0, the app uses the Story Points field) and when an issue security level hides issues from the app (see above).

Jira's report lives on the board's Reports page and uses that board's own Done column and estimation setting. Velocity Chart is a dashboard gadget: you choose which statuses count as Done and how to estimate, can chart up to four boards in one gadget, click a sprint to see the issues behind its bars, and get an average say/do ratio and CSV/SVG export (Pro).

Yes. Team-managed Scrum boards appear in the board picker tagged “team-managed” and use the same calculation as company-managed boards.

No. Velocity Chart is strictly read-only and requests no write permissions. It only reads sprint data to draw the chart and keeps a short-lived cache of it in Atlassian Forge Storage (issue IDs, keys, estimates and statuses; no titles, no people). See the Privacy Policy and the Security Policy.