This chapter describes how to use the Ensemble 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.
Rule Set Properties
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
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, 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.
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.
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.
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
clause within a rule:
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:
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
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)
) 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 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.
Identifies the message category for the particular message class:
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.
At left is the Schema Category
. This is the name of a built-in schema category or the name of a custom schema definition.
At right is the Schema Doc Type
. This is an HL7 message structure within the identified schema, such as ADT_A08 or ORM_O01.
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:
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.
Multiple data transformations are chained in the order in which they appear, from left to right.
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
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.
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.
||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:
Within a rule definition, a condition
consists of two values
and a comparison operator between these values. For example:
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
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
operators. For example:
IF Amount <= 5000
AND CreditRating > 5
OR CurrentCustomer = 1
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
operators come into play.
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.
||Result is true when...
||Both values are true.
||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
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
IF (Amount <= 5000 AND CreditRating > 5)
OR (CurrentCustomer = 1 AND CreditRating >= 5)
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:
IF Amount <= 5000
AND CreditRating > 5
Gives a result, true or false. Call this result SafeBet.
IF CurrentCustomer = 1
AND CreditRating >= 5
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.
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:
"hello" & "world"
Age * 4
(((x=1) || (x=3)) && (y=2))
A built-in Ensemble function
such as Min()
, or SubString()
. The function name must include parentheses. It must also include any input parameters, such as the numeric values n
. If there are no input values for the function, then the open and close parentheses must be present, but empty.
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):
||Expression is true when...
||Both values are true.
||At least one of the values is true. Both values may be true, or only one true.
||The value is false.
||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.
||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:
Multiplication and division: * /
Addition and subtraction: +
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.
Within a rule definition, an expression
is a formula for combining values and properties to return a value. For example:
|"hello" & "world"
|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.
||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.
||0.33. This expression uses the built-in function Round.
||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.
||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:
An expression may involve any values
as described in the preceding topics: numbers, strings, context
properties, expressions, functions
, or any valid combination of these.
White space in expressions is ignored.
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:
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)