ConfluenceLinkLens for Confluence

How do I show the blocked work items in a Jira release on a Confluence page?

By Mortise Apps · 19 October 2026 · 4 min read

To show which work items in a Jira release are blocked, add the Jira work items macro to the release page (type /jira while editing), switch the search to JQL, and enter fixVersion = "2.4" AND workItemLinkType = "is blocked by" AND statusCategory != Done, with your version name in place of 2.4. The list then holds every unfinished work item in that release that has at least one "is blocked by" link. It does not show the blockers themselves, whether they are still open, or what blocks them in turn. For those questions you need one more macro per item, or a graph.

Checked 19 Oct 2026: Atlassian Support's "JQL fields" page (Work item link type, Fix version) and "JQL functions" page (unreleasedVersions()), both read 19 Oct 2026, and "Display Jira work items in a list" (the Confluence macro), read 14 Oct 2026. We have not run these queries on a live site for this article; the syntax is quoted from those pages.

The query, piece by piece

Variants worth knowing:

• Every unreleased version of a space: fixVersion in unreleasedVersions(ABC) AND workItemLinkType = "is blocked by". The unreleasedVersions() function only works with IN and NOT IN.
• The next release only: fixVersion = earliestUnreleasedVersion(ABC) in place of the version name, so the page follows along when a release ships.
• The opposite list, work in the release with no blockers: workItemLinkType != "is blocked by", also from Atlassian's examples.
• Just a number for a status table: the same query with COUNT VIEW selected in the macro.

The link type is written as the link's description, so the direction matters: "blocks" finds the work items that block something, "is blocked by" the ones being blocked. Older filters use the field name issueLinkType; Atlassian's page now calls it workItemLinkType. Use whichever name your site's JQL autocomplete offers.

Adding it to the release page

From Atlassian's "Display Jira work items in a list": insert the macro, pick JQL instead of BASIC, enter the query and select Insert work items. Add the columns that matter for a release check (Status, Assignee, Priority) with the column icon. Because the macro is a saved search, the list updates as links and statuses change; nobody has to edit the page.

What this list cannot tell you

• Which work item is the blocker. The query returns the blocked items, not what they are waiting on. To see the blockers of one item, add a second macro with issue in linkedWorkItems(ABC-123, "is blocked by") (our walkthrough), one per item.
• Whether the blocker is still open. The field matches on the link. Nothing in Atlassian's description of it filters on the status of the work item at the other end, so expect an item to stay in the list after its blocker is done, until someone removes the link.
• Chains. If a blocker is itself blocked, or the blocker sits in another release or another space, the list does not show it.
• This site only. The same page says remote links to work items on other Jira sites are not included.

For a small release, the list plus one linkedWorkItems() macro per blocked item is a usable readiness page, and it needs no app.

When the release page needs the whole picture

When the question is "what is blocking this release, and what is blocking that", a list per item gets long. LinkLens for Confluence, which we make, is a macro that draws Jira link chains as a graph on the page. Pick the link type (Blocks, or any link type on your site) and a JQL scope such as fixVersion = "2.4"; chains are laid out left to right, linked work items outside the scope appear dimmed, and a loop is drawn in red and listed under the graph. It reads Jira live as the person viewing the page, so each reader sees only what their Jira permissions allow, and it does not change any links.

Its limits: one link type per macro, and it follows links one hop outside the scope, so a blocker two steps outside the release is not drawn. Setup is in the getting-started guide and the app is on the Atlassian Marketplace. For a whole project's map, see How to put a Jira dependency map in a Confluence page; for one epic, see this epic walkthrough.

FAQ

Can I list the blockers of a whole release with one native query?

Not with the documented functions. linkedWorkItems() takes one work item key, not a query, so "everything that blocks anything in version 2.4" cannot be written as one JQL search. workItemLinkType gives you the blocked side only.

Does the list update by itself?

Yes. The macro runs its JQL search when the page is viewed, so new links and status changes show up without editing the page.

Why does a work item stay in the list after its blocker is done?

The query looks for the link type, not the blocker's status. Remove or change the link in Jira once the blocker no longer applies, or check the blocker's status with a linkedWorkItems() macro.