Skip to main content

Creating and Editing Rule Sets

The primary purpose of the Rule Editor page is to enable you to create and modify the rule sets that comprise rule definitions. In general, there are two types of rule sets:

  • General business rule sets — A list of rules that are evaluated sequentially until one of them is found to be true. The rule that is found to be true determines the next action of the business process that invoked the rule. If none of the rules are true, the rule set returns a default value. You invoke this type of rule set using the BPL <rule> element.

  • Routing rule sets — A rule set for use in message routing productions. Based on the types and contents of incoming messages (which you specify as constraints), 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 type of rule set.

All rule sets have three properties:

  • Rule Set Name — Identifier for the rule set.

  • Beginning Date and Time — Time from which the rule set is active. The exact time is included in the active interval. The format is YYYY-MM-DDTHH:MM:SS. The time portion is optional and defaults to 00:00:00.

  • Ending Date and Time — Time after which the rule is no longer active. The exact time is excluded from the active interval. The format is YYYY-MM-DDTHH:MM:SS. The time portion is optional and defaults to 24:00:00

Typically, a rule definition includes only one rule set that is always in effect. However, a rule definition can include multiple rule sets as long as they are in effect at different times. Each time a business process invokes a rule, one and only one rule set is executed.

The following sections describe how to create and manage rule sets.

Creating a Rule Definition

A rule definition is a collection of one or more rule sets. To create a rule definition, you perform the following steps:

  1. In the general tab of the Interoperability > Build > Business Rules (or Rule Editor) page, click New.

    The Business Rule Wizard appears and enables you create a new business rule definition based on the Ens.Rule.Definition class.

  2. Fill in the following fields:

    Package

    Package name for the rule definition. You can type the name of a new package or select an existing package name in the list.

    Name

    Name of the business rule class.

    Alias

    Deprecated. Do not use.

    (Optional) Alias name for this rule. The following characters are not permitted:

    ; , : | ! * - $ ‘ “ < > &
    
    Description

    (Optional) Description for the rule definition, which the system uses as the class description.

    Type

    Type of rule definition, which determines valid actions in the ruleSet tab. You can select one of the following:

    • General Business Rule

    • General Message Routing Rule

    • Virtual Document Message Routing Rule

    • Segmented Virtual Document Message Routing Rule

    • HL7 Message Routing Rule (for InterSystems IRIS for Health)

    • Extended Business Rule

    • Creation Rule for Managed Alerts

    • Overdue Rule for Managed Alerts

    Each type of rule definition is associated with one rule assist class, which specifies constraints for the rule definition and controls the functioning of the Rule Assistant pane. For more information, see General Tab.

    Context Class

    (Optional) Class that determines which object properties you can modify when you edit a rule. For general business rules, the context class is generated from the business process class associated with the BPL process and ends in .Context. For routing rules that are not associated with a BPL process, the context class is usually the business process class used by the routing engine.

  3. Click OK.

    A ruleSet tab containing the first rule set for the new rule definition appears. If you view the new rule definition class in a supported IDE such as InterSystems Studio, the definition includes an XData block named RuleDefinition.

Creating a Rule Set

When you create a rule definition, InterSystems IRIS creates a rule set for you. You can edit the rule set in the corresponding ruleSet tab.

To add another rule set, you perform the following steps:

  1. In the general tab of the Interoperability > Build > Business Rules (or Rule Editor) page, select a rule set in the list of rule sets.

  2. Click the Add icon.

  3. Double-click the name of the new rule set or click on the corresponding ruleSet tab to edit the rule set.

    You can use the icons at the top of the ruleSet tab or the RuleAssistant pane to edit a rule set.

Adding Rules to a Rule Set

A rule set contains one or more rules that you define to satisfy specific functions in a business process.

