Workflow Functions Tutorial
ScriptRunner for Jira Server provides built-in and custom workflow functions. These workflow functions include built-in and custom validators, conditions, and post functions. ScriptRunner workflow functions allow you to do a lot more with your Jira workflows and further enhance your automation.
Explore the following sections within this page to learn more:
Jira workflow functions
As a reminder, a workflow is the series of steps through which a piece of work passes from conception to completion. In Jira, workflows are made up of two main parts; statuses and transitions. Statuses indicate that someone is working (or not working) on the issue, while transitions link statuses together. You can control several aspects of a transition's behavior in Jira. For instance, you can have:
- Conditions that check to make sure the user should be able to perform a transition.
- Validators which ensure that all needed changes have been made or that the changes that were made were valid.
- Post Functions that program automated actions after the transition is performed.
These workflow functions enable a level of automation in your projects. This automation keeps your teams focused on their work, while Jira takes care of the repetitive tasks your team doesn't need to focus on. However, you may find that Jira's basic workflow functions don't always do as much as you would like them to do—and that's where ScriptRunner workflow functions come in!
For more information on Jira Workflows, we recommend you familiarise yourself with the Atlassian documentation on workflows.
ScriptRunner workflow functions
For each of the Jira workflow functions, ScriptRunner for Jira provides built-in and custom workflow functions so that you have workflows that suit your exact needs. There are three main types of ScriptRunner workflow functions:
For example, you can use the All sub-tasks must be resolved built-in script condition to ensure that all sub-tasks have been resolved before the transition is allowed. See below for a full list of ScriptRunner workflow functions.
Available ScriptRunner workflow conditions
The following ScriptRunner conditions are available when you add a condition to a workflow transition:
| ScriptRunner conditions | Description |
|---|---|
| Simple scripted condition | Runs a simple embedded script to find out whether to show the action or not. |
| Custom script condition | Run your own Groovy script from a file or enter it into Jira. |
| All sub-tasks must be resolved | Do not allow the action unless all sub-tasks have a resolution set. You can choose any resolution: a named one or the same as the parent task. |
| Field(s) required condition | Allow the transition if required fields are completed. |
| Group(s) condition | Allow the transition if the current user is, or is not, a member of the specified group(s). |
| JQL query matches condition | Allow the transition if the current issue matches the provided JQL query. |
| Linked issues condition | Control the transition based on the status or resolution of linked issues or sub-tasks. |
| Checks the issue has been in a status previously | Require that this issue has been in the specified status either previously, or immediately prior. |
| Project role(s) condition | Allow the transition if the current user is, or is not, a member of the specified project role(s). |
| Regular expression condition | Check a system or custom field value that matches a regular expression. |
| User(s) condition | Allow the transition if the current user is, or is not, included in the list of users. |
| User in field(s) condition | Allow the transition if the current user is in the User or Group field. |
Available ScriptRunner workflow validators
The following ScriptRunner validators are available when you add a validator to a workflow transition:
| ScriptRunner validators | Description |
|---|---|
| Custom script validator | Run your own Groovy script from a file or enter it into Jira. |
| Simple scripted validator | Run a simple embedded script to find out whether to allow the transition or not. |
| Field(s) changed validator | Enforce that one or more fields are changed as part of the transition. |
| Require a comment on transition | Enforce that a comment is provided on transition. |
| Field(s) required validator | Allow the transition if Required fields are completed. |
| Regular expression validator | Make sure a system or custom field value matches a regular expression. |
| User in field(s) validator | Allow the transition if the current user is in the User or Group field. |
Available ScriptRunner workflow post functions
The following ScriptRunner post functions are available when you add a post function to a workflow transition:
| ScriptRunner post functions | Description |
|---|---|
| Custom script post-function | Run your own Groovy script from a file or entered into Jira. |
| Add/remove from sprint | Add/remove the issue to/from a sprint on transition. |
| Adds the current user as a watcher | Adds the user performing the action as a watcher, if condition applies. |
| Archive this issue | Archive the current issue, which can help improve performance. |
| Assign to last role member | Assign this issue to the last user from the specified role who this issue was assigned to previously. |
| Assign to first member of role | Assign to the first member of the specified role. |
| Clear field(s) | Clear selected fields. |
| Clones an issue, and links | Clones this issue to another issue, optionally another project and issue type, and creates a link. |
| Add a comment to this issue | Adds a templated comment to the current issue, as the user making the transition. |
| Copy field values | Copy field values from one field to another. |
| Create a sub-task | Create a sub-task. Will optionally reopen a matching sub-task. |
| Fast-track transition an issue | If the condition is met, automatically transition this issue to another status. |
| Fires an event when condition is true | Fires an event that can be picked up by a notification scheme, in order to send mail only under certain conditions, for example, Priority is Blocker. |
| Post a message to Slack | Allows you to define a customizable message to send to a Slack channel. |
| Transition parent when all sub-tasks are resolved | Transition the parent issue through the provided action when all sub-tasks are resolved. |
| Send a custom email | Send an email based on the provided template if conditions are met. |
| Set issue security level depending on provided condition | Sets the security level for an issue if the provided condition evaluates to true. |
| Adds a comment to linked issues when this issue is transitioned | Useful for alerting participants of other issues that a blocker is resolved, etc. This function should be put on the Resolve transition (or similar). |
Access ScriptRunner workflow functions
You can access ScriptRunner workflow functions as follows:
- Go to .
- Select Edit on the workflow you want to add a condition to.
- Select the transition you wish to add a the workflow function to.
- Under Options, select then workflow function or your choice.
Your next steps depend on if you edit a workflow condition, validator, or post function. We have provided you with examples for each in the section below.
Remember when editing a workflow, changes result in a draft that you must publish before you see them take effect in your workflow. Since you can use both built-in workflow functions and scripted workflow functions that you customize, there is a lot of flexibility to what you can do with ScriptRunner.
Walkthrough examples of ScriptRunner workflow functions
The following pages include simple examples for you to follow so you can better understand how ScriptRunner workflow functions work: