Skip to main content

Working with Rules

A rule set contains one or more rules that you define to satisfy specific functions in a business process. Once you create a new rule definition in the Rule Editor (Interoperability > Build > Business Rules), you are ready to start adding rules to a rule set.

Though you can give each rule a name, it is not required. By default, InterSystems IRIS® names the rules in sequential order in the form rule#n. If you give the rule a user-defined name, 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.

About If and Else Clauses

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

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

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 if clause has a condition property. A common design for a general business rule set is one that contains one rule with a series of if 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 else 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 if 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 Virtual Property Path Basics.

About Actions

Each if or else 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 following actions are supported:

Rule Set Type Action Description
All assign Assigns values to properties in the business process execution context.
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 <trace>.
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.
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. See Using the foreach Action for more details.
Routing Rule send When evaluated by a routing engine business process, this action sends the message to a particular target after optionally transforming it. For the ability to pass data to the data transformation, see Passing Data to a Data Transformation.
Routing Rule delete When evaluated by a routing engine business process, this action deletes the current message.
Routing Rule delegate When evaluated by a routing engine business process, this action delegates the message to a different rule.

The send, delete, and delegate actions should not be used within a BPL <rule>. If you include them, the action will not be executed and instead a string value will be returned that includes the given 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 if clauses of rules.

Using the foreach Action

The foreach action allows you to loop through a repeating segment and reference any of the fields within the segment.

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 if clauses and an else 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. To reference the specific field, you can use Segment.{<field-name>} — for example: Segment.{ObservationIdentifier}.

The if and else clauses in a foreach action can contain one or more rule nodes. However, you cannot nest foreach actions.

When the rule executes a return action within a foreach loop, it exits the entire rule set, not just the loop or rule.

The following example shows the use of a foreach action within a business rule. 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.

generated description: foreach example

Defining Expressions

You can use expressions when modifying the values of four properties:

  • condition property of an if clause— Specifies the condition for executing the logic in the if clause. For more information, see Editing the Condition Property of an if 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, and persistent variable contextfor 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.

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

For examples, see Expression Examples.

Editing the Condition Property of an if 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 if 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 Rule 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 Rule 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

When defining an expression, you can select one of the follow 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. When defining the expression, simply select a function from the drop-down list.

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

Defining Constraints

If the rule set contains routing rules, you can define constraints such that when a message makes its way through the rule set, the rule logic is executed only if the message matches the defined constraints. Leaving a field blank will match all values. To set constraints for a rule, double-click the rule and define the following settings:

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)

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.

Schema Category

For virtual document routing rules, 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

For virtual document routing rules, 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.

Disabling a Rule

If you would like to prevent a rule set from executing a rule, but do not want to delete the rule, you can disable it. Simply double-click the rule, and select Disable.

Passing Data to a Data Transformation

A Send action can invoke a data transformation before sending the message to a target within the production. This data transformation can use its aux variable to obtain information from the rule. Some of this data, for example the name of the rule and the reason the rule was fired, is available to the transformation without making changes to the rule class.

In order to pass additional information to the transformation, you need to edit the rule class in an IDE to assign values to properties of the class. A value assigned to the RuleUserData property of the rule class is available to the transformation if it accesses the aux.RuleUserData variable. A value assigned to the RuleActionUserData property of the rule class is available to the transformation as aux.RuleActionUserData.

For additional information about accessing the aux variable in a transformation, see the list of valid expressions in DTL Syntax Rules.

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.NotificationOpens in a new tab 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.NotificationOpens in a new tab and uses the code in %OnNotify to determine what to do upon executing a rule.

FeedbackOpens in a new tab