Validating user input in workflow transitions

Exclusive offer: get 50% off this eBook here
JIRA 6.x Administration Cookbook

JIRA 6.x Administration Cookbook — Save 50%

Over 100 hands-on recipes to help you efficiently administer, customize, and extend your JIRA 6 implementation

$29.99    $15.00
by Patrick Li | July 2014 |

In this article by Patrick Li, author of JIRA 6.x Administration Cookbook, we will cover one of the most powerful features in JIRA, with recipes that show you how to work with workflows, including permissions and user input validation.

(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:


JIRA 6.x Administration Cookbook Over 100 hands-on recipes to help you efficiently administer, customize, and extend your JIRA 6 implementation
Published: July 2014
eBook Price: $29.99
Book Price: $49.99
See more
Select your format and quantity:

About the Author :


Patrick Li

Patrick Li is the cofounder and senior engineer of AppFusions. AppFusions is the leading Atlassian partner specializing in integration solutions with many enterprise applications and platforms, including IBM Connections, Jive, Google Apps, Box, SugarCRM, and more.

He has worked in the Atlassian ecosystem for over five years, developing products and solutions for Atlassian platform and providing expert consulting services. He is one of the top contributors to the Atlassian community, providing answers and suggestions on the Atlassian user forum.

He is extensively experienced in designing and deploying Atlassian solutions from the ground up, and customizing existing deployments for clients across verticals such as Healthcare, Software Engineering, Financial Services, and Government Agencies.

Books From Packt


JIRA 5.x Development Cookbook
JIRA 5.x Development Cookbook

JIRA 5.2 Essentials
JIRA 5.2 Essentials

JIRA Development Cookbook
JIRA Development Cookbook

JIRA 4 Essentials
JIRA 4 Essentials

Atlassian Confluence 5 Essentials
Atlassian Confluence 5 Essentials

SELinux System Administration
SELinux System Administration

Microsoft SharePoint 2010 Administration Cookbook
Microsoft SharePoint 2010 Administration Cookbook

Moodle Administration
Moodle Administration


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software