What's Blocked, and by What? Portfolio Dependency Queries for Jira PMOs

Many of the teams that rely on Argon are PMOs: program managers, delivery leads, the people who own a plan that spans several Jira projects. The searches they run most aren't the exotic ones. They follow links and the hierarchy: what is blocked, what is blocking it, what is related, and where in the plan it all sits.

In the last weeks before a launch, the question every morning is the same: what is waiting on unfinished work, what is holding it up, and what changed since yesterday? Plain JQL can't answer that in one search. This post shows the handful of Argon queries that can, and how they fit next to the portfolio tool you already plan in.

Why plain JQL stops short

Jira knows every link and every parent. What JQL can't do is follow them from the results of another search:

• issue in linkedIssues("PLAT-7") lists what is linked to one issue you name. It can't start from “every unfinished issue in the launch”.
• issueLinkType = "is blocked by" finds every issue that has a blocking link, including the ones whose blocker was finished weeks ago.
• parent in (PLAT-1, WEB-2) lists the children of the epics you type in. It can't tell you which epics have trouble underneath.
• On Jira Premium, portfolioChildIssuesOf("PORT-4") lists everything under one issue. Again, one key that you name.

The missing piece is a subquery: start from every issue that matches this search, then follow its links, or go up or down the hierarchy. That is what Argon adds.

Four functions, two directions

Argon has two link functions and two hierarchy functions. Each takes an ordinary JQL query in quotes (the inner query) and returns the issues one step away from its results.

• linksQuery("…") follows links forward: the issues the inner query's results point at. For a “blocks” link, that's the work they hold up.
• linkedByQuery("…") follows links backward: the issues that point at the inner query's results. For a “blocks” link, that's the work holding them up.
• childrenOf("…") goes one level down: stories under epics, sub-tasks under stories, epics under initiatives.
• parentOf("…") goes one level up.

The two link names are easy to mix up, so check them against the picture: if PLAT-7 blocks WEB-31, linksQuery("key = PLAT-7") returns WEB-31, and linkedByQuery("key = WEB-31") returns PLAT-7.

The morning queries

The examples use a launch spread over three projects: PLAT (platform), WEB (website) and LEGAL. Swap in your own projects, a label or a fix version.

1. What is blocked by unfinished work

Read it from the inside out. The inner query is every unfinished issue in the launch. linksQuery follows their links forward to the work they hold up. The last two lines keep what is itself unfinished and has a blocking link.

An issue whose only blocker is done drops out, and that is the difference from issueLinkType on its own. In the picture at the top, three items wait on unfinished work. The Cookie policy doesn't: the Press kit it waited on is done.

2. What to chase first

Same inner query, other direction: unfinished work that other unfinished work is waiting on. These are the items to raise in the standup. In the example, that's Usage-based billing, which holds up two website items, and the Pricing calculator, which holds up Legal.

Add AND assignee is EMPTY and you get the worst kind: blockers nobody owns.

3. Blocked work inside the launch's epics

Projects are rarely a clean boundary for a launch. If the launch is a set of epics, scope by the hierarchy instead:

childrenOf returns every story under the tagged epics, whichever project it lives in. The second line keeps the ones waiting on unfinished work.

4. Which epics are in trouble

Turn the list around and ask for the parents of the blocked work:

One function inside another. The inner part is the blocked list from query 1, and parentOf lifts it to the epics it belongs to. Mind the quotes: the outer function takes double quotes, the nested one single quotes.

Wrap the whole thing in one more parentOf and you are at the initiative level, if your plan has one. Levels above epic need Jira Premium.

5. Who else this epic touches

Every issue in another project that is linked to a story in the Billing epic, in either direction. Run it before a scope change: these are the teams to tell. It uses both functions because “relates to” links point whichever way the person who created them clicked.

Two things to get right

Link types. Argon's link functions follow every link type: blocks, relates to, duplicates, clones. That is what you want for related work (query 5). For the blocked and blocking lists, narrow with Jira's own issueLinkType, as queries 1 and 2 do. It checks the issue, not the specific link: an issue whose blocker is done but which also “relates to” unfinished work can still show up.

Scope the inner query. Each inner query can match up to 1,000 issues. “Everything not done” across a whole Jira site is usually more than that, and Argon will ask you to narrow it. Scope it to the launch's projects, a label, a fix version or the children of its epics. That is the answer a PMO wants anyway: the launch's blockers, not the whole company's.

Watch it every morning

A query you have to remember to run doesn't help much in launch week. Jira already has the pieces to bring it to you:

• Save each query as a filter: “Blocked”, “Blockers to chase”, “Epics in trouble”.
• Put them on a dashboard with the Filter results gadget, so the whole team looks at the same lists.
• Subscribe to the filters. Jira emails the results on a schedule, for example every weekday morning, to you or to a group.

For “what changed since yesterday”, keep a copy of the blockers filter with AND status CHANGED AFTER -1d on the end: the blockers that moved since yesterday, and nothing else.

Where Argon fits next to your PPM tool

Argon isn't a portfolio tool. It doesn't draw timelines, plan capacity or score projects. Jira Plans, Structure, BigPicture and the Gantt and portfolio apps from our partner DevSamurai do that. Where they show dependencies, they show them against dates. In Jira Plans, for example, a dependency is an issue link drawn as a line between two bars, and it turns red when the dates don't fit.

That answers “will the dates work?”. A PMO also needs a plain list: what is waiting on unfinished work today, whatever the timeline says. That is the question Argon answers, about the same issues. There are two ways to tie them together.

Ask about exactly the plan's issues. Most PPM tools build their scope from projects, boards or a saved filter. If yours uses a saved filter, put it straight into the inner query with Jira's own filter =:

The blocked list and the plan now cover the same work. If the tool scopes by projects instead, use the same project list, as the queries above do.

Feed an Argon filter into the tool. Jira Plans can take a saved filter as a source, Structure builds rows from a JQL query, and BigPicture boxes can take saved filters. Before Jira runs a search, it replaces each Argon function with plain JQL that Argon worked out, so to Jira a filter that uses Argon is a filter like any other. That lets you build, say, a structure of just the launch's blocked work. None of these tools document other apps' JQL functions either way, so try it on a small filter first.

Jira Align is the exception: it syncs with Jira through its connector, by projects and boards rather than JQL. There, run Argon in Jira over the same projects.

The same questions on monday.com

We have watched PMOs ask these questions in Jira for long enough that we built them into our first monday.com app. Advanced Search for monday.com follows dependencies, connected items and subitems across every board, and its watchlists tell you each morning what is newly blocked and what no longer is. It is coming soon to the monday.com marketplace.

Try it on your own launch

Install Argon, paste query 1 with your own projects, and see what your launch is waiting on. The JQL cheat sheet has the rest of Argon's functions on one page.

— Bartek, Orbiscend