Purpose

Condition based on JQL query and Validation based on JQL query are used for hiding or blocking a transition depending on the result of a JQL query.

Field codes in format %{nnnnn} can be inserted in the JQL query. They will be replaced by the corresponding field values at JQL execution time. Most of the times you will require to introduce one or more field codes in your JQL query, since you usually want to make some kind of reference to current issue (%{00015}), current user (%{00020}), current date (%{00057}), assignee (%{00003}), etc.

Example: Prevent creation of same issue types with identical summary

Condition based on JQL query and Validation based on JQL query have 3 configuration parameters. In the case of the validator you also have a forth parameter called "Message to show when validation fails" which is a custom message to show the user to inform him the cause that prevents him from executing the transition.

In the following screenshot it's shown the way to config a validator in transition "Create Issue", in order to prevent issue creation whenever there already is an issue with the same summary, and same issue type, in the same project:

Note that:

• %{00018} is field code for "Project key"
• %{00000} is field code for "Summary" 
• %{00014} is field code for "Issue type"
• {00058} is code for numeric value of "Ephemeral number 1" 

project = "%{00018}" AND issuetype = "%{00014}" AND summary ~ "\"%{00000}\""

Once configured, transition looks like this:

Configuration Parameters

Parameter "JQL Query"

This parameter is a JQL query which can contain field codes in format %{nnnnn}. This query will be run when the validator is invoked by transition execution, but previously all field codes will be replaced with its corresponding value. In most cases these field codes are used to refer to current issue, current user, current project, current date and time, etc.
As a result of JQL query execution we get a set of issues, and we will make our condition or validator depend in a certain way of them.

When you write your JQL for selecting the issues you want to write, take into account the following advices:

• If field values are expected to have white spaces or JQL reserved words or characters, you should write field code between quotes (double or simple). 
  Example: summary ~ "%{00021}" will return issues with current user's full name. As full name can contain spaces, we have written the field code between double quotes.

• In general we will write field codes between quotation marks, since in most cases it doesn't hurt and it's useful for coping with field values containing white spaces or reserved JQL words. Anyway, there is an exception to this general rule: when our field contains a comma separated list of values, and we want to use it with JQL operator IN. In those cases we will not write the field code between quotes, since we want the content of the field to be processed as a list of values, not as a single string value.
  
  Example: Let's assume that "Ephemeral string 1" (field code %{00061}) contains a comma separate list of issue keys like "CRM-1, HR-2, HR-3". JQL Query: issuekey in ("%{00061}") will be rendered in runtime like issuekey in ("CRM-1, HR-2, HR-3"), which is syntactically incorrect. On the other hand, JQL Query: issuekey in (%{00061}) will be rendered in runtime like issuekey in (CRM-1, HR-2, HR-3), which is correct.

Disabling JQL Syntax Pre-Checking:

When we enter our JQL query, a syntax pre-checking is carried out in order to verify that it's correctly written. But when we insert field codes in our JQL query, the definitive form of the query that will be executed is unknown, since it depends on the actual values of the fields in runtime. In these cases the syntax pre-checking is done with speculative values given to the fields, and it might happen that fake syntax errors are reported. In order to inhibit the JQL syntax pre-checking you should enter // at the beginning of the line. Those characters will be removed in the actual JQL query that will be executed.

Example:

Parameter "Condition"

This parameter sets the way we want to make our condition or validator depend of the result of the JQL query:

• current issue belongs to output of the query: if current issue is among issues returned by the JQL query.
• current issue doesn't belong to output of the query: if current issue is not among issues returned by the JQL query.
• number of issues returned by the JQL query...: depending on the number of issues returned by the JQL query. This dependence is set in the next parameter "Mathematical expression".

Parameter "Mathematical expression"

This is a boolean expression for evaluating the number of issues returned by the JQL query. The number of issues returned is stored in virtual field "Ephemeral number 1" (field code {00058}).

Syntax of these expressions is the same as used for Boolean condition and validator with math. date-time or text-string terms.

Additional parameters:

• Run as: JIRA user post-function is going to be executed as. This parameter can be set to a fixed user (e.g. "john.nash"), or to a user field (e.g. "Reporter", "Assignee", etc). This parameter is particularly important in this feature since JQL query will return issues according to the browse permission this user has in the different project of the instance of JIRA.

• Message to show when validation fails: This parameter is only available in the validator form of this feature. It's a custom message to explain the user the cause that is preventing him from executing the transition.
  Translations* to every language installed in the JIRA instance can be optionally entered.
  In Condition based on JQL query the transition is simply hidden whenever condition isn't satisfied, so this parameter is not present.