Pre-Defined JQL Functions

Owned by Jonathan Muse
Last updated: Aug 18, 2022
6 min read

Starting with version 4.1.1, Power Scripts™ got itself a list of pre-defined JQL routines that many of our users have been requesting. Reasons? Well, probably the most important one is the performance, since the predefined functions are precompiled thus they have a much better execution time.

In the following chapters, we tried to split the provided JQL functionalities into similar covered areas. At the moment we cover the basic searches for links, structural search (including epics if you have Jira Agile installed), attachments, and quick filters.

And a note: we used the "key in ..." syntax everywhere, to emphasize that there is a list of issues there, and not a single issue returned. And of course, you can use "key not in ..." as well.

Note that that the name of the function must be unique within the Jira instance. If more than one app adds a JQL function under the same name, only one registration will succeed. You can still control which of the apps will provide the JQL function by enabling / disabling the relevant modules at the app level, but this tends to be error-prone. Be careful with the JQL routines added by other apps.

Starting with v4.1.4 of the Power Scripts™ these routines are disabled by default, to avoid such conflicts. You can enable them manually from the plugin UPM modules page.

Linked Issues

hasLinksOfType

Finds the issues having links of the provided type:

JQL syntax
key in hasLinksOfType(<JQL>, <Link Type>[, <"both"|"inward"|"outward"|"0","1","2">])

Examples:

Example
key in hasLinksOfType("project = TSTAG", "Blocks") //will return both inward and outward links key in hasLinksOfType("project = TSTAG", "Blocks", "0") //equivalent of the above key in hasLinksOfType("project = TSTAG", "Blocks", "both") //equivalent of the above key in hasLinksOfType("project = TSTAG", "Blocks", "1") //will return only inward links ("inward" works too) key in hasLinksOfType("project = TSTAG", "Blocks", "2") //will return only outward links (similar, you can use "outward")

To search for the standard links, you can use the name of the link only, case sensitive:

  • Blocks - for "is blocked by" / "blocks"

  • Cloners - for "is cloned by" / "clones"

  • Duplicate - for "is duplicated by" / "duplicates"

  • Relates - instead of "relates to"

For all the user-defined relationships, use the name you gave to the issue link type.

Finds issues that have links of any kind:

JQL syntax
key in hasLinks(<JQL>)

A simplification of the above, it filters all the issues that have links, excluding the system links (standard subtasks, Jira Agile, and Service Desk added issue links):

Example

Finds issues that have links of any kind, this also includes system links:

JQL syntax

JQL routine filters all issues that have any kind of links:

Example

issuesLinkedAtDepth

Finds issues linked at the provided depth and optionally, of a certain type:

JQL syntax

The recursion level, mandatory, gives the levels we need to look under. It must be a positive number in the [1-16] interval. The optional link type is the link to follow. Controlling the direction of traversal is done through the 4th parameter.

Example

Issue Structure

parentsOf

Finds the issues being the parents of the given issue, issue list or JQL:

JQL Syntax

Returns parents of the issues selected by the provided JQL. You can also pass a list of issue keys, then they have to be comma separated:

Example

hasSubtasks

Finds issues that have at least one subtask:

JQL Syntax

Filters all main issues having subtasks:

Example

subtasksOf

Finds the issues being the subtasks of the given issue, issue list, or JQL:

JQL Syntax

The opposite of the above, the subtasksOf returns the subtasks of the issues selected by the provided JQL:

Example

epicsOf

Finds issues that are epics of the given issue, issue list, or JQL:

JQL Syntax

This will work if you have Jira Agile installed, and does a similar thing as the subtasksOf function above, but for the epic - issue relationships.
It will return the epics of the issues selected by the JQL.

Example

issueInEpics

Finds the issues belonging to the given epics or JQL:

JQL Syntax

Again, we have provided the ability to get the issues from certain epics. If the issues selected by your JQL are not epics, they are discarded. Then, for the resulting epics, the issues are returned:

Example

Portfolio issue structure

Starting with version 4.5.0, we implemented routines to support Portfolio fields so that you can work with the parents and children of a given ticket.

portfolioParentsOf

This routine is available starting with v4.5.0.

Finds the issues being the Portfolio parents of the given issue, issue list or JQL:

JQL Syntax

Returns the Portfolio parents of the issues selected by that provided JQL. You can also pass a list of issue keys, in that case they have to be comma separated:

Example

Optionally, you can also pass a second argument/parameter, to specify the number of levels to search each Issue's Portfolio parents. 
If this is not provided, all parents will be returned. Given the following code

Example

can only return one issue, if exists, since one issue can only have one parent.

The following code can return zero issues (if none of the provided issues have parents), one issue (if they both have the same parent, or if only one of them has a parent), or two issues (if they have different parents):

Example

Note that the provided Issues can be on different Portfolio levels.

The following code will return all parents (without duplicates) of both Issues, gathering all parents and parents' parents and so on:

Example

portfolioChildrenOf

Finds tickets that are the Portfolio children of the given issue, issue list or JQL:

JQL Syntax

Returns the Portfolio children of the issues selected by that provided JQL. You can also pass a list of issue keys, in that case they have to be comma separated:

Example

Optionally, you can also pass a second argument/parameter, to specify the number of levels to search each Issue's Portfolio children. 
If this is not provided, all children will be returned. Given the following code

Example

can return zero or multiple issues, if exists, since one issue can only have one or more children. All returned children will be on the same Portfolio level in the hierarchy.

The following code can return zero Issues or more issues:

Example

Note that the provided issues can be on different Portfolio levels, so the returned children can also be found on different Portfolio levels.

The following code will return all children (without duplicates) of both issues, gathering all children and children's children and so on until no children are found (usually the sub-task level is reached):

Example

Attachments

hasAttachments

Finds the issues with at least one attachment:

JQL Syntax

As an example, the following JQL returns all issues that have an attachment:

Example

hasAttachment

Finds the issues having an attachment matching the provided REGEX:

JQL Syntax

Returns the issues having a certain attachment name. You can provide either a fragment of the attachment or a full, valid REGEX expression:

Example

Quick Filters

assigneeIsReporter

Finds the issues that have the same assignee as the reporter:

JQL Syntax

Filter the issues having the same person in both assignee and reporter fields.

SAFe Support

featuresOf

Finds issues that are features of the given issue, issue list, or JQL:

JQL Syntax

issuesInFeatures

Finds the issues belonging to the given features or JQL:

JQL Syntax

Want more functions?

If you would like more functions, feel free to request them, we'll be happy to help.