Skip to end of metadata
Go to start of metadata

Availability

This feature is available for the Jira server deployment option only. We plan to add it to the Cloud version in the near future.

Validators check that any input available to the transition (such as user-supplied input) is valid before the transition is performed. If a transition's validator 'fails', the transition's post functions will not be executed and the issue will not progress to the destination step of the transition.

You can use Power Scripts™ for Jira and SIL™ to define a large set of validators beside the default validators offered by Jira, by just adding a (k) SIL™ Validator to a transition and publishing the workflow, as described here.

Below are just a few common examples:

Required apps

Power Scripts™ for Jira (server)

Level: BASIC

Comment required

A validator that forces users to enter a comment during a transition, otherwise displaying a customized error message:

SIL Code
string errorMsg = "You must enter a comment!";
if(!hasInput("comment")) {
   return false, "comment", errorMsg;
}

Field has single value

A SIL™ validator for checking if a multi-valued field does not contain more than one value during a transition:

SIL Code
string errorMsg = "You must choose a single fix version!";
if(size(fixVersions) > 1) {
   return false, "fixVersions", errorMsg;
}

Parent status

A SIL™ validator which ensures that the current issue's parent issue is in one of the specified Statuses:

SIL Code
string[] statuses = {"Opened", "Reopened"};
string errorMsg = "Parent issue should have status Opened or Reopened!";
if(!isNull(parent) && !elementExists(statuses, parent.status)) {
   return false, errorMsg;
}

Validation based on regular expression

A SIL™ validator which checks if a text field matches a regular expression (eg for a social number):

SIL Code
string errorMsg = "Invalid social number format.";
string REGEXP = "^\\d{3}-\\d{2}-\\d{4}$"; 
if(!matches(customfield_10100, REGEXP)) {
   return false, "customfield_10100", errorMsg;
}

Force a custom field to be required if another field was set to a certain value

A SIL™ validator which makes custom field Product with id customfield_10200 required in the resolve screen only if the resolution was set to Fixed:

SIL Code
string errorMsg = "To resolve the issue as 'Fixed' you should give a value to field 'Product'.";
if(resolution == "Fixed" && !hasInput("customfield_10200")) {
   return false, "customfield_10200", errorMsg;
}

In a similar way, you can make any custom field required based on another custom field value:

SIL Code
string errorMsg = "The Address field is required.";
if(customfield_10100 == "Yes" && !hasInput("customfield_10200")) {
   return false, "customfield_10200", errorMsg;
}

In the above example we assume that the field with id customfield_10100 is a select list with options Yes and No, and when Yes option is selected, field Address with id customfield_10200 should be required.

Ensure that the issue has at least one attachment

A SIL™ validator which checks if an issue has any file attached during a transaction:

SIL Code
string errorMsg = "At least one file must be attached to the issue.";
if(size(attachments) == 0) {
   return false, errorMsg;
}

Validation on linked issues

Blocking Start Progress transition whenever current issue has a link of type Blocks with an issue in a status different from Resolved and Closed:

SIL Code
string errorMsg = "Progress can't start because there is at least one blocking issue.";
string[] statuses = {"Resolved", "Closed"};
string[] blockingIssues = linkedIssues(key, "Blocks");
for(string issue in blockingIssues) {
    if(!elementExists(statuses, %issue%.status)) {
       return false, errorMsg;
    }
}

Forbidding issue links of types Blocks and Cloners with issues of type Bug:

SIL Code
string errorMsg = "Issue links of types 'Blocks' and 'Cloners' with 'Bugs' are forbidden.";
string[] links = {"Blocks", "Cloners"};
for(string link in links) {
    string[] linkedIssues = linkedIssues(key, link);
    for(string issue in linkedIssues) {
        if(%issue%.issueType == "Bug") {
           return false, errorMsg;
        }
    }
}

Validation on non-linked issue

Preventing a transition from being executed if the rest of issues in the project aren't closed:

SIL Code
string errorMsg = "There are still unclosed issues in the current project.";
string[] issues = selectIssues("project = " + project + " AND status != Closed AND key != " + key);
if(size(issues) > 0) {
   return false, errorMsg;
}

Validation based on mathematical expression

A SIL™ validator which checks if a numeric custom field is greater than or equal to 0:

SIL Code
string errorMsg = "The number should be greater or equal to 0";
if(sign(customfield_10101) == -1) {
   return false, "customfield_10101", errorMsg;
}

The sign routine determines the sign of a number. It returns 1 if the number is positive, zero (0) if the number is 0, and -1 if the number is negative.

More useful mathematical routines can be found in the Math routines section.

Validation based on date-time expression

A SIL™ validator which checks if due date is before current date:

SIL Code
string errorMsg = "The due date of the issue was exceeded!";
if(dueDate < currentDate()) {
   return false, "duedate", errorMsg;
}

More useful date routines can be found in the Date Routines section.

Compare two parsed texts

A SIL™ validator which checks if description contains summary:

SIL Code
string errorMsg = "Description must contain summary";
if(!contains(description, summary)) {
   return false, "description", errorMsg;
}

Users in a field are/aren't in a project role

A SIL™ validator which checks if users selected in a multi user picker custom field are in a given project role:

SIL Code
string PROJECT_ROLE = "Developers";
for(string user in customfield_10500) {
    if(!isUserInRole(user, project, PROJECT_ROLE)) {
       string errorMsg = "User " + user + " is not in project role " + PROJECT_ROLE;
       return false, "customfield_10500", errorMsg;
    }
}

A custom field is/isn't initialized

A SIL™ validator which checks if a custom field is initialized during transaction:

SIL Code
string errorMsg = "Field was not initialized!"; 
if(!hasInput("customfield_10500")) { 
   return false, "customfield_10500", errorMsg; 
}

Check user property

A SIL™ validator which checks if a user property has a certain value:

SIL Code
string COUNTRY = "Romania";
string errorMsg = "Assignee country must be " + COUNTRY; 
if(getUserProperty(assignee, "country") != COUNTRY) { 
   return false, "assignee", errorMsg; 
}

See also