Customise and extend your workflows using complex scripts to support or enforce your business processes.

Introduction

Modify or create a new workflow.

Add a new condition, post-function, validator, of the correct type, eg "Script Validator".

Most of the built-in workflow functions can be customised with Condition code or Additional actions code, so if you can use a built-in script, you should.
Example 1. Where to put your scripts?

Give either the absolute path of the script, or path relative to one of your script roots. Relative paths are more portable and make switching servers easier.

If your scripts/classes have a package declaration, obviously, you will need the correct directories under there.

Simple built-in scripts like Simple Scripted Validator can be used to avoid most of the boilerplate in writing a validator function.

Script Binding

For each type of workflow function, the plugin will provide the current issue and transientVars in the script binding. That means you can refer to them using these variables, without declaring them.

log.debug issue.getKey()

If you use Intellij IDEA, you can add a dynamic property for these variables of the correct type. Alternatively you can just redeclare it with type information:

import com.atlassian.jira.issue.Issue;
Issue issue = issue

Conditions

Condition functions define whether an action is visible and available for a particular issue. JIRA runs condition functions more often than you would expect, so avoid doing any long processing in them.

Set the variable passesCondition to true or false depending on whether you want the action to be permitted or not. Note that passesCondition defaults to true, so if it is unset in your script, then the action will be permitted.

Avoid complex scripts with heavy processing requirements, as the condition is evaluated by JIRA several times if it is applicable instead of once.

Instead of a custom condition you may prefer to use Simple Scripted Condition, where you can just return true or false

See conditions examples.

Validators

To disallow the transition you throw a new InvalidInputException (com.opensymphony.workflow.InvalidInputException).

This has constructors for specifying a general error message, and for applying an error message to a particular field. For example, to set the resolution field in error:

import com.opensymphony.workflow.InvalidInputException

throw new InvalidInputException("resolution", "Resolution must not be fixed if not specifying a fix-version")
resolution error

To apply a general error message:

throw new InvalidInputException("Some combination of multiple fields are in error")
multiple error
Instead of a custom validator you may prefer to use Simple Scripted Validator, which has a UI where you specify what field to apply the error message to.

Post-Functions

Post-functions execute after the transition has been validated. Here is the place where you can pass on a message to a downstream system, send custom notifications or modify the issue etc.

The order of the post functions is important. For example a post function that changes the description of the issue - issue.setDescription("A new description") - should be placed before the Update change history for an issue and store the issue in the database step and a fast track transition an issue after the Fire Event step.

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

Ask a question about ScriptRunner for JIRA, for for Bitbucket Server, or for Confluence.