Vivid Trace 2021.1 JQL Reference

This document contains definitions of all 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
• Accuracy of Results
• JQL Function Reference
• JQL Function Parameter Reference
• Performance
• Troubleshooting

For error & warning messages refer to Messages and Codes.

Searching Issue Relationships

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.

You can control whether 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.

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. The artifactType parameter either limits or prunes which issue types are following during the tracing process, thus controlling the effective artifact types. Similarly, 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.

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 desirable issues.

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.

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.

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 deviates in one aspect 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.

The projectConfig Parameter

These JQL functions can apply project configurations (by specifying the projectConfig = apply parameter) to affect the results. Because project configurations can be changed over the course of a project's lifetime, the projectConfig 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 trade-off: 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 resistant 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.

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 specializations at your disposal for writing more concise JQL queries that are easier to reason about. The ordering of issues produced by these JQL functions is unspecified.

None of these functions observe or are affected by the Issue Count Soft Maximum, a setting that limits the size of the results, or by the Graph Traversal Time Limit, a setting that caps the amount of time Jira spends computing 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()
• parents()
• relatesWith()
• relations()
• subtasks()

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.

Parameters that can appear in any quantity:

• issue
• jql

Parameters that can be supplied at most once:

• artifactType
• direction
• distance
• inclusive
• issueLinkType
• projectConfig

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 System Optimization 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.

Troubleshooting

Characters Outside Unicode Basic Multilingual Plane (BMP): The use of Unicode characters outside 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 were carefully chosen to avoid overlapping with those of other add-ons known at the time of their naming. 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 of the conflicting JQL functions 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.