Considerations for Creating Custom Operator Expressions
Each operator definition contains an operator expression, a text template that defines the meaning of the operator and how operands are integrated into the expression. All operator expressions must be Boolean expressions.
Comparisons supported in operator expressions are =, <. >, <=. >=, <> (not equal). All comparisons are type-driven; for example, a number cannot be compared to a string.
If type conversion is necessary, the value to be converted may be preceded by the token's string, number, date, datetime, or time, as needed.
Values are placed in expression text with two types of substitution tokens, location number and ? (question mark).
Location Number As an Operand
Location number determines the operand in the expression that is being referred to. For the left-hand-side term, the location number is zero; for the right-hand-side elements, the range is from one to four, depending on which right-hand-side parameter is being referred to. Usually, the location number is preceded by a percent sign. The percent sign and location number combination form a complete operand token.
A complete operand token refers to the value of the configured operand. When you create a condition, an expression-text entry is substituted for the operand token. This expression-text entry corresponds to the definition of the operand value's source.
Sometimes a term ID value needs to be provided in the expression instead of a location number. In this rare case, instead of a percent sign, a dollar sign is used to precede the location number.
Parentheses around subexpressions are allowed, so long as each left parenthesis has a corresponding right parenthesis, and so long as the subexpressions denoted within parentheses are valid. (While “(%0) > %1” and “(%0 > %1) are valid, “(%0 >) %1” is not.) Constants are available for the current date, date-time, and current time by means of the items “%today”, “%timestamp” and “%now”.
Use of Term Code
In addition to referring to the results of terms that have been configured in the Operator Definition page, references to terms can be embedded directly in the expression text by means of the term code. A reference to a term is made by placing the term code name (which may not contain spaces) within square brackets. The bind parameters needed for the term must be part of the context; therefore, the operator should be part of a restricted operator set that is available only where the operator will be known to be valid.
You can also manually specify parameters for a term by following the term code name with a parameter specification, which consists of a name, a colon symbol, and the value to be bound to the parameter.
In the following example, a term is used as an input to another term in a condition to detect whether a customer's car is out of warranty:
[WarrantyExpirationDate VIN:[PrimaryVehicle DriversLicense:%0]] < %today
Generally, this type of construction is awkward and difficult to maintain, but it is available if needed. A more maintenance-friendly facility that doesn't require the configuration overhead of a term definition is a member-function call on an application class.
Two rules must be satisfied to use this facility:
The class must not require any constructor arguments.
The method to be invoked must accept an array of any as its only parameter.
To use this facility, set up an operator expression as if you are referring to a term; instead of using a term code name, use a quoted string value giving the fully qualified name of the class to be instantiated followed by a period and the name of the member function to be invoked. For example:
["MyAppPackage:MySubPackage:MyClass.MyMethod" MyParm1:%0 MyParm2:%2] = %1
Should an application class method need to return a Boolean result, the standard practice is to return a number, and to compare the number to 0 for false values or to 1 for true values.
Note: Be aware that when you create operators for a specific purpose, they are neither valid nor relevant except in a specific situation. Therefore, the operator should belong to an operator set that corresponds to the context or term for which the custom operator makes sense.