JQL functions

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





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"



#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.


#Example 3: 

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


#Example 4: 

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





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'

#Example 3: 

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

#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'

#Example 5: 

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