To add a rule to a rule set, you perform the following steps:

  1. In the ruleSet tab of the Interoperability > Build > Business Rules (or Rule Editor) page, select a node.

    For example, to add a second rule to the following rule set, you can select the ruleset node.

    Ruleset node selected in Rule Editor page

  2. Click the Add icon, and then select Rule.

    The new rule node appears.

    Rule set with two rules as it appears on Rule Editor page

  3. Specify the following properties:

    Name

    Optional identifier for the rule.

    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.

    Disabled

    Indicates whether the rule is disabled.

    You can double-click the disabled node to toggle the value. A value of true indicates that the rule is disabled and, therefore, skipped when the rule set is executed.

    Constraint

    (For routing rules only) Distinguishes a routing rule.

    As a message makes its way through the rule set, if it matches the constraint that you define for the rule, the rule logic is executed. See “Using the Rule Constraint Editor” for details on defining constraints.

About When and Otherwise Clauses

A rule can contain one or more when clauses and an otherwise clause. Each clause can include actions such as assign or return.

The logic in a when clause can be executed only if the condition property associated with the clause holds true. The logic in an otherwise clause can be executed only if none of the condition properties associated with the preceding when clauses holds true. When a rule contains multiple when clauses, only the logic in the first when clause where the condition property associated with the clause holds true is executed. For more information about conditions, see Editing the Condition Property of a When Clause.

In the following example, x will always be set to 2 when the ruleSet is executed since only the condition property of the second when clause holds true:

Rule set including when and otherwise clauses to illustrate the logic described above

When you add a rule, a when clause appears automatically. For routing rules, a return action appears in the when clause as well.

As you develop rules, keep the following points in mind:

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

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

  • You can access property paths in virtual documents using the syntax described in the syntax described in Virtual Property Path Basics.

About Actions

Each when or otherwise clause in a rule can include actions, but they are not required. The actions in a clause are executed if and only if the condition associated with the clause holds true. The ruleSet tab of the Interoperability > Build > Business Rules (or Rule Editor) page supports the following actions:

Rule Set Type Action Description
All 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.
All 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.
All 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.
All 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.
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.
Routing Rule delete Deletes the current message.
Routing Rule delegate Delegates the message to a different rule.
Segmented Virtual Document Routing Rule or HL7 Message Routing Rule foreach Loops through a repeating segment. A segment may repeat if it is designated as a repeating segment, is in a repeating loop, or both.
You specify the repeating segment in the propertypath property of the foreach action using the syntax described in Virtual Property Path Basics. For example, to access the OBX segments in the repeating OBXgrp of an HL7 document, you can specify HL7.{OBXgrp().OBX}, where the empty parentheses indicate the repeating group.
A foreach action can contain one or more when clauses and an otherwise clause. Within the clauses, you specify actions to execute when the conditions in the clauses hold true.
For example, you can use a foreach action to determine when a field in a repeating segment contains a particular value, and then specify a send action to route a message when the value is present.
The when and otherwise clauses in a foreach action can contain one or more rule nodes. However, you cannot nest foreach actions.
Important:
A return action is required in a foreach action and results in the process executing the rule set to return out of the rule (not just out of the foreach action).

You must ensure that you construct rule sets such that they are logically sound and result in the rule set being executed as you intended. For example, while it might make sense to set a default return value if none of the rules in a rule set are executed, it does not make sense to do so if you have created the rule set such that one rule is always executed. Typically, most actions reside in the when clauses of rules.

The following example shows a rule that includes several clauses and a foreach action. The action iterates through a repeating OBX segment in an HL7 document to determine when the ObservationIdentifier field contains certain string values. When the values are found, the rule sends the document to a file operation. When the values are not found, the rule logs an entry in the Event Log using a trace action. Lastly, the rule returns to ensure proper functioning of the rule set.

Rule set illustrating the logic described above

Editing Properties

Each node in the ruleSet tab of the Interoperability > Build > Business Rules (or Rule Editor) page can have one or more properties. For example, the ruleSet node has three properties: name, effectiveBegin, and effectiveEnd.

Ruleset with various nodes showing that each node can have one or more properties

Note:

The otherwise clause and delete action have no properties to edit.

