How to create and configure a validated custom field

1. Go to the custom fields management screen (/secure/admin/ViewCustomFields.jspa).

2. Click “Create custom field”.

3. Go to the “Advanced” tab, and select one of the validated custom fields.
   
   

   Open

   

4. Enter the field name and description.

5. Find the newly created field on the list, click the three dots “…”, and select “Contexts and default value”.

6. To configure the field in a selected context, click “Edit custom field config”.
   
   

   Open

   

7. Select the rules you want to apply when the field is edited and click “Save and close”.
   
   

   Open

   

Validated custom field types

The following custom field types are available. They are all available in JQL, REST API, boards, dashboards, reports, and all other places in Jira that fields are used in.

Different validation rules for values are available, depending on the field’s type.

Edit permissions can be defined for all of these fields.

Validated String Field

The field stores values as single-line strings.

Validated Single Select Field

The field stores values as single-line strings, but during edition allows the user to select the value from a predefined list. Configure the values to populate the list by adding the Value is one of rule.

Validated Number Field

The field stores values as integer number.

Validated Date Time Field

The field stores dates with time. With validation rules, you can define how far into the past or into the future the date can be.

Validated User Field

The field stores users. Offers user auto-complete during edit and when searching in JQL.

Validated Users Field

The field stores a list of users. Offers user auto-complete during edit and when searching in JQL.

Validated Group Field

The field stores groups. Offers user auto-complete during edit and when searching in JQL.

Validated Groups Field

The field stores a list of groups. Offers group auto-complete during edit and when searching in JQL.

Combining validation rules

Multiple rules can be defined for a field. They are all joined with the logical AND operator, meaning that all must pass for the value to pass validation.

The significance of AND

Some rules allow any argument to be true to pass. For example, the User in group rule allows you to select multiple groups, and will pass if the user belongs to any of the selected groups. But in may happen that you need to ensure that the user must belong to all groups from a given set. Such rules can be selected multiple times for one field, and since all rules are joined with AND, they will all have to pass for the whole validation to pass, allowing you to combine OR (within one rule) and AND (across rules) to match your needs.

Validation rule types

Below is a list of all validation rules available in the app.

Note that not all rules are available for all custom field types. For example, rules that control the number of items on the list are available only for multi-value fields.

Value matches regular expression

Checks that the value matches the given regular expression.

The whole value must match for the rule to pass. If you want to match only a sub-string, start your expression with .* and end with .*.

Matching is case-sensitive.

On the configuration page, the text will turn red if the regular expression is invalid.

Here are some useful examples to get you started:

• [0-9]*, matches texts that consist only of digits

• [1-9][0-9]*, matches integer numbers (a non-zero digit followed by zero or more digits)

• [a-zA-Z]+@[a-zA-Z]+\.[a-zA-Z]+, is a simple pattern that matches email addresses with both lower- and upper-case letters.

• \w+@\w+\.\w+, is also a pattern for email addresses, but written in a more concise manner, using the special \w character class, which denotes any letter or digit. You can find all available character classes here: https://docs.oracle.com/javase/tutorial/essential/regex/pre_char_classes.html.

• Note that those were just toy examples. Writing a regular expression that can actually match all valid emails is not an easy feat, see https://stackoverflow.com/questions/201323/how-can-i-validate-an-email-address-using-a-regular-expression.

To recap:

• . matches any character,

• * denotes that the preceding expression may occur zero or more times,

• + denotes that the preceding expression may occur one or more times,

• \. matches the literal dot “.” character (we add `\` to differentiate it from the . wildcard),

• \w denotes any letter or number,

• [a-z] matches any letter between “a” and “z” in the alphabet.

This short crash course should get you started with writing your own regular expressions. For diving deeper we recommend checking some on-line resources on regular expressions, for example, the Wikipedia page: Regular expression.

Value doesn't match regular expression

Checks that the value does not match the given regular expression. Matching is case-sensitive.

Value is one of

Checks that the value is equal to one of the given values.

Value is not one of

Checks that the value is different from all the given values.

Length greater than

Checks that the length of the value (number of characters that comprise the string, or number of digits in a number) is greater than the given number.

Length less than

Checks that the length of the value (number of characters that comprise the string, or number of digits in a number) is less than the given number.

Value greater than

Checks that the number value is greater than the given number.

Value less than

Checks that the number value is less than the given number.

Value in group

Applicable to user custom fields. Checks that the selected user belongs to one of the given groups.

Value not in group

Applicable to user custom fields. Checks that the selected user doesn’t belong to any of the given groups.

Max number of values

Applicable to multi-value fields. Checks that the value comprises at most the given number of items.

Min number of values

Applicable to multi-value fields. Checks that the value comprises at least the given number of items.

At most N days in the past

Applicable to date time fields. Checks that the date is no older than the given number of days.

Set this number to 0, to allow only future dates.

At most N days in the future

Applicable to date time fields. Checks that the date is not farther into the future than the given number of days.

Set this number to 0 to allow only past dates.

Permission rules

These rules control who can edit the field.

Note that they are joined with the AND operator, so anyone who wants to edit a field, must comply with all of the permission rules defined for the field.

User in set

Checks that the user who edits the field is one of the given users.

Leaving this empty means that no-one will be allowed to edit the field.

User not in set

Checks that the user who edits the field is different than any of the given users.

User in group

Checks that the user who edits the field belongs to one of the given groups.

Leaving this empty means that no-one will be allowed to edit the field.

If you want to ensure that the user belongs to more than one group simultaneously, add this rule one time for each required group.

User not in group

Checks that the user who edits the field doesn’t belong to any of the given groups.

User in role

Checks that the user plays any of the issue roles from the selected set:

• Creator – user who created the issue.

• Reporter – user who reported the issue (this is usually the same as Creator, but can be modified to point to anyone, whereas Creator is an immutable system field).

• Assignee – user who is assigned to work on the issue.

• Commenter – any user who commented on the issue.

Note that it’s enough for the user to have any chosen role for the rule to pass. For example, selecting Reporter and Assignee in the rule means that both issue reporters and assignees can modify the field. If you want only reporters who are also assignees to modify the field, add two separate rules like this:

Open

Thanks to this you can freely chose all possible combinations of roles joined by all logical operators.

User mentioned in a comment by

Checks that the user was mentioned in a comment written by any of the provided users. This can be useful for implementing “sign-off” kind of workflows.

If you want more than one user to have to write a comment, add this rule one time for each required user.