(For more resources related to this topic, see here.)

For workflow transitions that have transition screens, you can add validation logic to make sure what the users put in is what you are expecting. This is a great way to ensure data integrity, and we can do this with workflow validators.

In this recipe, we will add a validator to perform a date comparison between a custom field and the issue’s create date, so the date value we select for the custom field must be after the issue’s create date.

Getting ready

For this recipe, we need to have the JIRA Suite Utilities add-on installed. You can download it from the following link or install it directly using the Universal Plugin Manager:

https://marketplace.atlassian.com/plugins/com.googlecode.jira-suiteutilities

Since we are also doing a date comparison, we need to create a new date custom field called Start Date and add it to the Workflow Screen.

How to do it…

Perform the following steps to add validation rules during a workflow transition:

1. Select and edit the workflow to configure.
2. Select the Diagram mode.
3. Select the Start Progress transition and click on the Validators link towards the right-hand side.
4. Click on the Add validator link and select Date Compare from the list.
5. Select the Start Date custom field for This date, > for Condition, and Created for Compare with, and click on Update to add the validator:

   

6. Click on Publish Draft to apply the change.

After we add the validator, if we now try to select a date that is before the issue’s create date, JIRA will prompt you with an error message and stop the transition from going through, as shown in the following screenshot:

How it works…

Validators are run after the user has executed the transition but before the transition starts. This way, validators can intercept and prevent a transition from going through if one or more of the validation logics fail.

If you have more than one validator, all of them must pass for the transition to go through.

See also

Validators can be used to make a field required only during workflow transitions.

Creating custom workflow transition logic

In the previous recipe, we have looked at using workflow conditions, validators, and post functions that come out of the box with JIRA and from other third-party add-ons.

In this recipe, we will take a look at how to use scripts to define our own validation rules for a workflow validator. We will address a common use case, which is to make a field required during a workflow transition only when another field is set to a certain value.

So, our validation logic will be as follows:

• If the Resolution field is set to Fixed, the Solution Details field will be required
• If the Resolution field is set to a value other than Fixed, the Solution Details field will not be required

Getting ready

For this recipe, we need to have the Script Runner add-on installed. You can download it from the following link or install it directly using the Universal Plugin Manager:

https://marketplace.atlassian.com/plugins/com.onresolve.jira.groovy.groovyrunner

You might also want to get familiar with Groovy scripting (http://groovy.codehaus.org).

How to do it…

Perform the following steps to set up a validator with custom-scripted logic:

1. Select and edit the Simple Workflow.
2. Select the Diagram mode.
3. Click on the Move to Backlog global workflow transition.
4. Click on the Validators link from the panel on the right-hand side.
5. Click on Add validator, select Script Validator from the list, and click on Add. Now enter the following script code in the Condition textbox:

   import com.opensymphony.workflow.InvalidInputException
   import com.atlassian.jira.ComponentManager
   import org.apache.commons.lang.StringUtils
   def customFieldManager = 
     ComponentManager.getInstance().getCustomFieldManager()
   def solutionField = 
     customFieldManager.getCustomFieldObjectByName("Solution 
     Details")
   def resolution = issue.getResolutionObject().getName()
   def solution = issue.getCustomFieldValue(solutionField)
   if(resolution == "Fixed" && StringUtils.isBlank(solution))
   {
     false 
   } else {
     true
   }

6. Enter the text “You must provide the Solution Details if the Resolution is set to Fixed.” for the Error field.
7. Select Solution Details for Field.
8. Click on the Add button to complete the validator setup.
9. Click on Publish Draft to apply the change.

Your validator configuration should look something like the following screenshot:

Once we add our custom validator, every time the Move to Backlog transition is executed, the Groovy script will run. If the resolution field is set to Fixed and the Solution Details field is empty, we will get a message from the Error field as shown in the following screenshot:

How it works…

The Script Validator works just like any other validator, except that we can define our own validation logic using Groovy scripts. So, let’s go through the script and see what it does.

We first get the Solution Details custom field via its name, as shown in the following line of code. If you have more than one custom field with the same name, you need to use its ID instead of its name.

def solutionField = customFieldManager.getCustomFieldObjectByName("Solution 
  Details")

We then select the resolution value and obtain the value entered for Solution Details during the transition, as follows:

def resolution = issue.getResolutionObject().getName()
def solution = issue.getCustomFieldValue(solutionField)

In our example, we check the resolution name; we can also check the ID of the resolution by changing getName() to getId().

If you have multiple custom fields with the same name, use getId().

Lastly, we check whether the Resolution value is Fixed and the Solution Details value is blank; in this case, we return a value of false, so the validation fails. All other cases will return the value true, so the validation passes. We also use StringUtils.isBlank(solution) to check for blank values so that we can catch cases when users enter empty spaces for the Solution Details field.

There’s more…

You are not limited to creating scripted validators. With the Script Runner add-on, you can create scripted conditions and post functions using Groovy scripts.

Summary

In this article, we studied how to work with workflows, including permissions and user input validation.

Resources for Article:

---

Further resources on this subject:

• Getting Started with JIRA 4 [Article]
• Gadgets in JIRA [Article]
• Advanced JIRA 5.2 Features [Article]

---