To edit a property, perform the following steps:

  1. Double-click the property name.

    If the Rule Editor page includes an editor for the property, the (function icon) is enabled and the editor appears. For example, if you double-click the effectiveDate property, a Date and Time Selector appears.

  2. Modify the property value according to the following table:

    Node Property Instructions
    rule set name Type a name.
    rule set effective begin Specify a date and time in the Date and Time Selector.
    rule set effective end
    rule name Type a name.
    rule disabled Double-click to toggle between true and false.
    rule constraint See Rule Constraint Editor.
    when condition See Expression Editor.
    assign property Type the name of the context property that is the target of the assignment. The property must be in an execution context object.
    assign value See Expression Editor.
    return value (general rule set only) See Expression Editor.
    trace value See Expression Editor.
    send transform See Data Transform Selector.
    send target See Production Configuration Item Selector.
    delegate rule name Use the Finder Dialog to select the rule set to send the message to.
    foreach property path Type the path to the repeating segment using the syntax described in Virtual Property Path Basics.
    For example, to access the OBX segments in the repeating OBXgrp of an HL7 document, you can specify HL7.{OBXgrp().OBX}, where the empty parentheses indicate the repeating group.

    Recall that, if you define a temporary variable in the general tab, you can reference the variable in an expression by preceding the variable name with the @ (at sign) character, for example, @FreeShippingValue. You can use the same syntax to specify a temporary variable as the target of an assign action.

Rule Constraint Editor

Routing rules have a constraint property that you can use to specify the types of messages you route through each rule. You edit the property in the Rule Constraint Editor, which includes the following fields for all routing rules:

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)

You can click the ellipsis (...) next to the Source field to invoke the Production Configuration Item Selector, which displays a list of possible source items in the production that you selected on the general tab. You can leave the field blank and return to it later if you have not yet prepared the source item.

Message Class

Identifies the production message object that is being routed by this rule. The value of this field depends on the routing rule type:

  • For a General Message Routing Rule, you can click the ellipsis (...) next to the Message Class field to invoke the Finder Dialog and select the appropriate message class. You can choose the category of message class to narrow your choices.

  • For a Virtual Document Message Routing Rule, you can choose from the list of defined virtual document classes.

Additionally, the editor includes the following fields for virtual document routing rules:

Schema Category

Identifies the category of the message class and specifies its structure. You can choose from the list of category types defined for your chosen virtual document class. The types may be built-in or imported from a custom schema.

Document Name

Identifies the message structure. The acceptable values depend on the message class. You can choose from the list of category types defined for your chosen virtual document class. The types may be built-in or imported from a custom schema.

If you specify more than one value in the Document Name field, the rule matches any of the specified Document Name values and no others.

Leaving a field blank is equivalent to specifying all values.

Expression Editor

You can use the Expression Editor to modify the values of four properties:

  • condition property of a when clause

    — Specifies the condition for executing the logic in the when clause. For more information, see Editing the Condition Property of a When Clause.

  • value property of an assign action — Specifies the value to assign

  • value property of a return action in a general business rule — Specifies the value to return to the process that executed the rule set

  • value property of a trace action — Specifies the text to include in a trace message. You can specify a literal text string or an expression to be evaluated. Expressions must use the scripting language specified in the language attribute of the corresponding <process> element.

You can set each property to one of the following supported values:

  • A numeric value (integer or decimal), such as 1.1 or 23000.

  • A string value enclosed in double quotes, for example:

    "NY"

    Important:

    The double quotes are required.

  • A value of a context property. Recall that a BPL business process can contain a general-purpose, persistent variable called context. You define the context variable using the <context> and <property> elements of BPL. You can access the properties of the context object from anywhere in the business process. Therefore, if you invoke a rule from a business process using the <rule> element, you can access the context properties from within the rule.

    For context properties that contain collections such as lists and arrays, InterSystems IRIS supports several retrieval methods from within business rules, including Count(), Find(), GetAt(), GetNext(), GetPrevious(), IsDefined(), Next(), and Previous(). For more information, see Working with Collections.

    Note:

    Property names are case-sensitive and must not be enclosed in quotes, for example, PlaceOfBirth.

  • An expression using supported operators, literal values, properties of the general-purpose, persistent variable context, and temporary variables 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 and empty.

  • The Document variable, which represents the message object.

  • A temporary variable that you specified in the general tab.

  • Within a foreach action, a segment. For more information, see About Actions.

