Issue Links
hasLinks
Find all issues on your instance with links.
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.
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.
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.
I want to see issues with more than 2 blocks links.
hasLinkType
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.
These two are equivalent:
linkedIssuesOf
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:
With no link name argument, will search for the linked issues whatever the link type:
You can search for multiple links:
epicsOf
Jira Agile users can query on epic links, eg find all Epics that have unresolved stories:
issuesInEpics
You can go the other way, e.g. find all stories for open epics in a project
Find unresolved stories in resolved epics:
issuePickerField
When using the single or multiple issue picker fields, returns issues by a query on the linked issues.
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;
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.
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:
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:
If you also want issues linked to the stories, you can use:
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
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:
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.
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:
will return DEMO-2, DEMO-3, DEMO-4 and DEMO-5.
If you have 1000s of indirectly linked issues, traversal of all of the links will take a few seconds.
linkedIssuesOfRecursiveLimited
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.
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:
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
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:
Find all issues with a remote link to some Atlassian app (Confluence, Jira, Bamboo, Bitbucket, etc.):
Find issues linked to a specific page id:
Find issues linked to a specific web host:
Find issues linked to a path starting with a particular string:
By querying on the 'relationship' property, you can emulate the hasLinks function for links to a remote Jira instance.
Searching Against Title and URL
Find issues linked to a particular URL:
Find issues linked to a particular title with some wildcards (this cannot be used for Confluence pages):
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 ?
The linkedIssueOfRemote function can only search over the properties of a RemoteIssueLink Object from the Jira API, so there are limits to what can be used to search for linked issues and how. Unfortunately this means that you can't search by Confluence space or multiple pages (within the same function call). When searching by pages in Confluence, the page title is always returned as wiki page, or page by the Jira API, and results in not being able to use the wildcard. This is why we specify using the pageId rather than title.
hasRemoteLinks
Find any issue that has a remote link of any kind.
This query could be slow in instances with a large number of projects and issues, since it is an alias for linkedIssuesOfRemote('*').