Validators Tutorial

Your Jira workflows define the business processes associated with working on different issue types. Workflows can be simple or complex, and they can include several or few workflow functions. Depending on what your organization requires, you may want to use enhanced workflow validators provided by ScriptRunner. These script validators allow you to do more in your workflow, providing extra control or information.

All of the ScriptRunner workflows functions are found on the normal Workflows page of Jira Administration (Administration>Issues>Workflows), specifically by editing an existing workflow. Edit an existing workflow and click on the transition you wish to add a validator to, then Validators>Add Validator>Script Validator [ScriptRunner].

What is a Script Validator?

A script validator is a powered-up version of a standard Jira validator. Instead of using one of the basic validators that you find in Jira, you can run a script to validate your issue. Like other scripted workflow functions, ScriptRunner includes some built-in options, as well as a custom script, and a simple script option. Remember, a validator checks to see if the user can transition an issue, they don’t prevent the next transition button from appearing (that would be a script condition).

When you select Script Validator [ScriptRunner], you see several options on the Select Script page.

• Built-in Script Validators: ScriptRunner includes two built-in script validators that you can use without copying or pasting any scripts.

  • Require a Comment on Transition: This validator makes sure the user transitioning the issue enters a comment. You could use this validator to get background information on an issue that needs to transition to a Review status.

  • Field(s) Changed Validator: This validator makes sure the user updates a specified field. You can only select fields that appear on the transition screen for the issue.

• Simple Scripted Validator: This option is for inline scripts that are less complicated than the Custom Script option. Use a simple script that only checks if the transition should run or not run.

• Custom Script Validator Here you can upload your own script file or paste a script. These scripts are more complicated than the Simple Scripted Validators. If you aren’t quite a Groovy writer yet, you can copy and paste some example scripts found in Adaptavist’s ScriptRunner documentation and use them, or you can create your own. You can copy and paste code from the Adaptavist Library or create your own.

Examples of Script Validators

Field(s) Changed

Great Adventure needs every onboarding issue to show which department a new employee belongs to. To handle this requirement, they’ve been using components for each of the departments. Unfortunately, many users are transitioning the onboarding issues without updating the Component field first, so the issues are needing manual edits for the different departments. To help with this situation, Great Adventure plans to use a script validator to make sure users complete the Component field before they resolve an onboarding issue.

Add Field(s) Changed Validator

1. Access the project where you want to edit a workflow.

2. From the project, click Project settings>Workflows from the links on the side, or from the Summary page under Workflows.

3. On the Workflows page, find the workflow you want to edit, and click the pencil icon under Actions.

   1. On the Edit page, you see a good view of the workflow. In Diagram view, hover over the transition lines to see their names or select Show Transition Labels to display them permanently.

      If you want to work in Text view, you can see the transitions listed instead of appearing as lines between statuses.

4. Click the transition you want to edit to open the Options window.

5. Under Options, click Validators.

6. Click Add Validator.

7. Now you see the Add Validator to Transition page. From the list, select Script Validator [ScriptRunner], and then click Add.

8. On the Select Script page, select Field(s) Changed Validator.

   1. Now, you see some options for this built-in script. In the Note field, type a note for your reference.

   2. In the Fields menu, select a field that you want to be sure has changed. Great Adventure would use the Component field.

   3. Click Preview to see a statement that references what this script validator achieves.

   4. Click Update to add the script validator. Once you click Update, you see the Workflow Edit screen with your new validator.

9. The next step is to Publish the workflow and test it.

   For this particular script validator, the field you select in the Fields menu must be present on the transition screen associated with this transition. With this specific script validator, you also need a transition screen to capture that information. This screen does not have to be a resolution screen if you need to gather this information at a different point during the workflow.

Test Field(s) Changed Validator

1. At the top of the workflow edit screen, click Publish. A message appears about saving a backup of the current workflow.

   1. For this demo you may not need to, but we recommend you save backups in your daily work.

2. Select Publish to publish the workflow.

3. Now, you want to run some issues through to test this new process. Log in as a test user with access to the project that has your updated workflow.

4. Create an issue that uses the workflow you edited. Transition the issue to where you added the scripted validator.

5. When you click that transition and the transition screen appears, try to transition without changing the field you selected. It should not work.

6. Change the field and try and again and it should work.

This validator can be a useful reminder and an easy way to be sure that an issue is being updated as needed. If needed, users could still edit the field on the issue after it has transitioned.

Custom Script- Require Fix Version

In Great Adventure’s Software Development team, they use Fix Versions to track when the team resolves bugs in the products. Similar to the Component issue, many users forget to add the Fix Version when completing the issue. Great Adventure has decided to use a script validator in their Software Development project, so when a user sets the resolution to Fixed, they also have to add the correct Fix Version.

To add this validator, you just copy/paste the following code into the box that appears when you select the Custom Script Validator option on the Select Script page.

groovy
import com.opensymphony.workflow.InvalidInputException

if (issue.getResolution() == "Fixed" && ! issue.fixVersions) {
throw new InvalidInputException("fixVersions",
"Fix Version/s is required when specifying Resolution of 'Fixed'")
}

Like the built-in validator we discussed previously, this validator requires a transition screen. In this particular case you use a Resolution screen to capture the last bit of information to resolve the issue, but a different use-case might call for a screen on a different transition.

One thing to note if you are using sample scripts—​there may be items to change as you update your ScriptRunner version.