The Approvals Nobody Should Be Reminded About

[#1]

If you automate reminders, escalations or reports around JSM approvals, you probably start with approvals = pending(). It sounds definitive: Jira says an approval is pending, so someone must be waiting to answer. On a mature site, that is not always true. The query can find work nobody should chase, while other requests can appear pending without giving your automation enough information to act.

This came up in a support case last week. An IAM manager at a financial-services company had set up approval reminders for an IT operations project and received no reminders. The answer lay in the site's migration history. Jira still held approval data, but some of it no longer described live work.

Three ways "pending" isn't really pending

1. Resolved requests can still look pending. During a migration into JSM, a request can be closed without its approval step ever being completed. Jira then holds two facts at once: the request is Done, but its approval field still says pending. approvals = pending() will continue to find it. If your automation trusts that clause alone, it can remind real people about work that is already closed. Add the status category to the query:

approvals = pending() AND statusCategory != Done

2. A blank Request Type can make the approval unreadable. Requests created by an integration, brought across in a migration or created directly in Jira can have no Customer Request Type. Jira search can still match their pending approvals, but the service desk API will not return the approval details to an app. The app can see that something is waiting without being able to see who it is waiting for.

The admin fix is pleasantly dull: bulk-edit a Request Type onto those requests. The lesson for anyone building on the API is more important. Treat this as a known unreadable state and explain it to the admin; do not turn it into an empty screen.

One scope note: Atlassian's “Submitting approval” KB documents a different failure, caused by group membership changing while an approval is in progress. It does not document the blank-Request-Type behaviour described here.

3. Some genuine pending approvals should still be left alone. This one is not a Jira defect. A mature site may have a sandbox form, an integration queue or a legacy backlog that should not generate reminders. Those approvals really are pending; your team has simply decided they are outside the reminder process. That exclusion belongs in the query.

Narrowing safely: a small JQL trap worth knowing

The safe way to narrow a base query is to join it to the extra condition with AND, with each side in parentheses:

(your base criteria) AND (labels != no-nudge)

As long as the added condition stays inside its parentheses, it can only remove results from the base query. It cannot add work the base query would not have found.

The trap is operator precedence: JQL evaluates AND before OR. Suppose a script inserts the unbalanced fragment foo) OR (bar into (base) AND (fragment). The finished query becomes (base) AND (foo) OR (bar). Because AND is evaluated first, that means (base AND foo) OR bar. Anything matching bar can now enter the results without matching base at all. A filter intended to narrow the scan has silently widened it, potentially across the whole site.

The finished query is syntactically balanced, so checking only after concatenation misses the escape. Validate the fragment itself first: its parentheses and quotes must balance before you compose it into a larger query. If it fails, reject it rather than trying to repair it.

Whatever does the scanning should show its work

Two habits make these failures much easier to spot:

• Run the exact query yourself. Before trusting an automation, paste the JQL it actually runs into Jira's issue search. If the tool will not show you that query, you have already found a problem.
• Make exclusions visible. “No results” could mean the base query found nothing, or that an extra filter excluded everything it found. Those are different outcomes and should be reported differently. A saved filter can also become invalid later if, for example, someone deletes a field it uses. That is an error to surface, not an empty result to shrug at.

Where this landed in our product

Disclosure, as always in this series: I build Approval Nudge, and this case shaped releases 3.11 and 3.12.

In 3.11, resolved requests stopped being scanned. When unreadable requests have a blank Request Type, the app now shows a banner that gives the number affected and points the admin to the bulk-edit fix.

In 3.12, the settings page began stating the base scan criteria. The Advanced edition also gained one JQL condition per project. The condition is composed as shown above and validated before it is saved. The active filter is always shown on the settings page and the Approvals Overview, and when a scan finds nothing because the filter excluded the candidates, the result says what the filter excluded. An admin should never have to guess what an automated reminder is looking at.

The JQL and the two checks above are useful whether you use Approval Nudge, another app or your own automation. If you have found a different kind of phantom pending approval, I would genuinely like to hear about it. The last one changed my roadmap.