Skip to main content

Workflow Conditions

Compatibility

This module is available in Script Master for Jira only.

Overview​

Script Master provides advanced workflow conditions for Jira Cloud. These conditions check requirements before enabling workflow transitions. They include checks like ensuring a summary starts with specific characters, verifying field populations, requiring a PDF attachment, or restricting transitions to certain users. Script Master uses the Jira Expressions for these conditions. Users can create and edit these conditions through the Script Master interface by navigating to the workflow, selecting the condition type, and configuring the necessary expressions.

Scripted Conditions implements Forge Jira workflow condition module.

Context​

Jira Expressions use JavaScript-like syntax. They support a subset of JavaScript constructs and features, here is a brief overview of some of the main ones:

  • user (User): The user the condition is evaluated for.
  • issue (Issue): The work item selected for the transition.
  • project (Project): The space the work item belongs to.
  • transition (Transition): The transition that the condition is being evaluated against.
  • workflow (Workflow): The workflow that contains the condition.
  • config (JSON): The condition's saved configuration.
  • groupOperator (String): How this condition is combined with the others on the transition: AND, OR, or null when it is the only one.

On a Jira Service Management transition you also get:

  • customerRequest (CustomerRequest): The customer request selected for the transition.
  • serviceDesk (ServiceDesk): The service desk the customer request belongs to.

A condition has no originalIssue. That variable exists for validators only, because only a validator runs after the transition screen has been filled in.

A condition must return a boolean​

A condition controls whether the transition is offered at all. Jira makes the transition available only when the expression returns true, and treats everything else as false:

The expression returnsWhat happens
trueThe transition is available.
falseThe transition is hidden.
A string, a number, or any other valueThe transition is hidden. The value is not shown anywhere.
Nothing, because the expression failedThe transition is hidden.

A condition cannot show a message. Returning a string hides the transition exactly as false does, and the string is discarded. To block a transition and tell the user why, use a workflow validator instead.

Configuration​

Before you start, you need the Administer Jira global permission to edit a workflow.

  1. Go to Settings > Issues > Workflows.
  2. Select Edit on the workflow, then select the transition you want to restrict.
  3. In the rules panel, select Add restrict transition rule.
  4. Select Scripted Condition, then select Select. The Script Master editor opens in the Add Rule dialog.
  5. Write your Jira expression, and test it against a real work item.
  6. Select Add. The rule is attached to the transition.
  7. Select Update workflow to publish the change.

To change a rule later, open it from the same rules panel. The Edit Rule dialog opens on a read-only Summary tab rather than on the editor: it confirms the rule is configured, and expand shows the script. Select the Edit tab to change the expression, then confirm with Update.

A rule you have not written an expression for says so on the Summary tab, and does not affect the workflow until you do.

All available scripted extensions are listed in the Workflow section of Script Master.

Check expression syntax​

While you type, Script Master asks Jira to parse and type-check the expression and reports the result under the editor: whether it is valid, the return type Jira inferred, and any syntax error with the line and column where parsing stopped. Because a condition must return a boolean, Script Master warns you whenever the inferred type is anything else.

Jira reports the type Any for an expression whose branches return different types. That is expected, and Script Master says nothing about it.

Test an expression before you save it​

Script Master evaluates your expression against a real work item and tells you whether the transition would be available.

Before you start:

  • You need the Administer Jira global permission to edit a workflow.
  • You need permission to browse the work item you test against.
  1. Turn on Test with Issue below the expression editor. The test panel opens.
  2. Search for a work item by key or summary, and select it.
  3. Select Test expression. Jira evaluates the expression against that work item.
  4. Read the result. It states whether the transition would be available or hidden.

Two limits are worth knowing.

The test runs as you. user is your own account and every permission check uses your access, so a user with different permissions can get a different result.

transition, workflow and groupOperator exist only while Jira runs the transition. Script Master warns you when your expression uses one of them, because the test leaves it unset and the expression fails there even though it may work in the workflow.

Examples​

Allowed Issue Types​

Transition is visible only if the work type is included in the allowed list.

['Bug', 'Task'].includes(issue.issueType.name)

Current User Comment Verification​

Transition is visible only if the work item has a comment from the current user.

issue.comments
  .filter(c => c.author.accountId == user.accountId)
  .length > 0

Stricter When Combined With OR​

groupOperator tells the condition how it is joined to the other conditions on the transition. This example asks for more when the condition is one of several alternatives.

groupOperator == 'OR'
    ? issue.assignee != null && issue.priority.name == 'Highest'
    : issue.assignee != null