Vivid Trace 1.3 Search and JQL Reference
This document contains definitions of all the Vivid Trace JQL functions, along with samples of advanced searches that illustrate how these functions can be applied to common situations. To fully understand the information in this document, you should use this document in conjunction with JIRA's Advanced Searching documentation. This document covers the following topics:
- Searching Issue Relationships with Vivid Trace
- Accuracy of Results
- JQL Function Reference
- JQL Function Parameter Reference
- Performance
- Troubleshooting
For error & warning messages refer to Messages and Codes.
Searching Issue Relationships with Vivid Trace
Vivid Trace has a suite of highly-configurable JQL functions for comprehensively tracing issues along their issue link relationships and their parent/sub-task relationships using JIRA's Advanced Searching facilities. The essence of these functions is the identification of issues based on their relationships with other issues, a capability that JIRA lacks off-the-shelf.
Rudimentary queries can be formulated in three stages: indicate seed issues ("where to start"), specify how to conduct the search along issue relationships and other factors ("how to follow"), and finally narrow down results to the desired issues ("what to gather"). Once you have acclimated yourself, queries become a matter of describing the desired issues and their relationships to and characteristics of other issues.
JQL Functions and Seed Issues
Let's start with the relations()
JQL function. You indicate which issues to start searching from (the seed issues) by passing certain parameters to the function. relations()
will find all issues related to the seed issues by issue links and by parent/sub-task relationships. Seed issues can be specified directly as issue
parameters, and as the issues returned from jql
query parameters. All JQL functions accept any mix and quantity of seed issue parameters.
Objective & Explanation | JQL Query |
---|---|
Find all issues related to a specific issue. Here, ABC-1 is the lone seed issue. This query returns a list of issues that includes the seed issue plus every issue reachable from the seed issue by issue links and by parent/sub-task relationships. Issues for which the current user doesn't have view permission and any further issues beyond it are not included in the results. | issue IN relations(ABC-1) |
Find all issues related to and including several seed issues. Here, three issues are referred to by their issue keys, and one by its issue ID. | issue IN relations(ABC-33, ABC-481, 317289, XYZ-67) |
Identify all issues related to the issues returned from a JQL query. Depending on the quantity of issues returned from the JQL query and their connectedness, potential many issues can be found. | issue IN relations('jql = labels IN (support, operations)') |
Find all issue relations from a mix of seed issues. This query combines both methods of specifying seed issues. The issues found from executing the JQL queries and the directly specified issues are all merged together into the seed issues. | issue IN relations('jql = filter = "Exceeding SLA"', ABC-98, 'jql = assignee = "Beverly Dubois"', XYZ-10) |
You can control whether or not the seed issues are included in the search results using the inclusive
parameter. Some particular parameter settings recur often enough that they warrant their own shorthand. The relatesWith()
function is useful in the common situation where the seed issues are not wanted in the result set.
Objective & Explanation | JQL Query |
---|---|
Find all issues related to, but not including, several seed issues. The inclusive parameter tells the JQL function to not include the seed issues in the resulting list of issues. | issue IN relations(ABC-33, ABC-481, 'inclusive = no') |
Another way to write the above JQL query. It produces identical results, but uses the relatesWith() JQL function to make the query more concise and easier to reason about. | issue IN relatesWith(ABC-33, ABC-481) |
Searching Issue Link and Parent/Sub-task Relationships
Vivid Trace provides parameters for searching particular types of issue relationships, along with functions that abbreviate the task of writing such queries. The direction
parameter controls the effective directions: which kinds of issue relationships are followed when searching. When following issue link directions, the issueLinkType
parameter either limits or prunes which issue link types are followed during the search process, thus controlling the effective issue link types. distance
controls how far away from the seed issues to scan while conducting the search. The links()
function finds issues that have issue links. Where the parents()
function identifies parent issues, issues that have sub-tasks, subtasks()
finds sub-task issues, issues that have parents and are of a sub-task issue type.
Objective & Explanation | JQL Query |
---|---|
Find all issues in a project that have issue links. | issue IN relations('jql = project = ABC', 'direction IN (inward, outward)') |
Another way to write the above JQL query. It produces identical results, but uses the links() JQL function to make the query more concise and easier to reason about. | issue IN links('jql = project = ABC') |
Find all issues that have issue links of a certain type. | issue IN links('issueLinkType = Duplicates') |
Requirements satisfaction for a given software release. | issue IN relations('jql = project = ABC AND fixVersion = "1.2.3" AND issueType = Requirement') |
Starting from the issues in a saved filter, all issues reachable by up to 3 issue links away. | issue IN links('jql = filter = RemainingTasks', 'distance = 3') |
Find all issues outside of a project that are linked to issues within a project. | issue IN links('jql = project = ABC', 'inclusive = no') |
All parents in and of the issues found by a saved filter (referenced by name). | issue IN parents('jql = filter = "Back-support Escalated"') |
Issues whose sub-tasks are assigned to specific people. | issue IN parents('jql = assignee IN ("Carlita Mendez", "Funani Mkatshana")') |
All sub-tasks in and of the issues found by a saved filter (referenced by ID). Sub-tasks directly found by the filter are included in the results only if their parents were found too. | issue IN subtasks('jql = filter = 10020') |
All issues involved in cloning: the clones and the cloned (assuming the issue links are intact). | issue IN links('issueLinkType = Cloners') |
Overdue issues in a project of concern and the unresolved issues that feed into them. | issue IN relations('jql = project = ABC AND dueDate < now()', 'direction IN (parents, inward)') AND resolution IS EMPTY |
Nearby (and thus shorter list of) upstream issues that feed into a project of concern. | issue IN relatesWith('direction in (parents, inward)', 'jql = project = ABC', 'distance = 2', 'issueLinkType in (Blocks, Requires)') |
Narrowing Down Results
Seed issues indicate from where to start searching for issue relations, and have the potential to produce impractically large result sets that can't factor into your decision making. To extract only desired issues or to shorten the results to usable quantities, the resulting issues produced by these JQL functions can be further qualified by specifying the characteristics of the desireable issues.
Objective & Explanation | JQL Query |
---|---|
Describe from where to start searching for issue relations by indicating seed issues. | issue IN relations(...) |
Describe the nature of issues to produce by qualifying resulting issues with additional JQL clauses. | issue IN relations(...) AND ... |
Narrow down the related issues for a project version to higher-priority items assigned to the current user for an impending release. | priority IN (Blocker, Critical) AND assignee = currentUser() AND issue IN relations('jql = fixVersion = "1.2.3"') |
Pinpoint all issues outside of a project blocking a release. | issue in links('jql = project = ABC AND fixVersion = "1.2.3"', 'inclusive = no') AND project != ABC |
Identify issues shared by two spheres of responsibility. | (issue IN relations(ABC-55, 'distance = 4')) AND (issue IN relations(MNP-177, 'distance = 3')) |
Unresolved parent issues for a version, some of which might be from different projects. | issue IN parents('jql = project = ABC AND fixVersion = "1.2.3"') AND resolution IS EMPTY |
Show unresolved sub-tasks for a component. | resolution IS EMPTY AND issue IN subtasks('jql = component = Widget') |
Search for all issues blocking Zephyr for JIRA tests. Note that, depending on the version of Zephyr that created the issue links, those issue links might be set backwards, requiring an inversion of direction in your JQL queries or in your interpretation of the results. | issue IN relatesWith('jql = issueType = Test', 'distance = 1', 'direction = inward', 'issueLinkType = Blocks') AND issueType != Test |
Research documents attached to resolved duplicates while investigating a regression. | attachments IS NOT EMPTY AND ((issue IN relations('issueLinkType = Duplicates') AND resolution IS NOT EMPTY) OR (resolution = Duplicate)) |
Searching Based on the Existence of Relationships
relations()
and certain other sibling functions can be used to identify issues that have at least one relationship with another issue, be it an issue link or a parent/sub-task relationship. Searching based on the existence of relationships is accomplished by not supplying seed issues to the functions. When no seed issues are supplied but certain other parameters are, all issues that match (using issue IN ...
) or do not match (using issue NOT IN ...
) those parameters will be found.
Objective & Explanation | JQL Query |
---|---|
All issues that have one or more issue link or parent/sub-task relations. | issue IN relations() |
Orphan issues: All issues that have no such relations whatsoever. | issue NOT IN relations() |
Linked issues in certain statuses. | status IN ('In Progress', 10005) AND issue IN links() |
Sub-tasks not in a certain issue status. | resolution != Fixed AND issue IN subtasks() |
Potential orphans that are not related to other issues in a project. | project = 'ABC' AND issue NOT IN relations() |
Changes that occured anywhere along an entire value delivery chain (following relations) within the last 7 days. | updated <= 1w AND issue IN relations() AND project = ABC |
Quoting Function Parameters
JQL function parameters whose values contain quotes, commas, and other punctuation may require escaping and nested quoting, complicating legibility, readability, and problem diagnoses. Almost all of the parameters to these functions need to be quoted, with either single-quotes or double-quotes. Ideally you can copy & paste directly between parameters and other places, such as issue fields, however because such data also often contains punctuation and requires quoting, the parameters can end up having nested quotes and escaping.
Quotes nested within quotes of the same type, either single- or double-quotes, must be escaped using backslash \
characters. Alternatives to nested quoting and escaping include: Refer to source objects by ID instead of by name, split portions of the query into saved filters and reference those filters instead, or eliminating spaces and other JQL punctuation from the source objects' names.
Objective & Explanation | JQL Query |
---|---|
A query with nested quotes that identifies issues linked with the Cross Check issue link type. The issueLinkType parameter is surrounded with quotes, and its parameter value is also quoted because the name contains a space character. Because the inner quotes nested within the outer quotes are of the same type, the inner quotes need to be escaped. Notice how the escaping reduces readability. | issue IN links("issueLinkType = \"Cross Check\"") |
Another way to write the above JQL query. The respective quotings are different, and therefore the inner quotes need not be escaped. Note that single and double quotes may be difficult to distinguish when placed adjacently, as is so near the end of this query. | issue IN links("issueLinkType = 'Cross Check'") |
Yet another way to write the above queries. It also produces identical results, but references the issueLinkType by its ID, thereby avoiding nested quotes altogether, improving legibility while sacrificing readability. | issue IN links("issueLinkType = 10212") |
Accuracy of Results
When the stakes are high and a query's results are being fed into critical decision making processes like Release to Manufacturing or when asking "should this project be funded?", you need to understand the information in this section.
Security and JIRA Permissions
Vivid Trace enforces the JIRA security model but has its own flavor on one point for the sake of accurate results: Vivid Trace JQL functions issue warning VTW-7
whenever the search process finds related issues for which the user executing the search doesn't have browse permission. Such issues become dead-ends and are not reported in the results. This warning alerts the viewer to the incompleteness of the results on account of the current user not having the necessary permissions to display all related issues. Whether that incompleteness matters to you depends on your use case. When every last related issue needs to be put under the spotlight, such as when conducting traceability analysis, you need to ensure that the JIRA user account in use has permission to browse all issues in question.
Warning message VTW-7
that accompanies incomplete search results when the current user lacks permission to browse one or more of the related issues.
In keeping with JIRA's own JQL functions, Vivid Trace JQL functions will not acknowledge seed issues for which the current user lacks browse permissions, returning error message VTE-1
instead.
Methods of resolving a lack of permissions include: Using a JIRA user account that has permission to browse all issues in question, and adjusting BROWSE
permission on project permission schemes and issue-level security schemes.
The projectConfig
Parameter
These JQL functions can apply project configurations (by specifying the
parameter) to affect the results. Because project configurations can be changed over the course of a project's lifetime, the projectConfig
= applyprojectConfig
parameter should not be apply
'ed wherever results must remain consistent even when project configuration changes, for example in long-serving saved filters.
Stables IDs and Volatile Names: Interpretation of Parameter Values and Trade-offs
For parameter values that can specify JIRA objects by either ID or name, such as for issue link types, the value will be treated as an ID first, and if the ID cannot be resolved, then it will be treated as a name for another try at resolution. With this ordering, your queries will not change their behavior even when an object is created with or renamed to a name that mimics the IDs used in your queries.
And this is the tradeoff: When reading JQL queries, names are helpful because they convey meaning, while as simple numbers IDs are inherently opaque. On the other hand, while IDs cannot be changed, names can be edited by owners or administrators at any time, and distinct objects can bear identical names leading to ambiguity. Renaming objects can cause saved JQL queries whose function parameters refer to such objects by name to return incorrect results or start returning errors instead. In short, use of IDs in function parameters earns you queries that are more resistent to renaming and thus stable but at the cost of legibility, whereas names are readable but potentially hazardous, especially when a query's results are being fed into critical decision making processes like Release to Manufacturing or when asking "should this project be funded?" A correct approach is to select for readability versus sure-fire correctness of results. Queries written in an unstable manner can produce nearly imperceptible differences, wildly different results, or errors. Errors are perhaps the best outcome, because they alert you to the changes while not producing poisonous results.
To help eliminate ambiguity and maligned query results, Vivid recommends clearly avoiding naming objects in a way that can be interpreted as IDs. For example, avoid naming a saved filter as "10001", as that name is interpretable as an ID and likely overlaps an existing, different saved filter whose ID actually is 10001
.
Objective & Explanation | JQL Query |
---|---|
As version 1.2.3 can be renamed or exist in several projects, this query is susceptible to producing different results should the names of the referenced objects change. | issue IN relations('jql = project = ABC AND fixVersion = "1.2.3"') |
Even if the same version string is registered in several projects, version IDs uniquely identify a singular version in one project. Even if the version is renamed, this query will continue producing reliable results. | issue IN relations('jql = fixVersion = 11806') |
JQL Function Reference
Vivid Trace comes equipped with a suite of JQL functions for identifying related issues according to a variety of criteria, specified as parameters. Function parameters are detailed in the next section. In addition to the general relations()
JQL function, there are several specialisations at your disposal for writing more concise JQL queries that are easier to reason about. None of these functions observe or are affected by the Issue Count Soft Maximum, a setting that limits the size of the results. Functions that are asked to make use of issue linking and/or sub-task features that are disabled in your JIRA system will issue warning messages VTW-8
and VTW-9
, respectively.
The functions are:
links()
Usage |
where |
---|---|
Description | Identifies issues reachable from the seed issues by following along issue links, according to parameters. Without seed issues, identifies all issues that have issue links. Equivalent to |
Returns | List of issues. |
Availability | Since Vivid Trace 1.2. |
parents()
Usage |
where |
---|---|
Description | In terms of parent/sub-task relationships, parent issues are issues that have sub-tasks. This function identifies those seed issues that are parent issues plus all issues that are parents of the seed issues, according to parameters. When used without seed issues, this function identifies all parent issues. JIRA's own JQL function |
Returns | List of issues. |
Availability | Since Vivid Trace 1.2. |
relatesWith()
Usage |
where |
---|---|
Description | Identifies issues that relate with, but do not include, the seed issues, according to parameters. Issue link and parent/sub-task relationships are all considered. This function requires seed issues. Equivalent to |
Returns | List of issues. |
Availability | Since Vivid Trace 1.2. |
relations()
Usage |
where |
---|---|
Description | Identifies issues that are related to the seed issues by following along issue link and parent/sub-task relationships, according to parameters. By default, this function will search for all issues related to the seed issues in all directions at any distance, and include the seed issues in the results. Searches are performed by first determining which issues to start searching from (the seed issues). Issues directly specified as Next, the search begins for related issues. The search is conducted on each seed issue, and no further than specified by the When no seed issues are supplied, the search identifies all issues in the JIRA system that have any relations at all and for which the current user has browse permission. The results can be narrowed down with the Relationships with JIRA Agile Epic issues are treated as issue links. |
Returns | List of issues. |
Availability | Since Vivid Trace 1.2. |
See also | links() parents() relatesWith() subtasks() |
subtasks()
Usage |
where |
---|---|
Description | In terms of parent/sub-task relationships, this function identifies those seed issues that are sub-task issues plus all issues that are sub-tasks of the seed issues, according to parameters. When used without seed issues, this function identifies all sub-task issues. JIRA's own JQL function |
Returns | List of issues. |
Availability | Since Vivid Trace 1.2. |
JQL Function Parameter Reference
This section describes all of the parameters for the JQL functions. While JIRA's Auto-complete is available for the JQL functions, it is not available for these parameters. Either single quotes or double quotes can be used to quote parameters. Parameters, including values, are case-insensitive wherever possible. Parameters are not positional; they can appear in any order. Duplicate values within parameters are silently ignored.
The parameters are:
direction
Usage |
where |
---|---|
Default value | All directions |
Description | With seed issues,
When used without seed issues, only those issues that have relationships in any of the effective directions will be identified. This parameter is blind to particular issue link types and parent- or sub-task- issue types. To restrict the search to particular issue link types, see the Note that this parameter must be enclosed in single or double quotes. |
Limitations |
|
distance
Usage |
where |
---|---|
Default value | Unlimited distance |
Description | Search for issues within up to a maximum distance of Note that this parameter must be enclosed in single or double quotes. |
Limitations |
|
inclusive
Usage | 'inclusive = yes' 'inclusive = true' 'inclusive = no' 'inclusive = false' |
---|---|
Default value | yes , include seed issues in results |
Description | Determines whether the seed issues are included in the results. Note that this parameter must be enclosed in single or double quotes. |
Limitations |
|
issue
Usage | issue ID issue key |
---|---|
Description | The supplied issue can be specified by either a valid ID or key, and is added directly to the seed issues, from which the search is started. When an issue key identifies more than one issue, one of those issues is chosen arbitrarily. An attempt is made to interpret |
Limitations |
|
issueLinkType
Usage |
where |
---|---|
Default value | All issue link types |
Description |
With seed issues, An attempt is made to match each When used without seed issues, only those issues that have issue link relationships of any of the effective issue link types will be identified. Note that this parameter must be enclosed in single or double quotes. |
Limitations |
|
jql
Usage |
where |
---|---|
Description | Starts the search from issues returned by the supplied JQL query. Issues returned from the JQL query are added to the seed issues, from which the search is started. Form this parameter by adding The JQL query JQL parsing and permissions problems are reported back as error message Note that this parameter must be enclosed in single or double quotes. |
Limitations |
|
projectConfig
Usage | 'projectConfig = apply' 'projectConfig = ignore' |
---|---|
Default value | ignore project configuration |
Description | Instructs the JQL function to Alternatively, when set to Note that this parameter must be enclosed in single or double quotes. |
Limitations |
|
Performance
Performance of the JQL functions relies mainly on the performance of JIRA and its Lucene index. In addition to the information published in the JIRA Performance Tuning Knowledge Base article at Atlassian, Vivid recommends ensuring that the Lucene index resides completely in memory on all nodes during routine operation. Accommodating the full Lucene index in-memory is accomplished by vigilantly securing a margin of free JVM memory as measured during routine peak traffic periods. Even with Solid-State Disk (SSD) technology, the performance penalty of loading from disk instead of being in-JVM or cached by the host OS is measured in orders of magnitude.
You can judge baseline JIRA query performance and relative Vivid Trace JQL function performance by issuing and timing the following JQL queries.
Objective & Explanation | JQL Query |
---|---|
Cause a scan of all documents in JIRA's Lucene index, stricly using JIRA's own JQL functionality. | issueType IS NOT EMPTY |
Again, cause a full scan of the index, but this time using Vivid Trace's JQL functions. | issue IN relations() |
Troubleshooting
Characters Outside Unicode Basic Multilingual Plane (BMP): The use of Unicode characters outside of the Basic Multilingual Plane (BMP) with Vivid Trace has not been verified for correct operation and may lead to undefined & unsupported behavior.
JQL Function Name Collisions Between JIRA Add-ons: The JQL function names in Vivid Trace have been carefully chosen so that various add-ons can co-exist in your JIRA system. In the event that two or more add-ons register JQL functions with identical function names, JIRA will enable only the first of the overlapping functions it encounters, which might lead to loss of functionality. To resolve this situation, determine the affected add-ons, and then notify Vivid and the other vendors about the collision. While waiting for an up-stream solution, your JIRA Administrator can manually disable the colliding JQL function modules in each of the affected add-ons, and then re-enable just one JQL function in the add-on of your choice. Note that the functions will be unavailable to users during this administrative operation.
JQL Query is Too Long: The Advanced Search query input field appears to be limited in the number of ASCII characters it can accept in JQL queries. An example of this limit is approximately 8000 ASCII characters using the Advanced Query web-based user interface in JIRA Server version 6.3.11. Queries that exceed this length may cause JIRA to report an error with the message "Error occurred communicating with the server. Please reload the page and try again." One way to resolve this situation is to shorten the JQL query to within the length limit by splitting portions of the query into saved filters and then referencing those saved filters from the shortened query.
Translations and Localisations of JQL Function Parameter Values: The use of values and of user-provided name translations of JIRA objects or values using localisations unsupported by Vivid Trace has not been verified for correct operation and may lead to undefined & unsupported behavior.