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:

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
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
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-84: filtered 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.