Issue Links

hasLinks

Find all issues on your instance with links.

hasLinks()

Optionally, you can use the first argument to specify the link type. 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.

hasLinks([link name])

As well as link type, you can specify the number of that link type. For example, you want to search for issues with two or more blocks links.

issueFunction in hasLinks([link name], [number of links])

Examples

As a project manager I want to keep track of all issues that are blocking other work. To do this I want to set up a filter to show me all the issues with blocks links so I can keep an eye on their progress. 

hasLinks("blocks")

I want to see issues with more than 2 blocks links.

hasLinks("blocks", "+2")

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")

You can search for multiple links:

issueFunction in linkedIssuesOf("", "is part of", "is child of")

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 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')

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'")

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.

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.

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.

You can follow multiple links. For example from the diagram above:

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

will return DEMO-2, DEMO-3, DEMO-4 and DEMO-5.

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.

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 (this cannot be used for Confluence pages):

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

Warnings and Issues

For Confluence pages the URL is always the one with viewpage.action?pageId in - you can get the pageId as described in the Atlassian documentation. 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 ?

hasRemoteLinks

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('*').