JQL functions

Jira Server only

There are three JQL functions supported by the add-on:


Note

The jql functions are continuously optimized to obtain the best performance in terms of response times.

The runtime of the jqls depends on 3 factors:
1. The number of issues for which the hierarchy must be built.
2. The depth of the hierarchy to be obtained.
3. The number of links that have the issues present in the hierarchy.

You should keep in mind that the greater these factors are, the greater the amount of information that will have to be analyzed, especially with the linksHierarchyFilter and linksHierarchyVersion.

For this reason, we recommend using the jql functions always applying filters(exclusions) to limit the amount of information to analyze and improve response times.




All of them work in the same way:


  1. The add-on gets the root elements: In the case of the linksHierarchyIssue the root is a single issue, while in the other cases, the add-on will run the provided filter or will get all the issues related to a given project version
  2. For each root issue (1), the add-on will build the hierarchy structure in the memory and it will apply the JQL optional parameters to prune the filtered nodes
  3. For each hierarchical structure (2), the add-on will get all the distinct issues and they will be displayed on the JIRA Search page.

All the functions require a mandatory parameter (an issue, filter or version) and support the same optional parameters. Run each JQL function without any parameter to see a tip about how to use it:


The results of the JQL function are displayed on a column at the right with a synchronized view of the issue details beside right:
For example:

issue in linksHierarchyIssue("demo-9")




By default, the JQL function shows the first depth only. You can filter the results by setting some optional parameters:

issue in linksHierarchyIssue("demo-9","","","","story")

NOTE: Use a blank parameter "" to set the default value



Understanding unexpected results: like in the example above, you might want to filter (exclude) by issue type = Story… and you might get much less issues than you expected.
This is because the filters are applied internally. In this example, the issue-9 has the following children:

DEMO-5 (Story) and DEMO-10 (New feature). When the JQL function builds the tree, it founds the DEMO-5 and it will stop to load that branch because the DEMO-5 issue type (Story) has been included in the filter. Therefore the DEMO-1 and the DEMO-6 which are children of the DEMO-5 issue will be ignored as well as their children, and so on.




linksHierarchyIssue


linksHierarchyIssue

It takes an issue as input and builds the full hierarchy structure of linked issues

#

Name

Type

Required

Values

Description

1

Issue

String or integer

Yes


The issue key or id of the issue which is the root of the hierarchy

2

depth

Integer

No

Integer between 1 and 5

Limits the depth of the hierarchy structure. Default is 1.

3

Link direction

String

No

'Inward' or 'outward'

Excluded link direction

4

Link type

String

No

The link type name

List of the excluded link types separated by comma

5

Issue type

String

No

The issue type name

List of the excluded issue types separated by comma

6

Version name

String

No

The version name

The name of the versioned issues to exclude. It applies to the affects and fix version issue fields.

7

Resolved

String

No

Yes or No

Yes: include the resolved issues (default)
No: exclude the resolved issues


Examples

we take the following issue as an example:



#Example 1: 

Get the links hierarchy of level 1 for PUB-4.


#Example 2: 

Get the links hierarchy of level 2 for PUB-4, excluding the issues with "Version2"


Version filter

When using the filter to exclude versions, you should keep in mind that an issue will be filtered if all versions of the issue (affects and fix) are in the excluded versions:

for all version in ('Affects Version/s' U 'Fix Version/s'), version exists in 'Version filter'


#Example 3: 

Get the links hierarchy of level 2 for PUB-4, excluding initiatives.





linksHierarchyFilter


linksHierarchyFilter

It takes a saved filter is as input, executes it, takes all the root issues, builds the hierarchy structure of linked issues, applies the filter parameters and collects all the different issues into a list.

#

Name

Type

Required

Values

Description

1

Filter

String

Yes


A filter name or ID

2

depth

Integer

No

Integer between 1 and 5

Limits the depth of the hierarchy structure. Default is 1.

3

Link direction

String

No

'Inward' or 'outward'

Excluded link direction

4

Link type

String

No

The link type name

List of the excluded link types separated by comma

5

