Creating and Editing Rule Sets
This chapter describes how to use the Rule Editor to develop rule sets.
There are two types of rule set:
General business rule set — A list of rules that are evaluated sequentially until one of them is found to be true. The “true” case determines the next action of the business process that invoked the rule. If none of the rules is true, the rule set returns a default value. This is the type of rule that you invoke using the BPL <rule> element.
Routing rule set — A rule set for use in message routing productions. Based on the type and contents of incoming messages (constraint), the routing rule set determines the correct destination for each message and how to transform the message contents prior to transmission. You use a routing engine business process to invoke this rule set.
When you add a rule set, you see three property fields that you can use to distinguish rule sets in a rule defintion: Name, Effective begin date and time, and Effective end date and time. These are the values the rule set list shows on the general tab.
Most business rule definitions have only one rule set that is always in effect. You can, however, have more than one version of a rule defined and become active at different times using a beginning and ending effective date and time. Each time a process invokes a rule, one and only one rule set is executed.
You can add a rule set from the general tab by clicking the add icon with the rule set list selected. You can then begin to edit the rule set by clicking on its tab or double-clicking its row in the list. When you are editing a rule set, you can click the icons near the top of the rule set tab or you can click the ones (or in the case of the add icon, the labeled rectangles beneath) in the expanded Rule Assistant pane.
As you become more familiar with the rule set editor and the rule sets you are developing, you may find it unnecessary to view the property names throughout the display of the rule set. You can toggle the viewing of property names by clicking the green square in the top right of the editor pane.
Also throughout the editing process, if a property does not contain a valid value you see a small red circle containing an exclamation point at the top right of the property box. If you double-click this warning mark, a helpful error message displays.
The following sections describe the editing tasks involved in creating a rule set:
Each rule set contains one or more rules that you define to satisfy a specific function in a business process.
When you add a rule, you see the following properties:
You can give this rule an optional name to help you identify it.
Internally, InterSystems IRIS® names the rules in sequential order in the form rule#n. If you enter a value in the Name property, it appears in the class definition and also appears in parentheses next to the internal rule name in the rule log. The value of n changes if you reorder the rules in a rule set.
You can double-click this item to toggle between disabling and enabling the rule. A value of true means the rule is disabled and therefore skipped when the rule set is executed.
(For routing rules only) — The constraint property distinguishes a routing rule. As a message makes its way through the rule set, if it matches the constraint you define for the rule, that rule logic is executed. See “Using the Rule Constraint Editor” for details on defining the constraint.
Each rule consists of a series of one or more when clauses and an optional otherwise clause, along with some optional actions. When you add a rule, the editor starts you with a when clause and if it is a routing rule, it also provides a return action for the clause.
Some general considerations to keep in mind when developing rules in your rule set:
Once the execution through a rule set encounters a return action, the execution of the rule set ends and returns to the business process that invoked the rule definition class.
You can control the execution of more than one rule in a rule set by omitting the returns. In other words, if you want to check all rules, do not provide a return action within any of the rule clauses. You may then provide a value in a return action at the end of the rule set for the case where no rule clauses evaluate to true.
When a rule contains multiple when clauses, only the actions indicated by the first when that evaluates to true are performed. You can use an otherwise clause to perform an action if no when conditions are true.
Each when clause has a condition property. A common design for a general business rule set is one that contains one rule with a series of when conditions and returning a value depending on which condition is true. If you want to return a default value if none of the conditions is true, you can use the otherwise clause with a return.
A common design for a routing rule set is one that contains several rules each with a different constraint defined and each with one when clause describing how and where to route the message that matches the constraint.
Every clause within a rule can have zero or more actions associated with it. Actions are executed if and only if the associated when condition is true. You can add the following actions to a rule set or a when or otherwise clause within a rule:
|assign||Assigns values to properties in the business process execution context. For details see the <assign> entry in the Business Process and Data Transformation Language Reference.|
|return||Returns to the business process without further execution of the rule. For general rules it also returns the indicated value to the result location.|
|trace||Adds the information you enter into the Event Log when this specific part of the rule is executed. For details see the <trace> entry in the Business Process and Data Transformation Language Reference.|
|debug||Adds the expression text and value to the Rule Log when this specific part of the rule is executed. The debug action is executed only if the router business process RuleLogging property specifies the d flag, For details on the RuleLogging property, see “Rule Logging ” in Using Virtual Documents in Productions.|
You can add some actions at the rule set level, but they do not always logically make sense. You should contain most actions within the when clauses of rules. A time when it may make sense to provide an action outside of these clauses is to set a default return value if no rules are executed in a rule set.
In addition, you can add the following actions to a routing rule:
|send||Sends the message to a particular target after optionally transforming it. See “Selecting the Transformation and Target of a Send Action” for details.|
|delete||Deletes the current message.|
|delegate||Delegates the message to a different rule.|
Using the Associated Editors
When you select a property of any of the items in a rule definition, (the function icon) becomes enabled if the property has an associated editor. The following table shows which properties exist for a item, clause, or action and which editor opens when you double-click the property or click ƒx.
|Item||Property||Associated editor or edit action|
|rule set||name||Enter text.|
|effective begin||Date and Time Selector|
|disabled||Double-click to toggle between true and false.|
|constraint||Rule Constraint Editor|
|assign||property||Enter the name of a context property that is the target of this assignment. This must be a property in an execution context object.|
|return||value (general rule set only)||Expression Editor|
|send||transform||Data Transform Selector|
|target||Production Configuration Item Selector|
|delegate||rule name||Finder Dialog for rule classes.|
The otherwise clause and delete action have no properties to edit.
Using the Rule Constraint Editor
Routing rules have a constraint property you use to determine which messages to route through which rules. Use this editor to configure the rule constraint values, which can be made up of the following properties:
Configuration name of one of the following items:
A business service (for a routing interface)
A message routing process (if another rule chains to this routing rule set)
Click (...) next to the Source field to invoke the Production Configuration Item Selector which displays a list of possible source items in the production you indicate on the general tab. If you have not yet prepared the item you need as a Source, you may leave this field blank and return to it when the item is ready.
Identifies the production message object that is being routed by this rule. The value of this field depends on the routing rule type:
General Message Routing Rule — Click ... next to the Message Class field to invoke the Finder Dialog to select the appropriate message class. You can choose the category of message class to narrow your choices.
Virtual Document Message Routing Rule — Choose from the list of defined virtual document classes.
The following fields in the editor apply only when you are editing a virtual document routing rule class, such as X12. For general message routing rules, you are finished entering the constraint fields.
Identifies the message category for the particular message class:
Virtual Document Message Routing Rule — Choose from the list of category types defined for your chosen virtual document class; they could be built-in or from an imported custom schema.
Identifies the message structure; the acceptable values depend on the message class:
Virtual Document Message Routing Rule — Choose from the list of category types defined for your chosen virtual document class; they could be built-in or imported.
Enter more than one value in the Document Name text entry field. This causes the rule to match any of the specified Document Name values, and no others.
If you leave any of the fields blank, InterSystems IRIS considers all values to be a match for that rule.
Schema Category and Schema Doc Type represent the actual message structure.
Using the Production Configuration Item Selector
This editor helps you choose a configuration item as a source of a message or a routing target of a message. You choose from a list of production configuration items defined in the production you enter in the general tab. If you do not choose a production in the general tab of your rule definition, you receive the following warning when you invoke this editor:
No production name has been specified in the General tab of your rule. Be careful and ensure that your chosen target(s) exist in your production.
In this case you choose from a list of production configuration items defined in the current namespace. While developing your production rules, be careful to verify the names of your configuration items.
Selecting the Transformation and Target of a Send Action
When you add a send action, you also enter the following properties:
Transform — (optional) To transform the message before sending it to the Target, enter the full package and class name of one or more DTL data transformations. You can double-click the Transform field to invoke the Data Transform Selector to choose one or more defined data transformations in the namespace. The Data Transform Selector dialog contains a button that allows you to open the data transformation in the DTL Editor.
Multiple data transformations are chained in the order in which they appear, from left to right.
Target — Enter the configured name of one or more of the following production items:
A business operation, to route the message to an external application
A routing process, to chain to another routing rule set
Double-click the Target field to invoke the Production Configuration Item Selector to choose one or more production configuration items.
If you enter items for these field that do not exist yet, make sure to verify you have entered the correct name when the production does contain them.
If you want to pass information to the rule, you can assign a value to the RuleUserData property. This value is accessible to the transformation in the aux.RuleUserData. For details on using the aux variable, see “Valid Expressions” in the chapter “Syntax Rules” in Developing DTL Transformations.
Using the Expression Editor
When you select a condition or a value and click , you invoke the Expression Editor. There are four properties that activate the expression editor:
when condition — See Defining When Conditions for details.
return value of a general business rule
trace value — This is the text for the trace message. It can be a literal text string or an expression to be evaluated. If an expression, it must use the scripting language specified by the language attribute of the containing <process> element.
When defining an expression, you can nest several conditions by using the icons described in the following table.
|Click to move the selected node up in the expression.|
|Click to move the selected node down in the expression.|
|Click to merge the selected node with the parent node.|
|Click to choose from a list of operators of which to make the selected node an operand.|
|Click to choose from a list of functions to make the selected node an argument of the selected function.|
|Click to add a sibling node.|
|Click to delete the selected node.|
If an action is not available, its icon appears dimmed. As you add conditions and values to the expression diagram, you see the text of the expression in the blue bar at the top of the editor.
The following sections provide greater detail for entering expression values:
Defining When Conditions
Within a rule definition, a condition consists of two values and a comparison operator between these values. For example:
Amount <= 5000
If a condition is not true, it is false. There are no other possible values for a condition. This type of result is called a Boolean result. InterSystems IRIS stores a Boolean result either as the integer value 1 (if true) or 0 (if false). In most cases you do not need to be concerned with this internal representation; however, when using the constraint property in a routing rule, you may want to always execute the associated when clause when the constraints are satisfied. In this case, enter a value of 1 in the when condition property.
There can be more than one condition within a rule. If so, all of the conditions must be evaluated and compared before the rule (as a whole) can be found to be true or false. The logic between each condition is controlled using AND or OR operators. For example:
IF Amount <= 5000 AND CreditRating > 5 OR CurrentCustomer = 1
For this example, the Expression Editor dialog appears as follows:
The preceding rule has three conditions: Amount <= 5000, CreditRating > 5, CurrentCustomer = 1. Each of these conditions could be true or false. All of these conditions are evaluated before the AND or OR operators come into play.
AND and OR operate on true and false values only. The operator is positioned between two Boolean values, and returns a single Boolean result based on those two values, as follows.
|Operator||Result is true when...|
|AND||Both values are true.|
|OR||At least one of the values is true, or both are true. If one of the values is false and the other is true, and the result (as a whole) is still true.|
If there are multiple AND or OR operators within a rule, AND operators take precedence over OR operators. This means that all AND operations in the rule are performed first. Only then are the OR operations considered. Thus, logic such as this:
IF Amount <= 5000 AND CreditRating > 5 OR CurrentCustomer = 1 AND CreditRating >= 5
is handled as follows:
IF (Amount <= 5000 AND CreditRating > 5) OR (CurrentCustomer = 1 AND CreditRating >= 5)
For this example, the Expression Editor dialog appears as follows:
The preceding rule is true if anyone requests an amount less than 5,000 and has a credit rating better than average. The rule is true for any current bank customer requests any amount and has a credit rating greater than or equal to the average. Both conditions may be true, or only one or the other of them may be true. If both conditions are false, then the rule (as a whole) is false.
In detail, the preceding rule works as follows:
This AND expression:
IF Amount <= 5000 AND CreditRating > 5
Gives a result, true or false. Call this result “SafeBet.”
This AND expression:
IF CurrentCustomer = 1 AND CreditRating >= 5
Gives a result, true or false. Call this result “KnownEntity.”
Once the AND operations in the rule have completed, the OR operation begins, as follows:
IF SafeBet is true OR KnownEntity is true
From what we know about OR logic, we know that this rule (as a whole) is true if the customer is a SafeBet but not a KnownEntity, or if the customer is not a SafeBet but is a KnownEntity. Additionally, this rule is true if the customer is both a SafeBet and a KnownEntity.
Within a condition or the assign, return, or trace actions, the values can be any of the following items:
A numeric value (integer or decimal), such as 1.1 or 23000.
A string value, which must be enclosed in double quotes: "NY"
If your production invokes the rule from a BPL business process using the <rule> element, you can specify a property in the general-purpose, persistent variable context, which is defined using the <context> and <property> elements in BPL. A property name is case-sensitive, and must not be enclosed in quotes, as in:
An expression using various permitted operators, literal values, and properties of context, as for example:
((2+2)*5)/154.3 "hello" & "world" Age * 4 (((x=1) || (x=3)) && (y=2))
A built-in function such as Min(), Max(), Round(n,m), or SubString(). The function name must include parentheses. It must also include any input parameters, such as the numeric values n and m for Round. If there are no input values for the function, then the open and close parentheses must be present, but empty.
The Document variable, which represents the message object.
When you want to insert a value into a field on the rule set tab, you may type it into the text box directly. If the syntax is incorrect or inappropriate for the type of data expected for that field, you see the red error symbol when you try to save your changes.
If you correctly entered a Context Class in your rule definition, when you select a property in the Expression Editor, the text box provides choices of properties from the business process execution context of the identified BPL business process Context Class.
In the Expression Editor, you can click to choose from a list of operators of which to make the selected node an operand.
You may use the following arithmetic operators:
|+||Plus (binary and unary)|
|–||Minus (binary and unary)|
You may use the following logical operators, which return an integer value of 1 (true) or 0 (false):
|Operator||Meaning||Expression is true when...|
|AND (&&)||And||Both values are true.|
|OR (||)||Or||At least one of the values is true. Both values may be true, or only one true.|
|!||Not (unary)||The value is false.|
|=||Equals||The two values are equal.|
|!=||Does not equal||The two values are not equal.|
|>||Is greater than||The value to the left of the operator is greater than the value to the right of the operator.|
|<||Is less than||The value to the left is less than the value to the right.|
|>=||Is greater than or equal to||The value to the left is greater than the value to the right, or if the two values are equal.|
|<=||Is less than or equal to||The value to the left is less than the value to the right, or if the two values are equal.|
|[||Contains||The string contains the substring to the right. Pattern matching for Contains is exact. If the value at left is “Hollywood, California” and the value at right is “od, Ca”, there is a match, but a value of “Wood” does not match.|
You may use the following string operators:
|&||Concatenation operator for strings.|
|_||Binary concatenation to combine string literals, expressions, and variables.|
When more than one operator is found in an expression, the operators are evaluated in the following precedence order, from first to last:
Any of these logical operators: ! = != < > <= >=
Multiplication and division: * /
Addition and subtraction: + –
String concatenation: &
Logical AND: &&
Logical OR: ||
Within a rule definition, an expression can include a call to one of the InterSystems IRIS utility functions. These include mathematical or string processing functions such as you may be accustomed to using in other programming languages.
In the Expression Editor, you can click to choose from a list of functions of which to make the focused node an argument.
For a list of the available utility functions and the proper syntax for using them in business rules or DTL data transformations, see “Utility Functions for Use in Productions” in Developing Business Rules.
Within a rule definition, an expression is a formula for combining values and properties to return a value. For example:
|"hello" & "world"||"helloworld"|
|Age * 4||When Age is a context property (a property in the general-purpose, persistent variable context, which is defined using the <context> and <property> elements in BPL) and has the numeric value 30, the value of this expression is 120.|
|Min(Age,80,Limit)||This expression uses the built-in function Min. When Age is a context property with the value 30 and Limit (likewise a property) has the value 65, the value of this expression is 30.|
|Round(1/3,2)||0.33. This expression uses the built-in function Round.|
|x<65&&A="F"||x>80||This expression uses operator precedence conventions (explained in Expression Operators). When A is a context property with the string value F, and x (likewise a property) has the integer value 38, this expression has the integer value 1. This integer value has the meaning true or false according to InterSystems IRIS conventions. That is, an integer value of 1 means true; 0 means false.|
|Min(10,Max(X,Y))||This expression uses the utility functions Min and Max. When X is a context property with the numeric value 9.125, and Y (likewise a property) has the numeric value 6.875, the value of this expression is 9.125.|
|(((x=1) || (x=3)) && (y=2))||This expression uses parentheses to clarify precedence in a complex logical relationship.|
When you select a property that takes an expression as its value, a blank text field displays at the top of the rule set diagram. You may type any string in this field, so take care to enter the correct syntax. The rules for formulating expressions are as follows:
White space in expressions is ignored.
You may use any of the described operators.
If you want to override the default operator precedence, or if you want to make expressions easier to read, you can indicate precedence by using parentheses to group parts of the expression. Thus:
1+2.5*2 = 6
(1+2.5)*2 = 7
Business rules support parentheses to group complex logical expressions such as (((x=1) || (x=3)) && (y=2)).
When you invoke the Expression Editor, a blue bar displays above the graphical representation of the expression that contains the textual representation of the expression.
Adding Business Rule Notification
It is possible for you to set up rule notification, so that specific actions are taken each time a rule is fired. Unlike most activities related to rules, notification requires programming. You must subclass Ens.Rule.Notification and override the %OnNotify method in the subclass. The signature of this method is:
ClassMethod %OnNotify(pReason As %String, pRule As Ens.Rule.RuleDefinition) As %Status
Possible pReason values are:
At runtime, the production framework automatically finds your subclass of Ens.Rule.Notification and uses the code in %OnNotify to determine what to do upon firing a rule.