Pre-defined JQL functions

Looking for the documentation on the newest versions of Power Scripts for Jira 8 for Server/Data Center? Click here !

Naming considerations

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.

Contents

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.

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.

hasLinks

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

key in hasLinks("project = TSTAG") //will return issues that have links of any type but not system added ones

hasAnyLinks

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

JQL syntax

key in hasAnyLinks(<JQL>)

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

Example

key in hasAnyLinks("project = TSTAG") //will return issues that have links of any type

issuesLinkedAtDepth

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

JQL syntax

key in issuesLinkedAtDepth(<JQL>, <recursionLevel>[, <optional link type>, [, <"both"|"inward"|"outward"|"0","1","2">]])

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

key in issuesLinkedAtDepth("project = TSTAG", 2, "Blocks") //follows the "blocks" link type in searching

key in issuesLinkedAtDepth("project = TSTAG", 2, "Blocks", "outward") // only gives issues blocked by issues from the filter at the second level 
//(i.e.) suppose you have TSTAG-10 blocking TSTAG-9 which in turn is blocking TSTAG-8, the filter above will return the TSTAG-8 issue

Issue Structure

parentsOf

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

JQL Syntax

key in parentsOf(<JQL>)

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

key in parentsOf("TSTAG-11")
key in parentsOf("TSTAG-11, TSTAG-12")

hasSubtasks

Finds issues that have at least one subtask:

JQL Syntax

key in hasSubtasks(<JQL>)

Filters all main issues having subtasks:

Example

key in hasSubtasks("project = TSTAG")

subtasksOf

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

JQL Syntax

key in subtasksOf(<JQL>)

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

Example

key in subtasksOf("project = TSTAG")

epicsOf

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

JQL Syntax

key in epicsOf(<JQL>)

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

key in epicsOf("project = TSTAG") //returns only the epics from the project

issueInEpics

Finds the issues belonging to the given epics or JQL:

JQL Syntax

key in issueInEpics(<JQL>)

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

key in issueInEpics("EPIC-1,EPIC-2,EPIC-3") //do not forget that you can pass in a list of epics, not only a JQL

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

key in portfolioParentsOf(<JQL>[, levelsToSearch])

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

key in portfolioParentsOf("TSTAG-11")
key in portfolioParentsOf("TSTAG-11, TSTAG-12")

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

key in portfolioParentsOf("TSTAG-11", 1)

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

key in portfolioParentsOf("TSTAG-11, TSTAG-12", 1)

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

key in portfolioParentsOf("TSTAG-11, TSTAG-12")

portfolioChildrenOf

This routine is available starting with v4.5.0.

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

JQL Syntax

key in portfolioChildrenOf(<JQL>[, levelsToSearch])

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

key in portfolioChildrensOf("TSTAG-11")
key in portfolioChildrenOf("TSTAG-11, TSTAG-12")

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

key in portfolioChildrenOf("TSTAG-11", 1)

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

key in portfolioChildrenOf("TSTAG-11, TSTAG-12", 1)

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

key in portfolioChildrenOf("TSTAG-11, TSTAG-12")

Attachments

hasAttachments

Finds the issues with at least one attachment:

JQL Syntax

key in hasAttachments(<JQL>)

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

Example

key in hasAttachments("project = TSTAG")

hasAttachment

Finds the issues having an attachment matching the provided REGEX:

JQL Syntax

key in hasAttachment(<JQL>, <file name fragment or REGEX expression>)

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

Example

key in hasAttachment("project = TSTAG", ".arc") //returns all issues having an attachment containing ".arc" into the attachment name

Quick Filters

assigneeIsReporter

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

JQL Syntax

key in assigneeIsReporter(<JQL>)

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

SAFe Support

SAFe methodology support is provided by a one-of-a-kind app – SAFE Epic to Feature Translator. You need to install and activate this add-on in order for the following functions to work. Also, they are available starting with version 4.1.5 of Power Scripts™.

featuresOf

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

JQL Syntax

key in featuresOf(<JQL>)

issuesInFeatures

Finds the issues belonging to the given features or JQL:

JQL Syntax

key in issueInFeatures(<JQL>)

Want more functions?

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