Issue type

String

No

The issue type name

List of the excluded issue types separated by comma

6

Version name

String

No

The version name

The name of the versioned issues to exclude. It applies to the affects and fix version issue fields.

7

Resolved

String

No

Yes or No

Yes: include the resolved issues (default)
No: exclude the resolved issues


Examples

we take the following data as an example:

issues in the 'FLT_MIN' filter



links Hierarchy of LH-2 (depth 2)


links Hierarchy of PUB-90 (depth 2)


#Example 1: 

Get the links hierarchy of level 2 for the 'FLT_MIN' filter.


#Example 2: 

Get the links hierarchy of level 2 for the 'FLT_MIN' filter, excluding the resolved issues.

  • LH-2: filtered because it is resolved. By filtering LH-2, their descendants are not collected.


#Example 3: 

Get the links hierarchy of level 2 for the 'FLT_MIN' filter, excluding the link type 'Nombre de Épica'.

Name of the link type

The name of the link type will depend on the language you have configured in your Jira. To know the name, visualize the 'Link' filter.

  • PUB-8: filtered by link type.
  • LH-3: not filtered by link type. By filtering LH-3, their descendants are not collected.


#Example 4: 

Get the links hierarchy of level 2 for the 'FLT_MIN' filter, excluding Tasks, Subtasks and Iniciatives.

Issue types

The names of the issue types depend on the language you have configured in your Jira. To know the name, visualize the 'Issue' filter.

  • PUB-90: filtered by issue type. By filtering PUB-90, their descendants are not collected.
  • LH-6: filtered by issue type.





linksHierarchyVersion


linksHierarchyVersion

It takes a project version id or name is as input, gets all the issues affecting or fixing the version, takes all the root issues, builds the hierarchy structure of linked issues, applies the filter parameters and collects all the different issues into a list.

#

Name

Type

Required

Values

Description

1

Version

String

Yes


A version name or ID

2

depth

Integer

No

Integer between 1 and 5

Limits the depth of the hierarchy structure. Default is 1.

3

Link direction

String

No

'Inward' or 'outward'

Excluded link direction

4

Link type

String

No

The link type name

List of the excluded link types separated by comma

5

Issue type

String

No

The issue type name

List of the excluded issue types separated by comma

6

Version name

String

No

The version name

The name of the versioned issues to exclude. It applies to the affects and fix version issue fields.

7

Resolved

String

No

Yes or No

Yes: include the resolved issues (default)
No: exclude the resolved issues

Examples

we take the following data as an example:

issues that have 'Version Beta 2'


links Hierarchy of PUB-2 (depth 2)


links Hierarchy of PUB-84 (depth 2)

#Example 1: 

Get the links hierarchy of level 2 for the version 'Version Beta 2'.

#Example 2: 

Get the links hierarchy of level 2 for the version 'Version Beta 2', excluding issues that have 'Version2'

  • PUB-71: filtered by having only 'Version2'. By filtering PUB-71, their descendants are not collected.
  • LH-5: not filtered by also having 'Version3'

#Example 3: 

Get the links hierarchy of level 2 for issues that don't have only 'Version Beta 2'

  • PUB-84filtered by having only 'Version Beta 2'. By filtering PUB-84, their descendants are not collected.
  • PUB-2: not filtered by also having 'Version Beta 3'.

#Example 4: 

Get the links hierarchy of level 2 for the version 'Version Beta 2', excluding issues that have 'Version Beta 2' and 'Version Beta 3'

  • PUB-84: filtered because all its versions are in the excluded versions. By filtering PUB-84, their descendants are not collected.
  • PUB-2: filtered because all its versions are in the excluded versions. By filtering PUB-2, their descendants are not collected.

#Example 5: 

Get the links hierarchy of level 2 for the version 'Version Beta 2', excluding issues that have not version

  • PUB-8: filtered because it has no version.
  • PUB-85: filtered because it has no version.
  • PUB-1: filtered because it has no version. By filtering PUB-1, their descendants (LH-5 and PUB-3) are not collected, although LH-5 have versions.