Issue Links

hasLinks([link name])

With no arguments searches for all issues that have any link.

With one argument, searches for issues that have the specified link. You need to provide the link name, for instance blocks, is blocked by, duplicates, is duplicated by. If you misspell it the validation error will give you a list of suitable link names.

issueFunction in hasLinks("blocks") and resolution is empty

hasLinkType

hasLinkType(link type)

Searches for issues that have the specified link type in either direction. You need to provide the link type, for instance Blockers, Duplicate, Clones. If you misspell it the validation error will give you a list of suitable link types.

issueFunction in hasLinkType("Blockers") and resolution is empty

These two are equivalent:

issueFunction in hasLinkType("Blockers")
issueFunction in hasLinks("blocks") OR issueFunction in hasLinks("is blocked by")

linkedIssuesOf

linkedIssuesOf(Subquery, [link name])


This is similar to parentsOf and subtasksOf, in that it will return the linked issues.

To find all the unresolved issues that are blocked by issues in the Open state you could use:

issueFunction in linkedIssuesOf("status = Open", "blocks") and resolution is empty

With no link name argument, will search for the linked issues whatever the link type:

issueFunction in linkedIssuesOf("resolution = unresolved")

epicsOf

Jira Agile users can query on epic links, eg find all Epics that have unresolved stories:

issueFunction in epicsOf("resolution = unresolved")

issuesInEpics

You can go the other way, e.g. find all stories for open epics in a project

issueFunction in issuesInEpics("project = SSPB and status = 'To Do'")

Find unresolved stories in resolved epics:

issueFunction in issuesInEpics("resolution is not empty") and resolution is empty

issuePickerField

When using the single or multiple link:script-fields/issue-picker.html[issue picker] fields, returns issues by a query on the linked issues.

issuePickerField(IssuePickerFieldName, [subquery])


So if you had an issue picker field named `Issue Picker`, to find issues that, through that field, link to an issue of type `Bug`, you would do;

issuePickerField('Issue Picker', 'issuetype = Bug')

The semantics of this are very similar as that of linkedIssueOf.


If you leave out the subquery argument, then this will give the same results as `'Issue Picker' is not empty`.

More Complex Examples

Find all the stories in an epic, and all their subtasks. With these complex queries it helps to break them down into pieces, so the first step is to find the stories of the epics in a particular project, let’s say the JRA project.

issuesInEpics("project = JRA")

Now save that as a filter, called for example, Stories in Epic.

subtasksOf

Now to query for their subtasks we can create a new filter, and do:

issuefunction in subtasksOf("filter = 'Stories in Epic'")

Don’t edit the Stories In Epic filter as you will cause a cyclical reference. Instead create a new filter.

Note this this now returns only the subtasks, whereas you want the subtasks and the stories. So we can put it all together to get:

filter = 'Stories in Epic' or issuefunction in subtasksOf("filter = 'Stories in Epic'")

If you also want issues linked to the stories, you can use:

filter = 'Stories in Epic' or
    issuefunction in subtasksOf("filter = 'Stories in Epic'") or
    issueFunction in linkedIssuesOf("filter = 'Stories in Epic'")


The linkedIssuesOf function takes an optional second parameter which is the link name, eg "blocks" or "is blocked by", so you can constrain the issues returned by that clause.

When working on complex queries bear in mind the following:

  • Clauses in a multiple clause query should be tested on their own to check they are returning what you want

  • If a subfilter gets complicated, save it as a filter and use filter = 'Filter Name'

  • You can use double and single quotes if necessary, so long as they are balanced. You cannot escape quotes, if you need to you will need to save as a filter.

linkedIssuesOfRecursive

linkedIssuesOfRecursive(Subquery, [Link name])

This is similar to linkedIssuesOf, in that it will return the linked issues, however this function traverses issue links recursively to return all issues that are linked (directly and indirectly) to the results of the initial subquery.

To find all direct and indirectly linked issues of an particular issue you can use:

issueFunction in linkedIssuesOfRecursive("issue = DEMO-1")


So if we have the following setup:

Then our query would return: DEMO-1, DEMO-2, DEMO-3, DEMO-4 and DEMO-5.

DEMO-1 is returned by the query above as it has "is blocked by" links from DEMO-2 and DEMO-3.

You can limit the type (and direction) of links that are traversed using the second parameter.

issueFunction in linkedIssuesOfRecursive("issue = DEMO-1", "blocks")


