Rule – XpressDox

Using the «Rule()» command the template author can make sure that data values entered by the user in the interview for a template are syntactically correct (e.g. numeric fields represent valid numbers, account numbers follow a specific pattern) and to some extent that they are consistent with each other – in other words that the relationship between data elements makes sense.

Introduction

There are numerous variations of the «Rule()» command available.  The most generic form is similar to an «If()» command in that it contains a condition that must be fulfilled in order for the related data element to be valid.  An example would be:

«Rule(Price,hard,((Format = 'PaperBack' and Price < 100) or (Format = 'HardCover' and Price >= 100)), "The Price and Format are inconsistent.  Perhaps you have entered a Price that is too high for a paperback edition, or too low for a hardcover.")»

Although this is the most generic form of the command, in practice it is likely that the system-provided validation functions will be used (see below for a list of these).  For example, to validate that a field contains a valid date:

«Rule(DateOfBirth,soft,IsDate, "The date of birth has been entered in a form that is not consistent with your Regional Settings - do you want to accept this date anyway?")»

At this point, some points to note:

1. 1. The first parameter to the command is always the data element being validated.  In the first example, even though the validation involves both Price and Format, the rule will only be applied to the Price field in the interview.
   2. The second parameter indicates the “hardness” of the rule: when a data element fails a hard rule (“hard-and-fast”), then the system will not permit the interview to close and the template to be run until the data element passes the validation.  If the second parameter is soft (or just s), then if the data element fails the validation, the system will give the user the chance to accept the otherwise invalid value.  Notice that when a rule is soft, then the error message must end in a question to which the answer can be “Yes” or “No” – a “Yes” meaning that the system will accept that failing value anyway.
   3. The last parameter is an error message which the template author must provide to firstly tell the user that the data element contents is invalid, and also to try to help the user fix the problem.

Note that you cannot use a Rule command to force a value to be non-empty. The Rule will only ever be applied to non-empty values. In order to ensure that a data element receives a value in the interview, use the Required command.

Besides the Validation Functions section below, there are more examples and tips in the Cookbook article Tips and Hints using the Rule Command.

System Validation Functions

The system provided validation functions all begin with “Is”.  They are:

• IsDate.  Validates a date field.  There are three variations of this function:
  1. «Rule(DateOfBirth,hard,IsDate,1920-01-01,2020-12-31,The date of birth field does not contain a valid date of birth)»
     this makes sure that the field has a date in the correct format and that is lies in the range specified by the two date parameters.
  2. «Rule(DateOfBirth,hard,IsDate,1920-01-01,The date of birth field does not contain a valid date of birth)»
     very much like the first example except that there is no upper limit.
  3. «Rule(DateOfBirth,hard,IsDate,The date of birth field does not contain a valid date)»
     this validates that the format of the DateOfBirth field is valid and does not insist on a minimum or a maximum value.
     It is a shorthand form of «Rule(DateOfBirth,hard,IsDate,,,The date of birth field does not contain a valid date)» (notice the two empty parameters where the minimum and maximum values would be).
• IsDigits. Ensures that the field consists of only digits.  It has no other parameters:
  «Rule(PhoneNumber,hard,IsDigits,"The telephone number must be entered with no spaces or other characters between the digits")»
• IsEmailAddress. Validates that the field is in the form of an email address:
  «Rule(Email,hard,IsEmailAddress,"The format of the Email field is not an email address")»
• IsIBAN. Ensures that the field consists of a valid IBAN account code. Spaces can be entered. The code is not validated for country codes.  It has no other parameters:
  «Rule(AccountNumber,hard,IsIBAN,"The account number must be in the form of an IBAN account number")»
• IsNumber. Validates that the field is a valid number – i.e. starts with an optional  – and thereafter is only digits or at most one decimal point.  This is the form in which numbers are required to be used in calculations, regardless of what the regional settings of the PC are.  (In order to render the data element in the format corresponding to regional preferences, the «FormatNumber()» function would be used).  Like IsDate, there are three variations of this function:
  1. «Rule(Salary,hard,IsNumber,100,1000, "The salary must be at least 100 and no more than 1000")»
     this makes sure that the field contains a valid number, and that it lies in the range specified by the minimum and maximum parameters.
  2. «Rule(Salary,h,IsNumber,100, "The salary must be at least 100")»
  3. «Rule(Salary,h,IsNumber, "The salary field must contain a valid number")»
     this is a shorthand form of «Rule(Salary,h,IsNumber,,, "The salary field must contain a valid number")»(notice the two empty parameters where the minimum and maximum values would be).
