Pre-defined JQL functions

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:

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

Examples:

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

hasLinks

Finds issues that have links of any kind:

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

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:

key in hasAnyLinks(<JQL>)

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

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:

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.

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:

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:

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

hasSubtasks

Finds issues that have at least one subtask:

key in hasSubtasks(<JQL>)

Filters all main issues having subtasks:

key in hasSubtasks("project = TSTAG")

subtasksOf

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

key in subtasksOf(<JQL>)

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

key in subtasksOf("project = TSTAG")

epicsOf

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

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.

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

issueInEpics

Finds the issues belonging to the given epics or JQL:

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:

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

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

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:

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

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

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:

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

portfolioChildrenOf

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

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:

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

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:

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

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

Attachments

hasAttachments

Finds the issues with at least one attachment:

key in hasAttachments(<JQL>)

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

key in hasAttachments("project = TSTAG")

hasAttachment

Finds the issues having an attachment matching the provided REGEX:

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:

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:

key in assigneeIsReporter(<JQL>)

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:

key in featuresOf(<JQL>)

issuesInFeatures

Finds the issues belonging to the given features or JQL:

key in issueInFeatures(<JQL>)

Want more functions?

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