In this instance, if we use the example already mentioned, only DEMO-2, DEMO-3 and DEMO-4 will be returned.

The Link type parameter behaves exactly the same as the Link description parameter for linkedIssuesOf.

If you have 1000s of indirectly linked issues, traversal of all of the links will take a few seconds.

linkedIssuesOfRecursiveLimited

linkedIssuesOfRecursiveLimited(Subquery, Traversal depth, [Link name])

This function is exactly the same as linkedIssuesOfRecursive but it allows us to limit the depth of traversals along issue links that the function will do.

The following query will follow all links, recursively, from all issues in the DEMO project until it has traversed a maximum of 2 links deep along any link path.

issueFunction in linkedIssuesOfRecursiveLimited("project = DEMO", 2)


Using the following setup:

Our query with the depth parameter would return: DEMO-1, DEMO-2, TEST-1, TEST-2, TEST-4 and TEST-5.

We could specify the link name as well, to get different results:

issueFunction in linkedIssuesOfRecursiveLimited("issue = TEST-2", 3, "is blocked by")

which would return: TEST-3, TEST-6 and TEST-5

linkedIssuesOfAll, linkedIssuesOfAllRecursive, and linkedIssuesOfAllRecursiveLimited

These functions provide the old behaviour of the linkedIssuesOf…​ style functions, in that they include subtask and epic links when no link type is specified. Other than that, they function identically to their counterparts.

Remote Issue Links

linkedIssuesOfRemote

linkedIssuesOfRemote([Remote Link property], search term)

Find issues that link to remote content (for instance web pages, Confluence pages, or any other custom remote link type that you have set up). Two options are available: either specify against which remote link property to search or search against title and url.

Search term supports two wildcard characters:

  • * - matches zero or more characters. For example, he* will match any word starting with he, such as he, her, help, hello, helicopter, hello world, and so on

  • ? - matches exactly one character. For example, he? will only match three-letter words starting with he, such as hem, hen, and so on.

A primary use case for this is to find issues linking to a particular Confluence page. This allows you to show on your wiki page all the Jira issues that reference it (but see numerous caveats below). You can do this with either the Jira issues macro, or the Filter Results gadget. Note that the Jira issues macro has a cache, so if you are testing this you need to click the refresh icon on the Jira issues macro.

Examples

Searching by Link Properties

Remote Link properties supported: title, url, application name, application type, relationship, host, path, query.

Find all issues linked to a linked Confluence instance:

issueFunction in linkedIssuesOfRemote("application name", "Confluence")

Find all issues with a remote link to some Atlassian app (Confluence, Jira, Bamboo, Bitbucket, etc.):

issueFunction in linkedIssuesOfRemote("application type", "com.atlassian.*")

Find issues linked to a specific page id:

issueFunction in linkedIssuesOfRemote("query", "pageId=11469162")

Find issues linked to a specific web host:

issueFunction in linkedIssuesOfRemote("host", "www.stackoverflow.com")

Find issues linked to a path starting with a particular string:

issueFunction in linkedIssuesOfRemote("path", '/jira*')
issueFunction in linkedIssuesOfRemote("path", '/projects*')

By querying on the 'relationship' property, you can emulate the hasLinks function for links to a remote Jira instance.

issueFunction in linkedIssuesOfRemote("relationship", "mentioned in")
issueFunction in linkedIssuesOfRemote("relationship", "caused by")

Searching Against Title and URL


Find issues linked to a particular URL:

issueFunction in linkedIssuesOfRemote("http://www.acme.com/confluence/pages/viewpage.action?pageId=11469162")

Find issues linked to a particular title (with some wildcards):

issueFunction in linkedIssuesOfRemote("title wildcard* m?tch")

Warnings and Issues

For Confluence pages the title is always Wiki Page - so you can’t search on the Confluence page title.

For Confluence pages the URL is always the one with viewpage.action?pageId in - you can get the pageId by clicking Edit and copying it out of Confluence. A Confluence macro would save having to do this. Alternatively just click through on the remote link from the Jira issue.

Adding a remote link to an issue does not reindex the issue - the function won’t find it until it’s indexed. Make an edit or do any action on the issue to get it reindexed.

In order to prevent extremely slow WildcardQueries, a search term may not start with one of the wildcards * or ?

Find any issue that has a remote link of any kind.

issueFunction in hasRemoteLinks()

This query could be slow in instances with a large number of projects and issues, since it is an alias for linkedIssuesOfRemote('*').

On this page