• IsRegionalNumber.(XpressDox Version 4 and later) Validates that the field is a valid number in a format which conforms to the regional settings.  This is the form in which numbers are required to be used in by functions like FormatNumber() and IncrementV()).  Like IsNumber, there are three variations of this function:
  1. «Rule(Salary,hard,IsRegionalNumber,100,1000, "The salary must be at least 100 and no more than 1000")»
     this makes sure that the field contains a valid number, and that it lies in the range specified by the minimum and maximum parameters.
  2. «Rule(Salary,h,IsRegionalNumber,100, "The salary must be at least 100")»
  3. «Rule(Salary,h,IsRegionalNumber, "The salary field must contain a valid number")»
     this is a shorthand form of «Rule(Salary,h,IsRegionalNumber,,, "The salary field must contain a valid number")»(notice the two empty parameters where the minimum and maximum values would be).

  Data elements which are referenced in situations like «FormatNumber()» and the currency-phrase functions will have a «Rule(… IsRegionalNumber …)» command attached to them automatically. Have a look at Tips and Hints using the Rule Command to see how you can vary this automatic behaviour.

• IsPatternMatch.  This can be used to validate strings which should conform to a particular pattern.
  «Rule(AccountNumber,hard,IsPatternMatch,AA/999/XXX, "The account number is not in the correct format")»
  In the above pattern, the character A matches any alphabetic character, 9 matches any digit and X matches any character.  The / matches itself.  Valid account numbers would be:
  SE/021/-k-
  xy/123/AB3
  AA/999/XXX
  The full list of pattern characters is:
  A – matches any alphabetic character (of all alphabets, not just English)
  9 – matches any digit (i.e. 0-9)
  X – matches any character whatsoever
  =A  – matches only the letter A
  =9 – matches only the digit 9
  =X – matches only the letter X
  == – matches one equal sign
  All other characters in the pattern match themselves (e.g. the / in the Rule example above).
• IsRegexMatch.  Matches the field against a regular expression.  This is for the boffins, and can be used to match a string where the rules are too complicated to be specified by any of the standard mechanisms.
  «Rule(CreditCardNumber,soft,IsRegexMatch, '^(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13})$', "This does not look like a credit card number, should it be accepted anyway?")»
  The topic of regular expressions is so vast that this example is as far as it goes.
• IsUKPostalCode. Validates a UK Postal Code.
  «Rule(PCode,hard,IsUKPostalCode, "The PCode field should have a valid UK Postal Code but does not.")»
• IsUsSSN. Validates a US Social Security Number, where the three groups are separated either by space or a hyphen.
  «Rule(SSN,soft,IsUsSSN, "The SSN field should contain a valid Social Security Number but does not; should it be accepted anyway?")»
  Note that this rule is quite comprehensive and will not accept validly formatted SSNs which, according to Wikipedia should not be allowed.  That’s why this example uses a soft rule.
• IsZaIDNumber. Validates a South African Identity Number.  The different groups may be separated by hyphens or space, or have no separating characters.  The format of the groups is validated as far as possible (i.e. the first 6 digits must be a date, and the official formula for calculating the last digit based on the preceding 12 digits is used).
  «Rule(IDNo,soft,IsZaIdNumber, "The IDNo does not appear to be an ID number, should it be accepted anyway?")»
  Probably this Rule should always be soft because of the need to sometimes use “old” (pre-1994) Id Numbers, and also because of glitches in the Home Affairs department where ID Numbers with incorrect format have been known to have been issued.

The Delayed Option

With version 9.2.0, the Rule commands are executed immediately after the user finishes entering the relevant data field in the interview. This has many advantages, but one disadvantage is that when a Rule refers to more than one data element, (such as testing the value of TotalPrice depending on the QuantityOrdered), then it only makes sense to evaluate the rule after both elements have been captured. For this reason, it is possible to add the “delay” option after the hard/soft option. For example:

«Rule(ParentName,hard/delayed,(count(Child) > 0),‘Please make sure there is at least one Child.’)»

In this case, the Rule is evaluated after the OK (or Assemble) button has been pressed on the interview.