Go to the custom fields management screen (/secure/admin/ViewCustomFields.jspa
).
Click “Create custom field”.
Go to the “Advanced” tab, and select one of the validated custom fields.
Enter the field name and description.
Find the newly created field on the list, click the three dots “…”, and select “Contexts and default value”.
To configure the field in a selected context, click “Edit custom field config”.
Select the rules you want to apply when the field is edited and click “Save and close”.
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.
The field stores values as single-line strings.
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.
The field stores values as integer number.
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.
The field stores users. Offers user auto-complete during edit and when searching in JQL.
The field stores a list of users. Offers user auto-complete during edit and when searching in JQL.
The field stores groups. Offers user auto-complete during edit and when searching in JQL.
The field stores a list of groups. Offers group auto-complete during edit and when searching in JQL.
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.
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.
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.
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: https://en.wikipedia.org/wiki/Regular_expression.
Checks that the value does not match the given regular expression. Matching is case-sensitive.
Checks that the value is equal to one of the given values.
Checks that the value is different from all the given values.
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.
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.
Checks that the number value is greater than the given number.
Checks that the number value is less than the given number.
Applicable to user custom fields. Checks that the selected user belongs to one of the given groups.
Applicable to user custom fields. Checks that the selected user doesn’t belong to any of the given groups.
Applicable to multi-value fields. Checks that the value comprises at most the given number of items.
Applicable to multi-value fields. Checks that the value comprises at least the given number of items.
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.
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.
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.
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.
Checks that the user who edits the field is different than any of the given users.
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.
Checks that the user who edits the field doesn’t belong to any of the given groups.
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:
Thanks to this you can freely chose all possible combinations of roles joined by all logical operators.
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.