Developing Business Rules
Creating and Editing Rule Sets
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to use the Ensemble Rule Editor to develop rule sets.

There are two types of rule set:
Rule Set Properties
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:
Adding Rules
Each rule set contains one or more rules that you define to satisfy a specific function in a business process.
Rule Properties
When you add a rule, you see the following properties:
Name
You can give this rule an optional name to help you identify it.
Internally, Ensemble 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.
Disabled
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.
Constraint
(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:
Adding Actions
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:
Action Description
assign Assigns values to properties in the business process execution context. For details see the <assign> entry in the Ensemble Business Process 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 Ensemble Business Process Language Reference.
debug Adds the expression text and value to the Event 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 Ensemble Virtual Documents.
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:
Action Description
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
effective end
rule name Enter text.
disabled Double-click to toggle between true and false.
constraint Rule Constraint Editor
when condition Expression 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.
value Expression Editor
return value (general rule set only) Expression Editor
trace value 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:
Source
Configuration name of one of the following items:
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.
Message Class
Identifies the Ensemble message object that is being routed by this rule. The value of this field depends on the routing rule type:
The following fields in the editor apply only when the you are editing an HL7 or virtual document routing rule class, such as X12 or ASTM. For general message routing rules, you are finished entering the constraint fields.
Schema Category
Identifies the message category for the particular message class:
Document Name
Identifies the message structure; the acceptable values depend on the message class
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, Ensemble considers all values to be a match for that rule.
The Constraint Editor behaves somewhat differently when you are editing a rule set converted from a version older than Ensemble 2012.1. You may see the Schema Doc Type field with a box to select an item to append to the list.
Schema Category and Schema Doc Type represent the actual HL7 message structure. These values reside in the EnsLib.HL7.Message property called DocType. DocType is a two-part string separated by a colon, such as 2.4:ADT_A08.
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:
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 defining an expression, you can nest several conditions by using the icons described in the following table.
Icon Action
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 Ensemble 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. Ensemble 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:
  1. This AND expression:
    IF  Amount  <=  5000
    AND  CreditRating > 5
    
    Gives a result, true or false. Call this result “SafeBet.”
  2. This AND expression:
    IF  CurrentCustomer = 1
    AND  CreditRating >= 5
    
    Gives a result, true or false. Call this result “KnownEntity.”
  3. Once the AND operations in the rule have completed, the OR operation begins, as follows:
    IF  SafeBet is true
    OR  KnownEntity is true
    
  4. 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.
Expression Values
Within a condition or the assign, return, or trace actions, the values can be any of the following items:
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.
Expression Operators
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:
Operator Meaning
+ Plus (binary and unary)
Minus (binary and unary)
* Times
/ Divide
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:
Operator Meaning
& 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:
  1. Any of these logical operators: ! = != < > <= >=
  2. Multiplication and division: * /
  3. Addition and subtraction: + –
  4. String concatenation: &
  5. Logical AND: &&
  6. Logical OR: ||
Expression Functions
Within a rule definition, an expression can include a call to one of the Ensemble 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 Ensemble Utility Functions in Developing Business Rules.
Expression Examples
Within a rule definition, an expression is a formula for combining values and properties to return a value. For example:
Expression Computed value
((2+2)*5)/154.3 0.129617628
"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.
1+2.5*2 6
2*5 10
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 Ensemble 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:
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 Ensemble framework automatically finds your subclass of Ens.Rule.Notification and uses the code in %OnNotify to determine what to do upon firing a rule.