Using Forms Regex validation
Platform Notice: Cloud - This article applies to Atlassian products on the cloud platform.
Forms Text Fields can validate a wide range of text patterns using Regex validation. Regular Expressions (Regex) are sequences of characters that define a search pattern in text. They can be used to validate text based on complex criteria and match common text patterns like phone numbers and IP addresses. Regular expressions are both flexible and powerful, capable of matching virtually any text-based pattern you might want to include in a form.
Using Regex in Forms
When you create a text question, along with word/character limits, you can validate for Regex pattern matching. To validate a field with a Regex pattern, click the "Must match pattern" check box.
Next, add the expression you want to validate against. Then add the message your users will see if the validation fails.
If I need a full name field validator that only alphabetic letters are allowed and that is in the format of Name and Surname and accepts compound names.
For this, we will use the regex below:
^[a-zA-Z]+( [a-zA-Z]+)+$
This regex validator will work as shown on the screen recording below:
Description Property
You can save time for your users by including formatting instructions or examples in the question description.
Once you have created a form that uses Regex validation, be sure to test it. When the form is submitted, Forms will ensure that the Regex is valid. If the regex is not valid, you will see a message that says, "The regex pattern on this question is not valid. Answer unable to be validated". At this point, you need to return to the form builder and fix the regex pattern. If your form is deployed with an invalid regex, then users will not be able to submit the form.
For more information about JavaScript Regex Engine and how you can use it with Forms, please refer to the topics below:
Basics
The Regex engine used by Jira Forms is based on the JavaScript Regex Engine.
Character classes | Name | Description | Example Pattern | Example Match |
---|---|---|---|---|
. | Dot (wildcard) | any character except newline | . | forms is great |
\d | Digit | Matches any digit character (0-9). Equivalent to | file_\d\d | file_25 |
\w | Word | Matches any word character (alphanumeric & underscore). Only matches low-ascii characters (no accented or non-roman characters). Equivalent to | \w-\w\w\w | A-b_1 |
\s | Whitespace | White space: space, tab, newline | a\sb\sc | a b c |
\D | Not digit | Matches any character that is not a digit character (0-9). Equivalent to | \D | these-are-letters |
\W | Not word | Matches any character that is not a word character (alphanumeric & underscore). Equivalent to | \W | 12345 |
\S | Not whitespace | Matches any character that is not a whitespace character (spaces, tabs, line breaks). | \S | anything-without-whitespace |
Ranges and Sets | ||||
[abc] | Character set | Match any character in the set. | [airj] | jira |
[^abc] | Negated set | Match any character that is not in the set. | [airj] | confluence |
[a-g] | Range | Matches a character having a character code between the two specified characters inclusive. | [g-s] | ghijklmnopqrs |
[^a-g] | Not range | Matches a character not in the range. | [^g-s] | abcdeftuvwxyz |
Anchors | ||||
^ | Beginning | Matches the beginning of the string. This matches a position, not a character. | ^\w+ | she sells seashells |
$ | End | Matches the end of the string. This matches a position, not a character. | \w+$ | she sells seashells |
\b | Word boundary | Matches a word boundary position between a word character and non-word character or position (start / end of string) | s\b | she sells seashells |
\B | Not word boundary | Matches any position that is not a word boundary. This matches a position, not a character. | s\B | she sells seashells |
Groups & Lookaround | ||||
(abc) | Capturing group | Groups multiple tokens together and creates a capture group for extracting a substring or using a backreference. | (ha)+ | hahaha haa hah! |
\1 | Numeric reference | Matches the results of a capture group. For example | (\w)a\1 | hah dad bad dab gag gab |
(?=abc) | Positive lookahead | Matches a group after the main expression without including it in the result. | \d(?=px) | 1pt 2px 3em 4px |
(?!abc) | Negative lookahead | Specifies a group that can not match after the main expression (if it matches, the result is discarded). | \d(?!px) | 1pt 2px 3em 4px |
Quantifiers & Alternation | ||||
+ | Plus | Matches 1 or more of the preceding token. | b\w+ | b be bee beer beers |
Star | Matches 0 or more of the preceding token. | b\w* | b be bee beer beers | |
{1,3} | Quantifier | Matches the specified quantity of the previous token. | b\w{2,3} | b be bee beer beers |
? | Lazy | Makes the preceding quantifier lazy, causing it to match as few characters as possible. By default, quantifiers are greedy, and will match as many characters as possible. | b\w+? | b be bee beer beers |
| | Alternation | Acts like a boolean OR. Matches the expression before or after the |. It can operate within a group, or on a whole expression. The patterns will be tested in order. | b(a|e|i)d | bad bud bod bed bid |
Common Examples
Regular expressions are great for validating common input types in Jira Forms. So Forms currently includes validation for email addresses and URLs out-of-the-box. Further validation formats can be built using regex to make sure your forms always capture correctly formatted data.
Type of Input | Pattern | Example Match |
---|---|---|
Date format | ^(0?[1-9]|1[0-2])[\/](0?[1-9]|[12]\d|3[01])[\/](19|20)\d{2}$ | 10/2/2019 01/02/2019 10/2/19 10\1/2019 |
USD currency | ^(\$)(\d)+ | $10 $100000 $$$10 10$ $1.50 $10,000 |
IPv4 address | \b(?:(?:2(?:[0-4][0-9]|5[0-5])|[0-1]?[0-9]?[0-9])\.){3}(?:(?:2([0-4][0-9]|5[0-5])|[0-1]?[0-9]?[0-9]))\b | 192.168.0.1 255.255.255.255 192.168.0.1256.1.1 256.256.256.256 |
Phone number | ^\s*(?:\+?(\d{1,3}))?([-. (]*(\d{3})[-. )]*)?((\d{3})[-. ]*(\d{2,4})(?:[-.x ]*(\d+))?)\s*$ | 0400123000 +61 0400000000 610400000000+++ |
Advanced Usage
As stated above, the basics of regular expressions can be combined to achieved very useful input validation. Here are some examples of advanced pattern matches using regular expressions.
Type of Input | Pattern | Example Match |
---|---|---|
The letter "C" and 7 numeric characters | ^C\d{7}$ | C0000001 |
Alphanumeric with spaces allowed. Max length: 20 characters | ^[\w\d\s]{1,20}$ | 12345678912345678912 123456789123456789123 abcdefghijklmnopqrst abcdefghijklmnopqrstu |
Valid email address. Max length: 80 characters | ^(?=.{1,81}$)[\w\.-]+@[\w\.-]+\.\w{2,4}$ | placeholder@example.com placeholder@example placeholder@@@@example.com |
Valid email address from a specific domain and format. | ^[a-zA-Z]+\.[a-zA-Z0-9]+@example.com | john.doe@example.com john@example.com john.doe@otherdomain.com |
Country extension prefixed with a + and number with , no spaces, include area local area code | ^(?=.{1,30}$)\s*(?:\+?(\d{1,3}))?([-.(]*(\d{3})[-.)]*)?((\d{3})[-.]*(\d{2,4})(?:[-.x]*(\d+))?)\s*$ | +1-(800)-123-4567 +7 555 1234567 123-89-01 202 555 4567 |
Alphanumeric according to local reference table | ^[\u0410-\u042F]+[\u0410-\u042F]$ | АБВГДЕЖЗ hello |
Alphanumeric | ^\w{1,250}$ | 12345678weqweasdsad123123 |
2 letters, underline, 3 numeric | ^[A-z]{2}_[0-9]{3}$ | DK_003 ABC_000 |