Issue Checker guide

The full reference: where to find it, what every part of the screen means, and every setting.

What it is · Where you find it · What it tells you · Opening a check · The bar above the list · Dismissing a finding, and putting it back · The thirty-four checks · Choosing which checks run, and in what order · What your columns mean · What to include · Writing your own check · Where your choices are kept · When Jira cannot answer everything · What it cannot do

What it is

Issue Checker reads a Jira project's issues and tells you what is wrong with them: fields nobody filled in, dates that contradict each other, work that is blocked by something that cannot happen first, and estimates that do not add up.

It is a separate app from Project Commander. It never changes anything in Jira. It asks for no permission to write, of any kind, so that is something you can check on the permission list before you install rather than something we ask you to take on trust.

Thirty-four checks run, in five groups, plus any check you write yourself.

Where you find it

Inside a project. Open the project and choose Issue Checker from the row of tabs under the project's name. Jira puts apps under More at the end of that row, so open that first. There is nothing to set up: Jira tells the app which project the page was opened from, and the checks run.

On a dashboard. Add the Issue Checker gadget to a Jira dashboard. A dashboard belongs to a person rather than to a project, so here the gadget has to be told which project to read. It asks in its own header: a dropdown labelled Project, on the line under the name. Change it there and the checks run again straight away; the choice of sprints under What to include starts again from every sprint, because the new project has sprints of its own.

Two gadgets on one dashboard can watch two different projects. The project is remembered for you against that one gadget; everything else you choose is remembered for you against the project.

As an app. Open Issue Checker from Jira's Apps menu, on a page of its own.

What it tells you

The headline is one line saying what the whole list amounts to: 12 issues need attention · 9 of 34 checks found something · 3 new · 5 fixed.

The number counts issues, not findings. One issue with no epic and no due date is found by two checks and is still one issue that needs attention. New and fixed are compared with the last time you looked, so on a first look neither is shown, and after that each appears only when it is not zero.

When nothing is found at all it reads Nothing to fix · 34 checks, all clear.

Every check is listed, whether or not it found anything. A check that found nothing shows a green dot and a zero. This is deliberate: a check that found nothing and a check that never ran must never look the same, or the list is not worth trusting.

Every check says what it means. A small ? sits after the count on each row; rest on it and it tells you what that check looks for and why it matters. A check with nothing to explain still draws the mark's place, so the marks and counts line up down the list.

The groups, in this order, each with the number of issues in it beside the heading:

A check always stays in its own group, so a heading always describes everything underneath it.

Opening a check

Click any row and the issues behind the count appear under it, each by key, with its summary and a short note saying why it was found. Click a key to open that issue in Jira. A check that found nothing says Nothing to list.

Six are listed. If there are more, the last line reads and 4 more in Jira →, which opens a Jira search holding all of them.

A dependency loop is drawn as the loop rather than as a list — every key in it joined by arrows, first key equal to last — because the shape is the thing you need to see.

The bar above the list

Show only found issues is a checkbox. Ticked, every check that found nothing drops out of the list. The counts on the group headings do not change when you hide the quiet checks — you are hiding rows, not changing numbers. The choice is remembered for next time.

Expand all and Collapse all sit beside it. Expand all opens what is on screen, so with the checkbox ticked it opens only the checks that found something.

Dismissing a finding, and putting it back

Every finding inside an opened check carries a Dismiss button — including a dependency loop, which carries it on the line with the loop. Dismissing takes it off its check. The headline counts issues, not findings, so it drops by one only when that was the issue's last finding; an issue another check still finds stays in the headline.

A folded Dismissed section sits at the top of the list at all times, directly under the bar, with its count in brackets after the word — Dismissed (0) when you have dismissed nothing, so you can always see that it looked. Open it and each line names the issue and which check found it — a key on its own does not tell you what you set aside. Restore puts one back; Bring them all back puts back all of them, and the section then reads Dismissed (0) rather than disappearing.

What you dismiss is yours alone, on that project. Nobody else looking at the same project sees your decision.