You can type values directly into the text field at the top of the Expression Editor. If the syntax is incorrect, a red error symbol appears when you attempt to save your changes. Furthermore, if you correctly specified a Context Class in the general tab, the text field lists the relevant object properties when you edit a Value.

When you define expressions, you can nest and modify conditions by using the following icons:

Icon Action
Up arrow
Move the selected node up in the expression.
Down arrow
Move the selected node down in the expression.
Left arrow
Merge the selected node with the parent node.
Operator icon
Choose from a list of operators to make the selected node an operand. For more information, see Expression Operators.
Function icon
Choose from a list of functions to make the selected node an argument of the selected function. For more information, see Expression Functions.
Plus symbol
Add a sibling node.
x or delete symbol
Delete the selected node.

If an icon is disabled, the corresponding action is not valid for the selected node. As you build an expression diagram, the textual representation of the expression appears in the blue bar at the top of the editor.

For examples, see Expression Examples.

Editing the Condition Property of a When Clause

In a rule definition, a condition consists of two values and a comparison operator between the values, for example:

Amount  <=  5000

If a condition is not true, it is false. There are no other possible values for the condition property. A result that may be only true or false is called a boolean result. InterSystems IRIS stores boolean results as integer values, where 1 is true and 0 is false. In most cases, you do not need to use this internal representation. However, for a routing rule, you may want to execute the when clause that corresponds to the condition property any time the constraint for the rule holds true. In this case, you can set the condition property to 1.

A condition property can contain more than one condition. InterSystems IRIS evaluates and compares all the conditions in the property before determining whether to execute the corresponding rule. The logic between conditions is determined by AND or OR operators. For example, consider a condition property with the following value:

IF  Amount  <=  5000
AND  CreditRating > 5
OR  CurrentCustomer = 1

The same value appears in the Expression Editor as follows:

Example of how the condition property value above appears in the Expression Editor

The value contains three conditions: Amount <= 5000, CreditRating > 5, CurrentCustomer = 1. Each condition could be true or false. InterSystems IRIS evaluates the conditions individually before evaluating the relationships between them defined by the AND and OR operators.

The AND and OR operators can operate only on true and false values. That is, the operators must be positioned between two boolean values and return a single boolean result 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, then the result (as a whole) is still true.

If a condition property contains multiple AND or OR operators, the AND operators take precedence over the OR operators. Specifically, all the AND operations are performed first. Then, the OR operations are performed. For example, consider the following set of conditions:

IF  Amount  <=  5000
AND  CreditRating > 5
OR  CurrentCustomer = 1
AND  CreditRating >= 5

The same set of conditions appears in the Expression Editor as follows:

Example of how the condition property value above appears in the Expression Editor

InterSystems IRIS evaluates the conditions as follows:

IF  (Amount  <=  5000  AND  CreditRating > 5)
OR  (CurrentCustomer = 1  AND  CreditRating >= 5)

That is, the whole set of conditions is true if either or both of the following statements is true:

  • Someone requests an amount less than 5,000 and has a credit rating better than average.

  • A current bank customer requests any amount and has a credit rating greater than or equal to the average.

If both statements are false, then the set of conditions (as a whole) is false.

