The 'JQL Query' compares the number of issues returned from the JQL query against predefined conditions such as: You must write the 'JQL Query' and choose one option for the number of issues found. For example: For information on how to configure a check for a workflow transition in Jira, see the Jira documentation. See the JQL Use Cases for several examples. Jira Query Language (JQL) allows you to do some advanced searching in Jira's search dialog. This is a very powerful feature provided by Atlassian in Jira. JSU extends JQL with additional placeholders, which will be replaced with the values of the current issue in transition. For example, if you configure the following JQL query in a configuration screen of JSU: it will be changed by JSU into something like this, before the search is executed: This will search all sibling issues (same parent), which do not have the same component as the current issue (in this example Documentation). Any text in curly brackets, which follows the pattern {issue.FIELD NAME} will be replaced with the value of that field on the current issue (issue in transition). See below for further details on what names you can use for the different field types. Depending on your use case, you might not use any {issue.FIELD NAME} placeholder at all. Logical operators, Functions, and operators are the same as the JQL in JIRA. It is important to use the correct JQL syntax. The easiest way to write a JQL query for JSU is to prepare it first in Jira's standard search interface (use 'advanced search'!) with some sample value. Then copy it to JSU configuration and replace some of your sample values with {issue.FIELD NAME} as required. See JQL Use Cases for more examples. Add the following to your JQL query: sub-tasks with the same parent: parent = {issue.parent} excluding the current issue: key != {issue.key} See JQL Use Cases for more examples. JQL in JSU can be very powerful. However, you also must think very carefully, about what values might be used as replacements for the {issue.FIELD NAME} placeholders. Or what happens, if an issue has no value in such a field. There could be quite some variety in the data of your issues. You can set a limit for the maximum number of issues you expect from your JQL query (see also the previous paragraph). If the result of the JQL query returns more issues, JSU will not process anything. JSU is pulling the emergency brake before things get out of control. Like this, you can prevent JSU from accidentally processing hundreds of issues. By default, this limit is 50. You cannot set any higher limit than 1000. Field names in your JQL should be the same as in the Advanced Search. We suggest using the issue navigator's auto-complete feature to get the correct field names. In Jira's top menu bar, go to Issues > Search for issues, and switch to Advanced search. System Field names should be the same as those used in JQL. For example: reporter assignee issuetype priority Custom Fields names also should be the same as those used in JQL. For example: Approver or cf[10010] Hosting Server or cf[12910] Date to Join or cf[11000] Replaceable value from the current issue must be between curly brackets like Use the place holders from the following list: {issue.Affects Version/s} {issue.Assignee} {issue.Affects Version/s} {issue.Assignee} {issue.Component/s} {issue.Created} {issue.Creator} {issue.Customer Request Type} {issue.Description} {isseu.Due Date} {issue.Environment} {issue.Epic Color} {issue.Epic Name} {issue.Epic Status} {issue.Epic Link} {issue.Fix Version/s} {issue.Issue Key} {issue.Issue Number} {issue.Issue Type} {issue.Labels} {issue.Original Estimate} {issue.Original story points} {issue.Parent} {issue.Priority} {issue.Project} {issue.Rank} {issue.Remaining Estimate} {issue.Reporter} {issue.Request participants} {issue.Resolution} {issue.Resolved} {issue.Security Level} {issue.Sprint} {issue.Status} {issue.Summary} {issue.Time Spent} {issue.Time to resolution} {issue.Updated} {issue.Voters} {issue.Watchers} {issue.Work Ratio} Alternatively, you might use the technical field ID of a system field, or how JQL is referring to it. For example, those three variants refer to the same field: {issue.Affects Version/s} {issue.versions} {issue.affectedVersion} You can use either the name of a custom field or its ID. For example: {issue.My Text Field} {issue.customfield_12345} However, the cf[12345] notation is not supported between curly brackets. It's a good idea to check your log files for any errors and warnings from JSU. Even more when you're using complex JQL queries in JSU. While you configure a new workflow with JQL queries in JSU, you might even set the log level to DEBUG for the following package: See Troubleshooting to learn how to change a log level. JSU supports many different field types such as system fields and custom fields. However you should be aware, that not all field types are supported, and not in all combinations. We aim to cover the most important field types and are continuously adding and improving how different field types are supported. Some custom fields of other third-party apps might never be supported. For that reason, you should always test anything you do with the JSU app with fields. You can try it with a free 30-day evaluation license.Description
Configuration
Examples
How to write JQL Query
How to use placeholders for JQL in JSU
Configuration in JSU
parent = {issue.Parent} AND component != {issue.Component/s} OR component is EMPTY
Values after replacement
parent = 'ABC-123' AND component != 'Documentation' OR component is EMPTY
Top tips
Fields on the current issue
... AND key = {issue.key}
Fields on the parent issue
... AND key = {issue.parent}
Fields on all sibling issues (other sub-tasks of the same parent issue)
... AND parent = {issue.parent} AND key != {issue.key}
Think careful about what might be the result of your query
If you are not careful, the result of such a JQL query unexpectedly might contain thousands of issues. Or the JQL query might fail because the syntax has become invalid after the placeholders had been replaced.
Maximum Issues Allowed
JQL Injection
Be aware of potential 'JQL injection':
JSU does not check any value that it retrieves from the current issue. A malicious user might craft the value of a field (for example the value of a text field) so that after the replacement it adds additional criteria to your JQL query. We recommend that you don’t use any text fields as placeholders, or any other field, in which the user can freely change the text. Only use fields that can contain one/several clearly defined values.
Syntax for Field Names
System Fields
etc.Custom Fields
etc. If you have several custom fields with the same name, you can only use the cf[12345] notation to refer to one of them.
Syntax for Values of the current Issue
{issue.FIELD NAME}
System Fields
Label in the English Jira user interface.
Technical field id. See also reference from Atlassian.
JQL's way to refer to that field.Custom Fields
If you have several custom fields with the same name, you must use the custom field ID.
Troubleshooting
ch.beecom.jira.jsu.util.jql
Supported Field Types
Precondition Configuration
Preconditions can be configured in several ways:
A result of a precondition can be negated
A result of a precondition can be combined with a result of previous preconditions using the following ways:
Discard the result of the previous precondition (Results of the previous preconditions are not taken into account)
AND (All of the preconditions have to be true to allow execute a post function)
OR (Only one of the preconditions has to be true to allow execute a post function)