Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.4 / System Interoperability / Business Process and Data Transformation Language Reference / BPL Elements / <rule>
Previous section   Next section

<rule>

Refer to a production business rule class.

Syntax

<rule name="ApproveLoan"
        rule="LoanApproval"
        resultLocation="context.Answer"
        reasonLocation="context.Reason"> 
</rule>

Details

Attribute or Element Description Value
name attribute Required. The name of the <rule> element. A string of one or more characters.
rule attribute Required. The name of the business rule to be executed. This must be a valid rule within the namespace; see “Identifying the Rule”, below. If the rule is not defined or otherwise cannot be found at runtime, the rule will return a default value of "" (an empty string). A string of one or more characters.
ruleContext attribute
Optional. If defined, this is an expression that identifies the object to pass to the rules engine; see “Identifying the Context”, below. For example:
context.MyObject
By default the rule passes the business process execution context to the rules engine.
A string of one or more characters.
resultLocation attribute Optional. The location in which to store the return value of the rule. Typically this is a property within the business process execution context; that is, context.MyValue. The name of a valid property and object, usually within the business process execution context.
reasonLocation attribute Optional. The location in which to store the reason returned by the rule. The rule reason is a string indicating why a business rule reached its decision. For example, “Rule 1” or “Default”. If the business rule is empty (for example, it is a rule set that contains no rules) then the reason given for the decision is “Rule Missing.” A string of zero or more characters.
disabled, xpos, ypos, xend, yend attributes See “Common Attributes and Elements.”  
<annotation> element

Description

The <rule> element invokes a business rule from a business process. When a <rule> executes, it invokes its associated business rule (named by the rule attribute) and gets its response immediately (in the same manner as a <code> or <assign> activity).

Identifying the Rule

When you use the <rule> element in BPL, the value of the rule attribute can be either of the following:
  • A simple Rule Name:
    MyRule
  • A full Package Name plus Rule Name combination:
    MyClassPackage.Organization.Levels.MyRule
If any <rule> element identifies a simple Rule Name, InterSystems IRIS automatically prepends a Package Name that is equal to the full package and class name of the BPL business process that contains that <rule> element. That is:
BPLFullPackageAndClassName.MyRule
This combination must identify a valid rule within the namespace, or the return value of the <rule> will be a null string.

Identifying the Context

By default, the ruleContext passed to the rule is the business process execution context. If you specify a different object as a context, there are some restrictions on this object: It must have a property called %Process of type Ens.BusinessProcess; this is used to pass the business process calling context to the rules engine. You do not need to set the value of this property, but it must be present. Also, the object must match what is expected by the rule itself. No checking is done to ensure this; it is up to the developer to set this up correctly.

A Simple Example

The following is a BPL excerpt showing the use of the <rule> activity with a <switch> element to process the results from the rule:

<sequence>
  <rule name="ExecuteRule"
        rule="MyRule"
        resultLocation="context.MyResult" />
  <switch>
    <case condition="context.MyResult=1">
      <!-- ...Rule is true... -->
    </case>
    <default>
      <!-- ... Rule is false... -->
    </default>
  </switch>
</sequence>
The <rule> activity in this example returns a Boolean value (true or false) according to InterSystems IRIS conventions. That is, an integer value of 1 means true; 0 means false. All rules return a single value, as in this example, but the type need not be Boolean. The single value returned from a rule may be any literal value such as an integer number, decimal number, or text string.

Return Values

The result and reason for the result are stored in the variables identified by the resultLocation and reasonLocation attributes, respectively. Usually, these attributes give the names of properties in the context variable. This is the general-purpose, persistent variable that you define at the beginning of the BPL business process using <context> and <property> elements.

See Also

Previous section   Next section