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.
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:
This might not work for issues where the summary contains special characters since the default search will be performed as a fuzzy search. You can perform an exact search, however, if you use the following syntax \"%{00000}\" project = "%{00018}" AND issuetype = "%{00014}" AND summary ~ "\"%{00000}\"" |
Once configured, transition looks like this:
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:
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.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.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:
This parameter sets the way we want to make our condition or validator depend of the result of the JQL query:
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.