JQL Precondition

JSU for Jira Cloud

This is the documentation of JSU for Jira Cloud. If you are using JSU on Jira Server or on Jira Data Center, you can find the documentation here.


The 'JQL Query' compares the number of issues returned from the JQL query against predefined conditions like

  • At least find 1 issue
  • Must not find any issue
  • Compare with a particular number

Some of the simple things you would do with the JQL Precondition, you might also achieve with the Value Field Precondition. Choose that approach, which might be the simplest for you and your Jira admin colleagues.

Check out our Top tips further down!


You must write the 'JQL Query' and choose one option about the number of issues found. For example:

With this precondition, the post function will be only executed for Bugs.
No more will you need a separate workflow (and special workflow scheme configuration), when you only want 1 post function to perform different for a particular issue type.

For information on how to configure workflows in JIRA, see the JIRA documentation.


See the JQL Use Cases for several examples.

How to write JQL Query

How to use placeholders for JQL in JSU

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:

Configuration in JSU
parent = {issue.Parent} AND component != {issue.Component/s} OR component is EMPTY 

it will be changed by JSU into something like this, before the search is executed:

Values after replacement
parent = 'ABC-123' AND component != 'Documentation' OR component is EMPTY 

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 bellow for further details 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 same as the JQL in JIRA. It is important to use 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.

Top tips

Fields on the current issue

Add the following to your JQL query:

... 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}
  • sub-tasks with the same parent: parent = {issue.parent}
  • excluding the current issue: key != {issue.key}

See JQL Use Cases for more examples.

Think carefully about what might be the result of your query

JQL in JSU can be very powerful. However you also must think very careful, what values might be used as replacement for the {issue.FIELD NAME} placeholders. Or what happens, if an issue has no value on such a field. There could be quite some variety in the data of your issues.

(warning) If you are not careful, the result of such a JQL query unexpectedly might contain hundreds of issue. Or the JQL query might fail, because the syntax has become invalid after the placeholders had been replaced.

Maximum Issues Allowed

You can set a limit for the maximum number of issues you expect from your JQL query (see also 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 issue.

By default this limit is 50. You cannot set any higher limit than 1000.

JQL Injection

(warning) Further you must be aware of potential 'JQL injection':
JSU does not check any value which 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 an additional criteria to your JQL query.

(info) We recommend not to use any text fields as placeholders. Or any other field, of which the user can freely change the text. Only use fields which can contain one/several of clearly defined values.

Syntax for Field Names

Field names in your JQL should be the same as in the Advanced Search. We suggest to use 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 Fields

System Fields names should be same as used in JQL. For example:

  • reporter
  • assignee
  • issuetype
  • priority

Custom Fields

Custom Fields names also should be same as used in JQL. For example:

  • Approver or  cf[10010]
  • Hosting Server or cf[12910]
  • Date to Join or cf[11000]

(info) 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

Replaceable value from issue must be between curly brackets like

{issue.FIELD NAME}

System Fields

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 Type}
  • {issue.Labels}
  • {issue.Original story points}
  • {issue.Parent}
  • {issue.Priority}
  • {issue.Project}
  • {issue.Rank}
  • {issue.Reporter}
  • {issue.Request participants}
  • {issue.Resolution}
  • {issue.Resolved}
  • {issue.Security Level}
  • {issue.Sprint}
  • {issue.Status}
  • {issue.Summary}
  • {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 all those 3 variant refer to the same field:

  • {issue.Affects Version/s}
    Label in the english Jira user interface.
  • {issue.versions}
    Technical field id. See also reference from Atlassian .
  • {issue.affectedVersion}
    JQL's way to refer to that field.

Custom Fields

You can use either the name of a custom field, or it's id. For example:

  • {issue.My Text Field}
  • {issue.customfield_12345}

However, the cf[12345] notation is not supported between curly brackets.

(info) If you have several custom fields with the same name, you must use the custom field id.

Supported Field Types

In its different modules (especially those for workflows), the JSU app supports many different field types. System fields, as well as custom fields.

However you should be aware, that not all field types or all combinations are supported. We think we cover the most important field types and are still continuously adding and improving which, and how different field types are supported. But the one you need might not work (yet). 

We recommend that you test JSU with fields to see if it is compatible with your system. Our evaluation license gives you 30 days free trial.