Skip to main content

Creating and Editing Rule Sets

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

When you add a rule set, you see three property fields that you can use to distinguish rule sets in a rule defintion: NameOpens in a new tab, Effective begin date and timeOpens in a new tab, and Effective end date and timeOpens in a new tab. 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:

  • 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.

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 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 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, generated description: rule function enabled (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:

  • 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.

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:

  • HL7 Message Routing Rule — Defaults to EnsLib.HL7.MessageOpens in a new tab; you do not have the option of entering this property in a new rule definition.

  • 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 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:

  • HL7 Message Routing Rule — Choose from the built-in schema category list or the name of a custom schema definition.

  • 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.

Document Name

Identifies the message structure; the acceptable values depend on the message class

  • HL7 Message Routing Rule — The HL7 message structure that the source application identifies in the MSH:9 field, such as ADT_A08 or ORM_O01. To allow easy retrieval, this MSH:9 value resides in the EnsLib.HL7.MessageOpens in a new tab property called Name.

  • 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, 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.MessageOpens in a new tab property called DocType. DocType is a two-part string separated by a colon, such as 2.4:ADT_A08.

  • 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:

  • 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.

    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 generated description: rule function enabled, you invoke the Expression Editor. There are four properties that activate the expression editor:

  • when condition — See Defining When Conditions for details.

  • assign value

  • 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.

Icon Action
generated description: rule up enabled
Click to move the selected node up in the expression.
generated description: rule down enabled
Click to move the selected node down in the expression.
generated description: rule left enabled
Click to merge the selected node with the parent node.
generated description: rule operator enabled
Click to choose from a list of operators of which to make the selected node an operand.
generated description: rule function enabled
Click to choose from a list of Ensemble functions to make the selected node an argument of the selected function.
generated description: rule add enabled
Click to add a sibling node.
generated description: rule delete enabled
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:

generated description: ruleset condition example1

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:

generated description: ruleset condition example2

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:

  • 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:

    PlaceOfBirth

  • 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 Ensemble 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.

Expression Operators

In the Expression Editor, you can click generated description: rule operator enabled 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 generated description: rule function enabled 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:

  • 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.

  • 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

    Whereas:

    (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.NotificationOpens in a new tab 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:

  • BeforeSave

  • AfterSave

  • Delete

At runtime, the Ensemble framework automatically finds your subclass of Ens.Rule.NotificationOpens in a new tab and uses the code in %OnNotify to determine what to do upon firing a rule.

FeedbackOpens in a new tab