Custom Validators
Use the Custom script validator to run an embedded script that determines whether an issue should be permitted to transition to a particular status within a workflow. This validator allows you to write Groovy scripts that can evaluate a wide range of conditions based on issue fields, workflow states, project properties, user permissions, and other contextual data.
With the introduction of HAPI, you can do what the Custom script validator does but in fewer lines when using our Simple Scripted Validator built-in workflow function. We therefore recommend using the Simple scripted validator over the Custom script validator where possible.
If you need help writing your script, check out the Scripting tips page.
Use this validator
Validator exceptions
You can use the InvalidInputException to block a workflow transition if certain validation criteria are not met. This exception can also be used to provide feedback to the user about what needs to be corrected before the transition can proceed.
The Simple Scripted Validator has a UI where you specify what field to apply the error message to. We recommend using the Simple scripted validator over the Custom script validator where possible.
Set a specific field in error
When you want to indicate that there's an issue with a particular field, you can throw an InvalidInputException and specify the field and the error message. For example:
import com.opensymphony.workflow.InvalidInputException
throw new InvalidInputException("resolution", "Resolution must not be fixed if not specifying a fix-version")
This constructor of InvalidInputException takes two arguments; the ID of the field that has the error and the error message to display. When the exception is thrown, Jira will prevent the transition and display the specified error message next to the resolution field on the transition screen:
Apply a general error message
If the error is not specific to a single field, you can throw an InvalidInputException with just an error message:
throw new InvalidInputException("Some combination of multiple fields are in error")
In this case, the error message will be displayed at the top of the transition screen or as a general error message, not associated with any particular field.
Step-by-step instructions
- Go to Administration > Issues > Workflows.
- Select Edit on the workflow you want to add a condition to.
- Select the transition to which you wish to add a condition.
- Under Options, select Validators.
- On the Transition page, select Add validator.
- Select Custom script validator [ScriptRunner].
- Select Add.
- Optional: Enter a note that describes the validator. This is for your own reference.
Enter an inline script of your choice.
- Optional: Select Preview.
Select Update.
Select Publish and choose if you want to save a backup copy of the workflow.
You can now test to see if this workflow validator works.
Example
Require Fix Version if the Resolution is Fixed
You can use the following script to require the user to enter at least one Fix Version if the Resolution is Fixed:
import com.opensymphony.workflow.InvalidInputException
if (issue.resolution.name == "Fixed" && !issue.fixVersions) {
throw new InvalidInputException("fixVersions",
"Fix Version/s is required when specifying Resolution of 'Fixed'")
}
This example is easier using Simple Scripted Validator. As stated previously, we recommend using the Simple scripted validator over the Custom script validator.