Summary

Regular expressions provide a popular means to search text for a pattern. You can use regular expressions in edit validate rules (Rule-Edit-Validate rule type) in your application to check the format of a user input. 

Because regular expressions can describe a wide variety of text patterns, this approach can provide improved data validation without requiring your development team to write and test long Java routines.

Suggested Approach

An edit validate rule (Rule-Edit-Validate rule type) checks the format of a text value, such as a value typed into a form by an application user. The result outcome is either true — the value does meet the criteria defined in the rule, or false — the input value is rejected with a message.

In general, Process Commander developers need Java skills to create new edit validate rules. However, Java includes the well-known pattern matching facility known as regular expressions. This facility, like the UNIX grep command, tests an input string against a pattern, finding the first match (if any), or all matches. Using a short Java snippet, an edit validate rule can test an input string against a regular expression.

Many books, Web sites, and software products explain regular expressions, which are not explained here. For the complete, official specification see Regex.

The simple example below illustrates a Canadian postal code check, but other more complex regular expressions can be tested with similar code.

Example: Canadian Postal Codes

Every postal code for Canada consists of seven characters (including a single space) in the format ANA NAN, where A is a letter and N is a digit from 0-9. The first character is one of 18 specific letters; others are not so constrained. For example, the Pegasystems office in Toronto is located in Postal Code M5X 1E3.

1. Develop and test the regular expression.

The regular expression [ABCEGHJKLMNPRSTVXY][0-9][A-Z] [0-9][A-Z][0-9] captures the Canadian Postal Code format. To confirm this:

1. Open the built-in regular expression tester activity Code-Pega-Parse.RegExpTester. This supports the same Sun Microsystems® implementation that the edit validate rule executes.
2. Click the Run toolbar button ().
3. Click Run Rule and then click Execute. (Leave the parameters blank)
4. Complete the Regular Expression field. Enter a test string in the Source field.
5. Click Test Expression.

This test case confirms that the source "M5R 2E8" matches the regular expression pattern.

A second test case confirms that D5R 2E8 does not match. D is not one of the allowed first letters.

Note that the tester may find a match as a substring of a longer string:

2. Create the Edit Validate rule

Save the pattern you tested. in a scratch text file. Create an edit validate rule that uses the java.util.regex.Pattern class to apply the pattern to the predefined input variable theValue:

Paste the pattern you tested into the compile( ) method. In this example, the entire Java Source field contains only a few lines of code:

boolean retval = false;
if (theValue.length() == 7 ) {
java.util.regex.Pattern p =
java.util.regex.Pattern.compile("[ABCEGHJKLMNPRSTVXY][0-9][A-Z] [0-9][A-Z][0-9]");
java.util.regex.Matcher m= p.matcher(theValue);
retval = m.matches();
}
return retval;

3. Reference the edit validate rule in an activity or validate rule.

Edit validate rules execute through activities or through validate rules (Rule-Obj-Validate). To illustrate one use of the Canadian Postal Code, you can override the standard validate rule Data-Party.WorkAddress, which by default requires only that the property pyWorkPostalCode not be blank.

Enter "Canadian Postal Code" in the Validate field and an error message (or Rule-Message key) in the Error Message field.

(For testing purposes, delete the row for the pyStateCode property.)

4. Test

To exercise the validation rule and edit validation rule:

1. Select the File > Open > Work Pool > Sample Work menu item to access the PegaSample sample application.
2. Select the Run > Process > General Task menu item to enter a General Task
3. In the Parties section of the New form, select Add Party... Customer.
4. Set the Contact Preferences to Work Address. Enter customer details, including an invalid or valid Canadian Postal Code in the ZIP field.
5. Click Create.

In this example, the invalid code D8K 1Q1 was rejected.

Limitations and notes

• Edit validate rules provide only format checking. Many values that have the correct format (and so are accepted as input) do not correspond to real Canadian Postal Codes. However, format checking can detect many input errors, and is always better than accepting input without any checking.
• The Submit operation for HTML forms strips off leading and trailing spaces. There is no need to test for them or to match them.
• Your Rule-Edit-Validate Java code should not accept a substring as a valid match.
• WWW and other public sources provide regular expressions for book identifiers (ISBN numbers), telephone numbers, email addresses, IP addresses, and many other patterns. Of course, you should test any expression you plan to adopt to confirm that it matches your application requirements.
• Consult the Help System topic "About the Regular Expression tool" for more information on the built in testing tool.
• Like Java, the JavaScript language also supports regular expressions, so after you have implemented and tested an edit validate rule, you optionally can extend validation to the workstation using the client-side format validation feature and the standard ClientValidation HTML Property rule.