The thirty-four checks

Dependencies (5)

Something missing (7)

Dates and sprints that disagree (5)

Estimates (14)

The first eight, and Resolved, with time still on it, say nothing at all on a project that does not track time. The other five read how Jira settled the work — its resolution and the date of it — and run on any project.

Looks finished, is not (3)

Nine of the thirty-four are the same checks Project Commander's Alerts tab runs, asked of the same engine rather than written again here. A rule written twice drifts apart, and somebody using both products would then read two different accounts of the same project.

Choosing which checks run, and in what order

The settings open from the gear (⚙) at the right of the name, on a dashboard gadget and on the app's own page, even before a project is chosen - choices saved then are your starting choices for any project that has none of its own. The page inside a project has no settings of its own; it uses the choices you last saved for that project. Nothing in the settings takes effect until you press Save; Cancel puts back what was there.

In the settings, every check is listed under its group with a checkbox. Turning one off takes it off the list and out of every count.

Drag a check by its handle (⋮⋮) to move it within its group. It cannot leave its group, so a heading never comes to stand above something it does not describe. Dragging a check also sets How it reads to the dragged order.

Under How it reads, choose Most found first, which puts the checks that found the most at the top of each group, or The order you drag them into (the default). The groups themselves always stay in their usual order.

All of this is yours alone and changes nothing for anybody else looking at the same project.

What your columns mean

Jira sorts every status into not started, in progress or finished, and on nearly every board it is right. Where it is wrong it is wrong in one direction: a column like "Ready for release" or "Awaiting sign-off" that Jira counts as finished while your team does not, or a "Blocked" column Jira counts as in progress when nothing is happening in it.

So you can say, column by column, which group it really belongs to. Your word wins; Jira's own grouping answers for every column you have not named. There are four to choose from:

Waiting on something is a fourth group Jira does not have. Work in it is not finished and nobody is moving it, and saying so is the point — it is what the check "Waiting, and its date has passed" is built on.

Leave a column as Jira has it unless Jira has it wrong. Changing one changes what every check says.

The columns offered here are the ones seen the last time the checks ran, because the settings screen never reads the project itself.

What to include

Every sprint the project's issues sit in is listed with its state, each with a tick. Left alone, every sprint is ticked and every one is checked, closed ones included. Once you untick one, the checks look at every sprint that is not closed, less the ones you unticked. Include backlog, ticked by default, adds everything not in a sprint.

Writing your own check

Under Your own checks, give it a name (the box reads Name) and a Jira filter written the way you would write it in Jira's own search box (the box reads Jira filter (JQL)). Test puts the filter to Jira and says either ✓ Valid — N issues match right now, or why Jira refused it. Add check can be pressed only once a name is given and Jira has accepted the filter. Each check you have added is listed with its filter beside it and a × that removes it.

That catches a filter Jira rejects. It cannot catch one that is merely asking the wrong question.

Your own checks appear at the foot of the list, under their own heading, and are counted in the headline like any other.

Where your choices are kept

Which checks run, their order, what each column means, what to include, the checks you wrote and what you have dismissed are all kept per person and per project, inside your own Atlassian site. Two people looking at the same project can have completely different lists, and neither changes the other's.

The project a dashboard gadget reads is the exception: that is kept for you against the gadget itself, so two gadgets on one dashboard can read two different projects.

Nothing is sent outside Atlassian, by this app, ever.

When Jira cannot answer everything

"Carried over more than once" needs each issue's history, and on a large project Jira may not return all of it in the time allowed. When that happens the app says so under the headline, and that check counts only what it managed to read. An issue whose history did not come back is left out of the count rather than reported as having moved none — "nobody looked" must never be shown as "nothing found".

What it cannot do

It cannot change anything in Jira. There is no write permission in the app at all.

It reads issues and their links, which sprint an issue is in and whether that sprint has closed, the project, and — for a check you wrote — the filter you gave it. It stores your own choices. That is the whole list, and it is on the app's own permission screen before you install.