App Email and Phone Number Input Guidance

Overview

There have been instances, where phone numbers or email addresses contain values that are not valid. This is because the input is a "Text" question without a Validation Condition or with a simple Validation Condition.  Fortunately, there is a solution. The app developer can use a regular expression to validate the input. 

Regular expressions are used frequently in Computer Science, but they are not something that you find in the real world. Wikipedia as a nice article on the history and use of regular expressions. They are simply a sequence of characters that define a pattern. Sometimes, you will also see them referred to as "regex". While it's easy to say what regular expressions are, creating the sequence of characters can be tricky.

Here are two regular expressions:

• ^([A-Za-z0-9!#$%&\*\+\-\/=?^`{|}~])+(\.?([\w!#$%&\*\+\-\/=?^`{|}~]))*@([A-Za-z0-9]+(\-+[A-Za-z0-9]+)*\.)+([A-Za-z0-9])+$(?!\n)

• ^((\+\d{1,3}[\s.-]*)?\(?\d{2,3}\)?[\s.\/-]*)?\d{3}[\s.-]*\d{4,6}(\s+x\d+)*$
  

The first is a pattern that matches a valid email address. The second is a pattern that matches a valid phone number, although just glancing at these two sequences of characters you might be left wondering.

Typically, regular expressions are used in a function that takes two parameters; a string and the regular expression. The function returns TRUE if the string matches the pattern defined by the regular expression.

• regex(., '^([A-Za-z0-9!#$%&\*\+\-\/=?^`{|}~])+(\.?([\w!#$%&\*\+\-\/=?^`{|}~]))*@([A-Za-z0-9]+(\-+[A-Za-z0-9]+)*\.)+([A-Za-z0-9])+$(?!\n)')

This function call takes two parameters; a dot referring to the current question input and the regular expression. 

Regular Expressions in CommCare Apps

This article on advanced validation discusses the use of regular expressions in CommCare Apps. In CommCare Apps the function regex takes two parameters; the string and the pattern, and returns TRUE or FALSE depending whether or not the string matches the pattern. This link leads to the regex function definition in the list of CommCare functions. To use regular expressions in a Commcare App the user needs to add a validation condition to a question. 

Validating Email Addresses in CommCare Apps with Regular Expressions

To Validate email addresses in CommCare with a regular expression, in the App Builder create a "Text" question for the email input as usual. In the Validation Condition under "Logic" of the "Text" question paste the function call below and add an appropriate validation message:

• regex(., '^([A-Za-z0-9!#$%&\*\+\-\/=?^`{|}~])+(\.?([\w!#$%&\*\+\-\/=?^`{|}~]))*@([A-Za-z0-9]+(\-+[A-Za-z0-9]+)*\.)+([A-Za-z0-9])+$(?!\n)')

Types of email addresses match this Pattern

Email addresses have two main parts: the local-part and the domain.

Local-part can have:

• uppercase and lowercase Latin letters A to Z and a to z
• digits 0 to 9
• printable characters !#$%&*+-/=?^_`{|}~ (minus single and double quotes)
• dot ., as long as it's not the first character, last character, or consecutive to another dot

Domain can have:

• uppercase and lowercase Latin letters A to Z and a to z
• digits 0 to 9
• hyphen - , as long as it's not the first character, last character, or consecutive to another hyphen

Example Email Addresses that match the Pattern

• admin@aaa.com
• info@clinica.com.co
• user.help@home.edu
• a@nonprofit.org
• regular.email+alias@domain.net
• regular.email_alias@domain.net
• user-@example.org (local part ending with non-alphanumeric character from the list of allowed printable characters)
• test@example-domain.com (hyphen in domain that's not the first or last character)

Example Email Addresses that do not match the Pattern

• admin.aaa.com (No @ symbol)
• info@clinica.com,co (Comma where there should be a dot)
• user.help@homeedu (Single level domain name/dotless domain)
• admin@ aaa.com (space between @ symbol and domain)
• regular'email'@test.net (single quotes)
• "regularemail"@test.net (double quotes)
• welike🙂emojis@example.com (no icons)
• "Not Provided" (Not an email address)

If you would like to test a specific Email Address you can use this https://regex101.com/

Validating Phone Numbers in CommCare Apps with Regular Expressions

To Validate phone numbers in CommCare with a regular expression, in the App Builder create a "Text" question for the phone numbers as usual. In the Validation Condition under "Logic" of the "Text" question paste the function call below and add an appropriate validation message:

• regex(., '^((\+\d{1,3}[\s.-]*)?\(?\d{2,3}\)?[\s.\/-]*)?\d{3}[\s.-]*\d{4,6}(\s+x\d+)*$')

While this regular expression should match all domestic USA phone numbers, the format of international phone numbers is complex. Therefore, there may be some International phone numbers that do not match this pattern. If you find one please let us know, so we can update the regular expression.

Example Phone Numbers that match the Pattern

• (919) 555 7862
• +1 (919) 555 7862 x222
• 555 7862
• +57 301 6246123

Example Phone Numbers that do not match Pattern

• 123456 (too short)
• ++1 919 666 1234 (duplicate plus symbols)
• 919 666 runs (cannot contain letters)
• "Not Provided" (Not a phone number)

If you would like to test a specific phone number you can use this https://regex101.com/