To explain another way, InterSystems IRIS evaluates the set of conditions by taking the following steps:

  1. Determine whether the result of the following AND expression is true or false:

    IF  Amount  <=  5000
    AND  CreditRating > 5
    
    

    Suppose this result is called “SafeBet.”

  2. Determine whether the result of the following AND expression is true or false:

    IF  CurrentCustomer = 1
    AND  CreditRating >= 5
    
    

    Suppose this result is called “KnownEntity.”

  3. Determine whether the result of the following OR expression is true or false:

    IF  SafeBet is true
    OR  KnownEntity is true
    
    

    If SafeBet is true and KnownEntity is false, then the set of conditions is true. Similarly, if SafeBet is false and KnownEntity is true, then the set of conditions is true. Lastly, if both SafeBet and KnownEntity are true, then the set of conditions is true.

Expression Operators

In the Expression Editor, you can click o p icon, and then select an operator to make the selected node an operand.

You can use the following arithmetic operators:

Operator Meaning
+ Plus (binary and unary)
Minus (binary and unary)
* Times
/ Divide

Additionally, the following logical operators are supported and 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.

Lastly, you can 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 order of precedence, from first to last:

  1. Any of the following 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 InterSystems IRIS utility functions. These include mathematical or string processing functions similar to those that exist in other programming languages.

In the Expression Editor, you can click f x icon 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.

Expression Examples

Within a rule definition, an expression is a formula for combining values and properties to return a value. The following table includes examples of expressions along with their computed values:

Expression Computed value
((2+2)*5)/154.3 0.129617628
"hello" & "world" "helloworld"
Age * 4 If Age is a context property (a property in the general-purpose, persistent context variable, which you can define 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 Min()function . If 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) This expression uses the built-in Round() function. The result is 0.33.
x<65&&A="F"||x>80 This expression uses the operator precedence conventions that are described inExpression Operators). If 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. In InterSystems IRIS, an integer value of 1 is true and an integer value of 0 means false.
Min(10,Max(X,Y)) This expression uses the Min() and Max() functions. If 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 appears at the top of the rule set diagram. You must ensure that you use the appropriate syntax for the property since the text field enables you to specify any string. Consider the following rules when you formulate an expression:

  • An expression can include the values described in previous sections: numbers, strings, context properties, other expressions, functions, or any valid combination of these.

  • White spaces in expressions are ignored.

  • You can use any of the supported operators in an expression.

  • If you want to override the default operator precedence, or if you want to make an expression easier to read, you can use parentheses to group parts of the expression and indicate precedence. For example, consider the following expression, which results in a value of 6:

    1+2.5*2

    If you change the expression as follows, the result becomes 7:

    (1+2.5)*2

  • Business rules support parentheses to group complex logical expressions such as (((x=1) || (x=3)) && (y=2)).

Selecting the Transformation and Target of a Send Action

When you add a send action, you specify the following properties:

  • Transform(optional) The full package and class name of one or more DTL data transformations that the system uses to transform the message before sending it to the Target. 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 enables you to open the data transformation in the DTL Editor by clicking a button.

    Multiple data transformations are chained in the order in which they appear, from left to right.

  • Target — 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 and choose one or more production configuration items.

If you specify items that do not yet exist, ensure that you verify the names of the items after you create them.

Note:

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.

Production Configuration Item Selector

The Production Configuration Item Selector enables you to specify a business host as the source or a routing target of a message. Specifically, you can choose any of the business hosts from the production that you specify in the general tab. If you do not choose a production in the general tab, the following warning appears when you invoke the Production Configuration Item Selector:

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.

If you see this warning, you can choose from a list of business hosts defined in the current namespace. Ensure that you review your selections carefully.

Adding Business Rule Notification

InterSystems IRIS enables you to set up rule notifications so that the system takes specific actions each time a rule is executed. Unlike most activities related to rules, setting up notifications requires programming. You must create a subclass of the Ens.Rule.Notification class and override the %OnNotify method of the subclass. The signature of %OnNotify method is as follows:


ClassMethod %OnNotify(pReason As %String,
                      pRule As Ens.Rule.RuleDefinition)
                      As %Status

Possible pReason values are:

  • BeforeSave

  • AfterSave

  • Delete

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 executing a rule.

Feedback