4 Working with Rulesets and Rules

This chapter describes the Oracle Business Rules data model element called ruleset that you use to group one or more rules and Decision Tables. It also discusses how to work with dictionaries, nested tests, and advanced and tree mode rules, and Expression Builder.

The chapter includes the following sections:

For more information, see Section 1.1.5, "What Are Rulesets?".

4.1 Introduction to Working with Rulesets and Rules

You can use business rules to define key decisions and policies for a business, including:

  • Business Policies: for example spending policies and approval matrices

  • Constraints: for example valid configurations or regulatory requirements

  • Computations: for example discounts, premiums, or scores

  • Reasoning Capabilities: for example offers based on customer value

Oracle Business Rules provides two ways to work with rules:

  • Using IF/THEN rules

  • Using rules in a Decision Table

This chapter describes working with IF/THEN rules. For information on Decision Tables, see Chapter 5, "Working with Decision Tables".

4.2 Working with Rulesets

A ruleset provides a unit of execution for rules and for Decision Tables. In addition, rulesets provide a unit of sharing for rules; rules belong to a ruleset. Multiple rulesets can be executed in order. This is called rule flow. The ruleset stack determines the order. The order can be manipulated by rule actions that push and pop rulesets on the stack. In rulesets, the priority of rules applies to specify the order of firing of the rules in the ruleset. Rulesets also provide an effective date specification that identifies that the ruleset is always active, or that the ruleset is restricted based on a time and date range, or a starting or ending time and date.

4.2.1 How to Create a Ruleset

All rules and Decision Tables are created in a ruleset. A ruleset organizes rules and Decision Tables into a unit of execution.

To create a ruleset:

  1. In Rules Designer, go to the Rulesets navigation tab.

  2. Click the Create Ruleset... icon. This displays the Create Ruleset dialog.

  3. Enter a name in the Name field.

  4. Enter a description in the Description field, as shown in Figure 4-1.

    Figure 4-1 Adding a Ruleset

    Description of Figure 4-1 follows
    Description of "Figure 4-1 Adding a Ruleset"

  5. Click OK.

4.2.2 How to Set the Effective Date for a Ruleset

Effective date support provides the ability to specify a start date and an end date for a ruleset, a rule or a Decision Table. For a ruleset the effective date defines the date range in which the rules and Decision Tables within the ruleset are effective. For more information on effective dates, see Section 4.9, "Using Date Facts, Date Functions, and Specifying Effective Dates".

To set the effective date for a ruleset:

  1. Select the ruleset name from the Rulesets navigation tab.

  2. Click the navigation icon next to the ruleset name to expand the ruleset information to show the ruleset Name, Description, and Effective Date fields, as shown in Figure 4-2.

    Figure 4-2 Ruleset Showing Effective Date Field

    Description of Figure 4-2 follows
    Description of "Figure 4-2 Ruleset Showing Effective Date Field"

  3. Select the Effective Date entry. This displays the Set Effective Date dialog, as shown in Figure 4-3.

    Figure 4-3 Using the Set Effective Date Dialog

    Description of Figure 4-3 follows
    Description of "Figure 4-3 Using the Set Effective Date Dialog"

  4. Use the Set Effective Date dialog to specify the effective dates for the ruleset. Clicking the Set Date icon displays a calendar to assist you in entering the From and To field data.

4.2.3 How to Use a Filter to Display Matching Rules in a Ruleset

As the number of rules in a ruleset increases, it can be difficult to navigate the list of rules. You can instruct Rules Designer to filter the list of rules, to display only rules of interest. For example, you can display only active rules or only rules that have validation warnings.

For more information on creating rules, see Section 4.3, "Working with Rules".

To use a filter to display matching rules in a ruleset:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.

  2. To show the rule filter settings, next to the ruleset name, click Show Filter Query as Figure 4-4 shows.

    Figure 4-4 Showing a Filter Query in a Ruleset

    Description of Figure 4-4 follows
    Description of "Figure 4-4 Showing a Filter Query in a Ruleset"

  3. In the Filter Query field, click <insert test> to insert a default test as Figure 4-5 shows.

    Figure 4-5 Inserting a Default Filter Query Test

    Description of Figure 4-5 follows
    Description of "Figure 4-5 Inserting a Default Filter Query Test"

  4. Configure the default test.

    In this case, as shown in Figure 4-6, when you click an <operand> you can choose from the rule-specific options shown in Table 4-1.

    Table 4-1 Rule Filter Query Operands

    Operand Description

    name

    Matches against the rule name.

    description

    Matches against the rule description.

    priority

    Matches against the rule priority. For more information, see Section 4.5.5, "How to Set a Priority for a Rule".

    start date

    Matches against the rule start date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule".

    end date

    Matches against the rule end date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule".

    minutes until start date

    Matches against a specified number of minutes until the rule start date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule".

    minutes until end date

    Matches against a specified number of minutes until the rule end date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule".

    days until start date

    Matches against a specified number of days until the rule start date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule"

    days until end date

    Matches against a specified number of days until the rule end date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule"

    years until start date

    Matches against a specified number of years until the rule start date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule"

    years until end date

    Matches against a specified number of years until the rule end date. For more information, see Section 4.9.2, "How to Set the Effective Date for a Rule"

    is active

    Matches against whether the rule is active. For more information, see Section 4.5.3, "How to Select the Active Option".

    is valid

    Matches against whether the rule has validation warnings. For more information, see Section 4.4.2, "Understanding Rule Validation".

    referenced fact types

    Matches against one or more fact types.

    Figure 4-6 Filter Query Operands

    Description of Figure 4-6 follows
    Description of "Figure 4-6 Filter Query Operands"

    For more information, see Section 4.3.2, "How to Define a Test in a Rule".

  5. Select the operator to choose an operator for the comparison. For example, for the name you can select startsWith from the operand list.

  6. Enter a comparison operand for the right-hand-side of the filter test. For example, enter the string Customer.

  7. When the filter query is complete you can apply the filter to the rules in the ruleset:

    1. To apply the filter, select the Filter On checkbox.

      Rules Designer displays only the rules that match the filter query as Figure 4-7 shows.

      Figure 4-7 Enable Filter Query in a Ruleset with Filter On Option

      Description of Figure 4-7 follows
      Description of "Figure 4-7 Enable Filter Query in a Ruleset with Filter On Option"

    2. To disable the filter query, deselect the Filter On checkbox.

      Rules Designer displays all the rules in the ruleset.

    3. To delete the filter query, select it and press Delete or click the Clear Filter icon.

4.3 Working with Rules

You create business rules to process facts and to obtain intermediate conclusions that Oracle Business Rules can process. You create rules in a ruleset, so before working with rules you need to create a ruleset (or use the default ruleset). For more information on creating a ruleset, see Section 4.2, "Working with Rulesets".

You can easily test your rules as you are designing them without having to deploy your application. For more information, see Section 8.1.5, "How to Test a Decision Function Using an Oracle Business Rules Function".

Rules Designer rule validation can assist you when you work with rules. To show the validation log window, click the Validate icon or select View>Log and select the Business Rule Validation tab. This displays warnings for incorrect or incomplete rules. Note that you must correct all warnings before you can test or deploy rules. For more information on rule validation, see Section 4.4.2, "Understanding Rule Validation".

As the number of rules in a ruleset increases, you can configure Rules Designer to filter the list of rules to show only rules of interest. For more information, see Section 4.2.3, "How to Use a Filter to Display Matching Rules in a Ruleset".

4.3.1 How to Add Rules

To create a rule you first add the rule to a ruleset, and then you insert tests and actions. The actions are associated with pattern matches. At runtime when a test in the IF area of a rule matches, the Rules Engine activates the THEN action and prepares to run the actions associated with the rule.

Rules Designer lets you create a rule where by default the rule fires for each matching fact. To enable other options, where the same fact type matches more than once, or never, you select Advanced Mode. For more information on advanced mode and showing advanced settings, see Section 4.5, "Using Advanced Settings with Rules and Decision Tables".

To add rules in a ruleset:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.

  2. In the View field, select IF/THEN Rules.

  3. Click Add to add a rule. For example, click Add to add a rule named Rule_1, as shown in Figure 4-8.

    Figure 4-8 Adding a Rule in a Ruleset

    Description of Figure 4-8 follows
    Description of "Figure 4-8 Adding a Rule in a Ruleset"

4.3.2 How to Define a Test in a Rule

To create a test in a rule you add conditions for facts. For example, with a sample CustomerOrder fact with an annual spending property, you can add a test to determine if a customer order is associated with a high value of spending, based on the annual spending for the customer. Note that you can use bucketsets to limit the values for tests and actions in rules. For more information, see Section 4.11, "Using Bucketsets as Constraints for Options Values in Rules".

Figure 4-9 shows this sample rule.

Figure 4-9 Adding a Test to a Rule

Description of Figure 4-9 follows
Description of "Figure 4-9 Adding a Test to a Rule"

At runtime, when this rule is processed the Rules Engine checks the facts against rule pattern tests that you define to find matching facts. For this sample rule, Rule_1, when a fact matches the Rules Engine modifies the fact and then modifies the value property to "High".

To define tests in rules:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.

  2. In the View field, select IF/THEN Rules (this is the Rules Designer default).

  3. Add or select the rule you want to use, for example, select Rule_1.

  4. In Rule_1, in the IF area, select <insert test>.

  5. For a test, the IF area of a rule includes a left-hand-side <operand> and a right-hand-side <operand>, as shown in Figure 4-10.

    Figure 4-10 Rule Test with Left-hand-side operand and Right-hand-side operand

    Description of Figure 4-10 follows
    Description of "Figure 4-10 Rule Test with Left-hand-side operand and Right-hand-side operand"

  6. In a test, you replace the left-hand-side operand with a value.

    To do this, select the left-hand-side <operand>. This displays a text entry area and a list, as shown in Figure 4-11:

    Figure 4-11 Configuring the Left-hand-side Operand of a Test in a Rule

    Description of Figure 4-11 follows
    Description of "Figure 4-11 Configuring the Left-hand-side Operand of a Test in a Rule"

    1. To enter a value use the list to select an item from the value options.

      You can view the options using a single list, by selecting List View, or using a navigator by selecting Tree View.

    2. To enter a literal value, type the value into the text entry area and press Enter.

      The value you enter must agree with the type of the corresponding operand. For example, in the test IF CustomerOrder.annualSpending > <operand>, valid values for <operand> must agree with the type of CustomerOrder field annualSpending.

  7. In a test, you replace the operator with the desired logical operator or accept the default (==). To do this, select the default == operator. This displays a field and a list. The list may contain additional operators, depending on the datatype of the left operand. For example, to test strings, if you select a String operand on the left hand side, then additional String operators, such as startsWith and equalsIgnoreCase are available as shown in Figure 4-12.

    Figure 4-12 Configuring String Operators in a Rule

    Description of Figure 4-12 follows
    Description of "Figure 4-12 Configuring String Operators in a Rule"

    Similarly, to test a logical condition between the left-hand and right-hand operands, select one of the logical operators as shown in Figure 4-13: == (equality), != (not equal), > (greater than), >= (greater than or equal to), < (less than), <= (less than or equal to). For more information on the operators, see Appendix B, "Oracle Business Rules Built-in Classes and Functions.".

    Figure 4-13 Configuring the Operator of a Test in a Rule

    Description of Figure 4-13 follows
    Description of "Figure 4-13 Configuring the Operator of a Test in a Rule"

  8. In a test, you replace the right-hand-side operand with a value.

    Configure the <operand> placeholder as you would for any operand.

    For example, enter 2000 into the text entry area and press Enter or Return, as shown in Figure 4-14.

    Figure 4-14 Configuring the Right-hand-side Operand of a Test in a Rule

    Description of Figure 4-14 follows
    Description of "Figure 4-14 Configuring the Right-hand-side Operand of a Test in a Rule"

4.3.3 What You Need to Know About Oracle Business Rules Test Variables

Oracle Business Rules test variables provide a way to shorten lengthy expressions that occur in rule and decision table conditions and actions. The variable and its value can be represented as an inline business term definition. The test variables are also called as inline aliases.

The option to insert test variables appears as a list next to <insert test> in the rules condition section. As part of the definition of rule condition, you can define a variable to represent a complex expression, a mathematical expression, or callouts to functions.

For example you have an XML fact called Song that has an attribute as composer having a function called size. When referring to the attribute, instead of using Song.composer.size() every time, you can just define a variable as the following:

lo = Song.composer.size()

Subsequently, in tests, you can use lo as part of your expressions. The expression can be anything from a simple to a complex expression. For example, in the body of a function, if you click <insert action>, you can see expression as a part of the available options.

Figure 4-15 displays a test variable.

Figure 4-15 Rules Test Variable

Description of Figure 4-15 follows
Description of "Figure 4-15 Rules Test Variable"

Once you define an inline alias, for subsequent test conditions, the inline alias is available in the list of the operands. The scope of an inline alias is restricted to the subsequent tests in a particular rule, in which the inline alias is defined. In case of a nested test, you can still use the inline alias, because the nested test is a part of the base test where you have defined the alias. This is true even for any test that you define even within the nested test. The scope of the inline alias is not just restricted to the test conditions of the base and its nested test, but also to the actions of that rule. If the inline alias is defined as a part of a nested test condition and not as a part of the main test condition, even then the alias will be available to all the subsequent test conditions and actions within or outside the main nested test.

However, if you define an inline alias inside a not nested test, then the scope of the inline alias is restricted only to the subsequent tests inside the not nested test and not to any tests that are outside the not nested test.

The inline aliases can be used both in If-Then rules as well as Decision Tables. In a Decision Table, in advanced mode, you can show or hide patterns as well as enter a pattern by clicking <insert pattern>. After you insert a pattern, you can insert tests. In normal mode, you can show or hide tests as well as enter a test by clicking <insert test>.

4.3.4 How to Define Range Tests in Rules

To create a range test in a rule, you add conditions for facts. For example, with a sample CustomerOrder fact with an annual spending property, you can add a test to determine if the value of a customer order falls between an upper and lower range.

The following summarizes this sample rule:

IF  
     CustomerOrder.annualSpending between 100 and 2000
THEN
     Modify CustomerOrder.value = "Normal"

At runtime, when this rule is processed the Rules Engine checks the facts against rule pattern tests that you define to find matching facts.

To define range tests in rules:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.

  2. In the View field, select IF/THEN Rules (this is the Rules Designer default).

  3. Add or select the rule you want to use, for example, select Rule_1.

  4. In Rule_1, in the IF area, select <insert test>.

  5. The test in the IF area of a rule includes a left-hand side <operand> and a right-hand-side <operand>, as shown in Figure 4-16.

    Figure 4-16 Rule Test with Left-hand-side operand and Right-hand-side operand

    Description of Figure 4-16 follows
    Description of "Figure 4-16 Rule Test with Left-hand-side operand and Right-hand-side operand"

  6. In a range test, you replace the left-hand-side operand with a value.

    To do this, select the left-hand-side <operand>. This displays a text entry area and a list, as shown in Figure 4-17:

    Figure 4-17 Adding a Test Left-hand-side Operand to a Rule

    Description of Figure 4-17 follows
    Description of "Figure 4-17 Adding a Test Left-hand-side Operand to a Rule"

    1. To enter a value, use the list to select an item from the value options.

      You can view the options using a single list, by selecting List View, or using a navigator by selecting Tree View.

    2. To enter a literal value, type the value into the text entry area and press Enter. The value you enter must agree with the type of the corresponding operand.

      For example, in the test IF CustomerOrder.annualSpending > <operand>, valid values for <operand> must agree with the type of CustomerOrder field annualSpending.

  7. In a range test, you choose the between operator. To do this, select the default == operator. This displays a text entry area and a list. Select between as shown in Figure 4-18.

    Figure 4-18 Configuring the Operator of a Range Test in a Rule

    Description of Figure 4-18 follows
    Description of "Figure 4-18 Configuring the Operator of a Range Test in a Rule"

    This adds two more <operand> placeholders as shown in Figure 4-19.

    Figure 4-19 Between Operator in a Range Test

    Description of Figure 4-19 follows
    Description of "Figure 4-19 Between Operator in a Range Test"

  8. Configure the <operand> placeholders as you would for any operand as shown in Figure 4-20.

    Figure 4-20 Configuring the Operand of a Range Test in a Rule

    Description of Figure 4-20 follows
    Description of "Figure 4-20 Configuring the Operand of a Range Test in a Rule"

    The test is true when the left-most operand (CustomerOrder.annualSpending) is between the values 100 and 2000.

4.3.5 How to Define Set Tests in Rules

To create a set test in a rule, you add conditions for facts. For example, with a sample CustomerOrder fact with a line item property you can add a test to determine if the line item belongs to an arbitrary set of products.

The following summarizes this sample rule:

IF  
     CustomerOrder.lineItem.sku in 12345, 43255, 76348
THEN
     Modify CustomerOrder.value = "High"

At runtime, when this rule is processed the Rules Engine checks the facts against rule pattern tests that you define to find matching facts.

To define set tests in rules:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.

  2. In the View field, select IF/THEN Rules (this is the Rules Designer default).

  3. Add or select the rule you want to use, for example select Rule_1.

  4. In Rule_1, in the IF area select <insert test>.

  5. The test in the IF area of a rule includes a left-hand side <operand> and a right-hand-side <operand>, as shown in Figure 4-10.

    Figure 4-21 Rule Test with Left-hand-side operand and Right-hand-side operand

    Description of Figure 4-21 follows
    Description of "Figure 4-21 Rule Test with Left-hand-side operand and Right-hand-side operand"

  6. In a set test, you replace the left-hand-side operand with a value.

    To do this, select the left-hand-side <operand>. This displays a text entry area and a list as shown in Figure 4-22:

    Figure 4-22 Adding a Test Left-hand-side Operand to a Rule

    Description of Figure 4-22 follows
    Description of "Figure 4-22 Adding a Test Left-hand-side Operand to a Rule"

    1. To enter a value use the list to select an item from the value options.

      You can view the options using a single list, by selecting List View, or using a navigator by selecting Tree View.

    2. To enter a literal value, type the value into the text entry area and press Enter.

  7. In a set test, you use the in operator. To do this, select the default == operator. This displays a text entry area and a list. Select in as shown in Figure 4-23.

    Figure 4-23 Configuring the Operator of a Set Test in a Rule

    Description of Figure 4-23 follows
    Description of "Figure 4-23 Configuring the Operator of a Set Test in a Rule"

    This adds two more <operand> placeholders in a comma separated list and an <insert> placeholder as shown in Figure 4-24.

    Figure 4-24 In Operator in a Set Test

    Description of Figure 4-24 follows
    Description of "Figure 4-24 In Operator in a Set Test"

    To add another operand to the list, click <insert>.

    To delete an operand from the list, right-click the operand and select Delete Test Expression.

  8. Configure the <operand> placeholders as you would for any operand as shown in Figure 4-25.

    Figure 4-25 Configuring the Operands of a Set Test in a Rule

    Description of Figure 4-25 follows
    Description of "Figure 4-25 Configuring the Operands of a Set Test in a Rule"

    The test is true when the value of the left-most operand (CustomerOrder.lineItem.sku) is any of 12345, 43255, or 76348.

4.3.6 How to Define Actions in Rules

To create a rule you insert tests and you insert actions. The actions are associated with pattern matches. When a test in the IF area of a rule matches, the Rules Engine activates the THEN action and prepares to run the actions associated with the rule.

When you add an action, you use one of the forms of actions shown in Table 4-2. For each form shown in Table 4-2 the options that Rules Designer presents are context sensitive, so the lists and the number of items you work with may be different, depending on which action you add and the choices you make while you enter the action. Table 4-2 shows the basic actions; additional actions are available with Advanced Mode. For more information on advanced mode see Section 4.5, "Using Advanced Settings with Rules and Decision Tables".

Table 4-2 Rule Action Choices

Action Form Description

Assert New

Assert a new fact

Modify

Modify a data value associated with a matched fact

Retract

Retract a fact

Call

Call a function

If, else, elseif, for, while

Conditional actions

To define actions in rules:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.

  2. In a rule, in the THEN area, select <insert action>. This displays the add action list as shown in Figure 4-26.

    Figure 4-26 Adding a Modify Action to a Rule

    Description of Figure 4-26 follows
    Description of "Figure 4-26 Adding a Modify Action to a Rule"

  3. In the add action list, select the type of action you want to add. For example, select modify. You can add any required action ranging from assert, call, modify to even conditional actions such as if, else, elseif, while, for, if (advanced), and while (advanced) as shown in

  4. In the THEN area, select <target> to display the option list. For example, select customerOrder as shown in Figure 4-27.

    Figure 4-27 Adding Modify Action to a Rule and Selecting the Target

    Description of Figure 4-27 follows
    Description of "Figure 4-27 Adding Modify Action to a Rule and Selecting the Target"

  5. Select <add property>. This displays the Properties dialog.

  6. In the Properties dialog, in the Value column, enter "High" (include the double quotation marks) and press Enter or Return as shown in Figure 4-28.

    Figure 4-28 Adding Modify Action Property and Value to a Rule

    Description of Figure 4-28 follows
    Description of "Figure 4-28 Adding Modify Action Property and Value to a Rule"

  7. In the Properties dialog, click Close. This displays the rule as shown in Figure 4-29.

    Figure 4-29 Rule with Test and Action Added

    Description of Figure 4-29 follows
    Description of "Figure 4-29 Rule with Test and Action Added"

4.3.7 What You Need to Know About Rule Actions

A rule loop occurs when the value for a condition is changed by an action. Loops can occur across rules in a single rule, spread over several Decision Tables, or spread over rules and Decision Tables in the same ruleset. You need to avoid creating rule actions that modify fact properties that are used in rule conditions. At runtime, such rules could cause an infinite loop.

4.3.8 What You Need to Know About Oracle Business Rules Performance Tuning

In most cases, writing of rules should not require a focus on performance. However, there are tips that can that help you to enhance and maximize rule performance.

For more information on Oracle Business Rules performance tuning, see "Oracle Business Rules Performance Tuning" in Oracle Fusion Middleware Performance and Tuning Guide.

4.4 Validating Dictionaries

Rules Designer performs dictionary validation when you make any change to the dictionary. Rules Designer validation can assist you when you work with rules or Decision Tables. To show the validation log window, click the Validate icon or select View>Log and select the Business Rule Validation tab. This displays warnings for incorrect or incomplete rules. Note that you must correct all warnings before you can test or deploy rules.

When a dictionary is invalid, Rules Designer produces a list of warning messages and lists the associated dictionary objects. You can use the validation message information to locate the dictionary object and to correct problems. In addition, Rules Designer flags objects with validation warnings with a validation indicator (a red, wavy underline), as shown in Figure 4-30.

Figure 4-30 Validation Warnings Shown in Log and On Screen with Wavy Underline

Description of Figure 4-30 follows
Description of "Figure 4-30 Validation Warnings Shown in Log and On Screen with Wavy Underline"

If a dictionary is invalid, you can save the dictionary. However, you can only generate RL Language for a dictionary that is valid and does not display warnings in the Rules Designer validation log.

In the validation log, each validation message includes the following:

  • Message: The message provides details on the Oracle Business Rules exception that describes the problem.

  • Dictionary Object: This field displays a path that indicates details that should allow you to identify a component in the dictionary.

  • Property: provides information on a property of the object associated with the warning message.

When you are viewing the validation log, if you select an item and then right-click and select from the list Select and Highlight Object in Editor, Rules Designer moves the cursor to select the dictionary object. Note that for some validation warnings this functionality is not possible.

4.4.1 Understanding Data Model Validation

Rules Designer performs dictionary validation when you make any change to the dictionary. When Rules Designer displays a warning message, the validation log includes a message that should assist you in locating the dictionary object that caused the validation warning. For example, the following string indicates that the warning originates from the data model object named RLFact_1. In addition, the problem is in the property named test_int:

CarRental/Data Model/RLFact_1/test_int/Expression

Table 4-3 specifies the parts of the dictionary object name specified in a validation message.

Table 4-3 Data Model Dictionary Property in Validation Log

Name Description

CarRental

Dictionary Name

Data Model

Data Model component in dictionary.

RLFact_1

Element name in data model

test_int

Property name in the specified element.

Expression

Expression part of property.

For more information, see:

4.4.2 Understanding Rule Validation

When you click the Validate icon Rules Designer displays the validation log. When you first add a rule you see validation warnings similar to those shown in Figure 4-31.

Figure 4-31 Rules Validation Messages

Description of Figure 4-31 follows
Description of "Figure 4-31 Rules Validation Messages"

The dictionary object name part of a validation message for a rule includes details that help you to identify the ruleset, the rule, and an area in the rule that is associated with the validation warning. For example, the following dictionary object specification indicates a problem:

OracleRules1/Ruleset_2/Rules_1/Pattern[1]

In validation messages, the dictionary object name for a rule uses indexes that start at 1. Thus, the first pattern is Pattern[1].

In addition to validating rules, you can also test them in Rules Designer as you are designing them. For more information, see Section 8.1.5, "How to Test a Decision Function Using an Oracle Business Rules Function".

4.4.3 Understanding Decision Table Validation

When you click the Validate icon Rules Designer displays the validation log. When you first add a Decision Table you see validation warnings similar to those shown in Figure 4-32.

Figure 4-32 Decision Table Validation Messages

Description of Figure 4-32 follows
Description of "Figure 4-32 Decision Table Validation Messages"

The dictionary object name part of a validation message for a Decision Table includes details that help you to identify the area of the Decision Table that is associated with the validation warning. For example, the following dictionary object specification indicates a problem in the first action row, and the first action cell of the Decision Table:

OR1/Ruleset_1/DecisionTable_1/Action[1]/Action Cell[1]

In validation messages the dictionary object name for a Decision Table object uses indexes that start at 1. For example, to indicate the first condition cell in the first row in the Conditions area, the message is as follows:

OracleRules1/Ruleset_1/DecisionTable_2/Condition[1]/Condition Cell[1]

This specification indicates the condition cell for the rule with the label R1 in the first row of the Conditions area in a Decision Table as shown in Figure 4-33.

Figure 4-33 Decision Table with Warning on a Condition Cell

Description of Figure 4-33 follows
Description of "Figure 4-33 Decision Table with Warning on a Condition Cell"

4.4.4 How to Validate a Dictionary

Rules Designer performs dictionary validation when you make any change to the dictionary.

To validate a dictionary:

  1. In Rules Designer, click the Validate icon (a checkmark).

  2. Select the Business Rule Validation log from the messages area.

  3. When you are viewing the validation log, if you select an item and then right-click and select from the list Select and Highlight Object in Editor, Rules Designer moves the cursor to select the dictionary object. Note that for some validation warnings this functionality is not possible.

4.5 Using Advanced Settings with Rules and Decision Tables

Advanced settings for rules and Decision Tables let you work with features that provide advanced options that not all Oracle Business Rules users need. These features include:

4.5.1 How to Show and Hide Advanced Settings in a Rule or Decision Table

In Rules Designer, next to each rule name and Decision Table name, the show or hide advanced settings icon lets you show and hide advanced settings.

To show and hide advanced settings in a rule or decision table:

  1. Select the ruleset where you want to show advanced settings.

  2. In the View field, from the list, select either IF/THEN Rules or select a Decision Table.

    1. To show the advanced settings, next to the rule name click Show Advanced Settings, as shown in Figure 4-34 (there is a highlighted icon shown next to the rule name, Rule_1).

      Figure 4-34 Showing Rules Advanced Settings

      Description of Figure 4-34 follows
      Description of "Figure 4-34 Showing Rules Advanced Settings"

    2. To hide the advanced settings, next to the rule name click Hide Advanced Settings, as shown in Figure 4-35 (there is a highlighted icon shown next to the rule name, Rule_1).

      Figure 4-35 Hiding Advanced Settings in a Rule

      Description of Figure 4-35 follows
      Description of "Figure 4-35 Hiding Advanced Settings in a Rule"

4.5.2 How to Select the Advanced Mode Option

Select Advanced Mode to use Rule or Decision Table features that provide additional pattern matching options and additional actions. For more information, see Section 4.7, "Working with Advanced Mode Rules".

To select the advanced mode option:

  1. Select the rule or Decision Table where you want to set Advanced Mode.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Select Advanced Mode, as shown in Figure 4-36.

    Figure 4-36 Setting Advanced Mode Option

    Description of Figure 4-36 follows
    Description of "Figure 4-36 Setting Advanced Mode Option"

4.5.3 How to Select the Active Option

Oracle Business Rules includes the ability to specify that a rule or a Decision Table is active or inactive. The active option is set independent of the effective dates and may be set without changing or removing previously specified effective dates. When Rule Active is unselected, Rules Designer does not validate the rule.

To select the active option:

  1. Select the rule or Decision Table where you want to set the Rule Active option.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Select Rule Active.

4.5.4 How to Select the Logical Option

A ruleset or Decision Table with the Logical option selected specifies that rules in the generated RL Language use the logical property. The logical property allows you to enable or disable logical dependence between the facts that trigger a rule and the facts asserted by a rule.

A rule with the logical property enabled makes all facts that are asserted by an action block in the rule dependent on facts matched in the rule condition. Anytime a fact referenced in the rule condition changes, such that the rule's conditions no longer apply, the facts asserted by the rule condition are automatically retracted. For more information on the logical property, see Oracle Fusion Middleware Language Reference Guide for Oracle Business Rules.

Using the ruleset and Decision Table Logical option you can enable or disable the logical property for the generated RL Language associated with the rules in the ruleset or the Decision Table. By default, the Logical option is not selected.

To select the logical option:

  1. Select the rule or Decision Table where you want to set the Logical option.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Select Logical.

4.5.5 How to Set a Priority for a Rule

You can set the priority for a rule or a Decision Table. You can select from a predefined named priority list as shown in Table 4-4, or enter a positive or negative integer to specify your own priority level. Higher priority rules run before lower priority rules, within a ruleset. The default priority is medium (with the integer value 0).

Table 4-4 Priority String Value Mapping

Named Priority Integer Value

highest

3000

higher

2000

high

1000

medium (Default Priority)

0

low

-1000

lower

-2000

lowest

-3000

To set a priority for a rule:

  1. Select the rule or Decision Table where you want to set the priority.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. In the Priority field, specify the priority value:

    1. To specify a named priority, select a named priority from the Priority list as Figure 4-37 shows.

      Figure 4-37 Choosing a Predefined Named Priority

      Description of Figure 4-37 follows
      Description of "Figure 4-37 Choosing a Predefined Named Priority"

    2. To specify an integer priority, click in the Priority field and enter a positive or negative integer value and press Enter, as Figure 4-38 shows.

      Figure 4-38 Choosing a User Defined Numeric Priority

      Description of Figure 4-38 follows
      Description of "Figure 4-38 Choosing a User Defined Numeric Priority"

4.5.6 How to Specify Effective Dates

You can specify effective dates for a ruleset, a rule, or a Decision Table.

To specify effective dates:

  1. Select the rule or Decision Table where you want to set the effective date.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Select the Effective Date field. This displays the Set Effective Date dialog.

  4. Use the Set Effective Date dialog to set the effective date.

For more information on using effective dates, see Section 4.9, "Using Date Facts, Date Functions, and Specifying Effective Dates" and Section 4.2.2, "How to Set the Effective Date for a Ruleset".

4.6 Working with Nested Tests

In a rule or a Decision Table you can create more complicated tests using the nested tests feature.

4.6.1 How to Use Nested Tests

To use nested tests:

  1. Select the rule where you want to use a nested test.

  2. In the IF area, select a test. This surrounds the test with a highlighted box.

  3. With a test selected right-click to display the list, as shown in Figure 4-39.

    Figure 4-39 Adding a Nested Test to a Rule

    Description of Figure 4-39 follows
    Description of "Figure 4-39 Adding a Nested Test to a Rule"

  4. To add the nested test, from the list select either Insert Before or Insert After and then select Nested Test. A nested test is shown in Figure 4-40.

    Figure 4-40 A Nested Test Added to a Rule

    Description of Figure 4-40 follows
    Description of "Figure 4-40 A Nested Test Added to a Rule"

4.7 Working with Advanced Mode Rules

Oracle Business Rules provides features that allow you to create advanced rules that add support for the following Oracle Business Rules features:

For more information, see Section 4.7.5, "What You Need to Know About Advanced Mode Rules".

4.7.1 How to Use Advanced Mode Pattern Matching Options

The advanced mode pattern matching options specify when a rule should fire. Table 4-5 shows the available options.

Table 4-5 Advanced Mode Pattern Matching Options

Option Description

for each case where

This is the default pattern matching option. A rule should fire each time there is a match (for all matching cases).

there is a case where

This option selects one firing of the rule if there is at least one match.

there is no case where

The value specifies that the rule fires once if there are no such matches.

aggregate

This specifies an aggregate function is applied to all matches. For more information, see Section 4.7.4, "How to Use Advanced Mode Aggregate Conditions".

To use advanced mode pattern matching options:

  1. Select the rule or Decision Table where you want to use pattern matching options.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Select Advanced Mode.

  4. Right-click a test pattern and select Surround With... as shown in Figure 4-41.

    Figure 4-41 Surrounding With Option

    Description of Figure 4-41 follows
    Description of "Figure 4-41 Surrounding With Option"

    The Surround With dialog appears as shown in Figure 4-42.

    Figure 4-42 Surround With Dialog

    Description of Figure 4-42 follows
    Description of "Figure 4-42 Surround With Dialog"

  5. Choose the Pattern Block option from the Surround With dialog and click OK.

    The pattern is surrounded by a nested pattern with the default (for each case where) as shown in Figure 4-43.

    Figure 4-43 Default Pattern Matching Option: for each case where

    Description of Figure 4-43 follows
    Description of "Figure 4-43 Default Pattern Matching Option: for each case where"

  6. Select the default (for each case where) option and select the desired pattern matching option from the list as shown in Figure 4-44.

    Figure 4-44 Adding an Advanced Pattern Match Option

    Description of Figure 4-44 follows
    Description of "Figure 4-44 Adding an Advanced Pattern Match Option"

4.7.2 How to Use Advanced Mode Matched Fact Naming

The matched fact name field, pattern binding variable, in a rule or a Decision Table lets you test multiple instances of the same type in a single rule. The matched fact name lets you enter a temporary name for the matched fact to use in a test. For example, the rules shown in Figure 4-45 show the use of pattern binding variables in a rule that applies a discount on a shoe item when an order includes at least one "matching" hat item.

Figure 4-45 Rule Using a Pattern Binding Variable

Description of Figure 4-45 follows
Description of "Figure 4-45 Rule Using a Pattern Binding Variable"

For example, you can create the rule, as shown in Figure 4-46 to find duplicate items in a customer order. This example shows the use of matched in a rule.

Figure 4-46 Rule to Find Duplicate Items in an Order

Description of Figure 4-46 follows
Description of "Figure 4-46 Rule to Find Duplicate Items in an Order"

To use advanced mode matched fact naming:

  1. Select the rule or Decision Table where you want to add a matched fact name.

  2. Click the Show Advanced Settings icon next to the rule name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Select Advanced Mode.

  4. Select the <fact type> and enter a fact type from the list.

  5. Select the supplied matched fact name and modify it as needed, as shown in Figure 4-47. For example, enter the matched fact name Order$LineItem1 and then press Enter.

    Figure 4-47 Adding a Matched Fact Variable Name

    Description of Figure 4-47 follows
    Description of "Figure 4-47 Adding a Matched Fact Variable Name"

  6. Create the rule as Figure 4-48 shows. Note that you can choose a matched fact name as an operand. Choose the LineItem1 and LineItem2 operands as needed to create the rule.

    Figure 4-48 Choosing a Matched Fact Variable Name as an Operand

    Description of Figure 4-48 follows
    Description of "Figure 4-48 Choosing a Matched Fact Variable Name as an Operand"

Note in Figure 4-48 that the test checking:

RL.get fact ID(Order$LineItem1) > RL.get fact ID(Order$LineItem2)

Prevents a single instance of an Order$LineItem from matching both patterns that match the Order$LineItem fact type. The ">" is required so that the rule does not fire for different permutations of different instances. For more information, see Appendix C, "How Do I Correctly Express a Self-Join?".

4.7.3 How to Use Advanced Mode Action Forms

When you create a rule with Advanced Mode, Rules Designer presents a list with the available actions shown in Table 4-6. For each form shown in Table 4-6, the options that Rules Designer presents are context sensitive. Thus, the lists and the number of items you see when you work with the action types are context sensitive, depending on which action you add and the choices you make while you enter the action.

Table 4-6 Advanced Mode Action Options

Action Form Description

Assert

Assert a fact

Assert Tree

Asserts a tree of facts given the root.

Assert New

Assert a new fact.

Assign

Assign a value to a variable.

Assign New

Assign a value to a new variable.

Expression

Perform expression.

Call

Call a function.

For

Oracle RL, like Java, has a for loop. A for loop includes a type with a variable and a collection. The type and variable defines the loop variable that holds the collection value used within the loop. Collection is an expression that evaluates to a collection of the correct type for the loop variable. You can use a for loop to iterate through any collection.

A return, throw, or halt may exit the action block.

If

Using the if else action, if the test is true, execute the first action block, and if the test is false, execute the optional else part, which may be another if action or an action block. Oracle RL, unlike Java, requires action blocks and does not allow a single semicolon terminated action.

Modify

Modify a data value associated with a matched fact.

Retract

Retract a fact.

Return

The return action returns from the action block of a function or a rule. A return action in a rule pops the ruleset stack, so that execution continues with the activations on the agenda that are from the ruleset that is currently at the top of the ruleset stack.

rl

Use an Oracle RL expression that you supply.

synchronized

As in Java, the synchronized action is useful for synchronizing the actions of multiple threads. The synchronized action block lets you acquire the specified object's lock, then execute the action-block, then release the lock.

throw

Throw an exception, which must be a Java object that implements java.lang.Throwable. A thrown exception may be caught by a catch in a try action block.

try

The try, catch, and finally in Oracle RL is like Java both in syntax and in semantics. There must be at least one catch or finally clause.

while

While the test is true, execute the action block. A return, throw, or halt may exit the action block.

To use advanced mode action forms:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.

  2. Select or add a rule or a Decision Table.

  3. In the rule or Decision Table click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  4. Select Advanced Mode.

  5. With the insertion areas showing, in a rule in the THEN area select <insert action>. This displays the action list, as shown in Figure 4-49.

    Figure 4-49 Adding an Action to a Rule in Advanced Mode

    Description of Figure 4-49 follows
    Description of "Figure 4-49 Adding an Action to a Rule in Advanced Mode"

  6. In the list select the action you want to add.

    For example, select assign new.

  7. In the THEN area, select the context sensitive parameters for the action and enter appropriate values.

4.7.4 How to Use Advanced Mode Aggregate Conditions

When you create a rule with Advanced Mode, Rules Designer supports the pattern matching aggregate option. When you write rule conditions that are based not only on one fact, but on many facts, you can use an aggregate. You use aggregate functions when the conditions have a view spanning multiple facts.

Table 4-7 shows the available aggregate functions.

Table 4-7 Aggregate Functions for Advanced Mode Rules

Function Description

count

Count of matching facts.

average

Average of matching facts.

maximum

Maximum value of matching facts.

minimum

Minimum value of matching facts.

sum

Sum of matching facts.

collection

Builds a list of matching facts.

For example, to write a rule that specifies a special order as follows:

IF 
   an order has more than 5 line items whose price is above a certain value
THEN 
   the order requires manual approval

The five line items may span multiple facts. Thus, you can use the count aggregate function to write this sample special order rule.

When you use an aggregate function, do the following:

  • Select aggregate for the pattern.

  • Enter a function from the list shown in Table 4-7

  • Enter or select values from the context sensitive menus:

    • <variable> A name for the aggregate value.

    • <expression> The value to aggregate, for example driver.age. When the aggregate function you select is the count function the <expression> is not used.

For example, you can compute the sum of the cost all the line items with color "red", as shown in Figure 4-50.

Figure 4-50 Using Aggregate Functions with Rules Red Color Total Cost Rule

Description of Figure 4-50 follows
Description of "Figure 4-50 Using Aggregate Functions with Rules Red Color Total Cost Rule"

To use advanced mode aggregates:

  1. Select or create the rule or Decision Table where you want to use an aggregate function.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Select Advanced Mode.

  4. Enter the fact type you want to work with.

  5. Select <insert pattern> to add a pattern.

  6. Select the new pattern.

  7. Right-click the pattern and select Surround With.... This displays the Surround With dialog.

  8. In the Surround With dialog select Pattern Block. For more information, see Section 4.7.1, "How to Use Advanced Mode Pattern Matching Options".

  9. Click OK.

  10. In the pattern select the first field. By default this field contains (for each case where), as shown in Figure 4-51.

    Figure 4-51 Adding an Advanced Pattern Match Option

    Description of Figure 4-51 follows
    Description of "Figure 4-51 Adding an Advanced Pattern Match Option"

  11. Select the aggregate option. This adds the context sensitive fields for an aggregate, as shown in Figure 4-52.

    Figure 4-52 Using Aggregate Functions in a Rule

    Description of Figure 4-52 follows
    Description of "Figure 4-52 Using Aggregate Functions in a Rule"

  12. Click <function> and select a function from the list.

  13. In the condition, click <fact type> and select a fact type from the list.

  14. Click <expression> and select an expression from the list.

  15. Rules Designer by default constructs variable names as you create the aggregate pattern. If needed for the rule you are constructing enter variable names to replace the default variable names. Figure 4-53 shows a completed rule using aggregate. In this example, for clarity the rule shows the variable names total_cost and item_x.

    Figure 4-53 Completed Aggregate Function in a Rule

    Description of Figure 4-53 follows
    Description of "Figure 4-53 Completed Aggregate Function in a Rule"

  16. Enter additional tests as required. For this example you enter the test for items with color "red", as Figure 4-54 shows.

Figure 4-54 Using Aggregate Functions with Rules Red Color Total Cost Rule

Description of Figure 4-54 follows
Description of "Figure 4-54 Using Aggregate Functions with Rules Red Color Total Cost Rule"

4.7.5 What You Need to Know About Advanced Mode Rules

There are some special cases to keep in mind when you work with Advanced Mode rules, including the following:

  • When you work with aggregates, in actions, you do not see pattern variables. The pattern variables are only shown for action lists when you use (foreach...) patterns. Thus, you cannot see pattern variables in aggregate, "there is a case", or "there is no case patterns".

  • After you select Advanced Mode the Advanced Mode stays selected and inactive (gray), as long as your rule uses advanced options such as advanced pattern matching. To deselect Advanced Mode you must remove or undo the advanced mode features (sometimes it is easier to start over by creating a non-advanced mode rule and then delete the advanced mode rule).

To deselect the advanced mode option:

  1. Select the rule or Decision Table where you want to deselect Advanced Mode.

  2. Click the Show Advanced Settings icon next to the rule or Decision Table name (see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table").

  3. Consider the state of the rule:

    • If you can simplify the rule to enable the Advanced Mode option (such that the Advanced Mode icon changes from gray to enabled). Then simplify the rule and when Advanced Mode is enabled, deselect Advanced Mode.

    • If you can use Undo to undo the steps you used to create the Advanced Mode rule, to get to a state where the rule is no longer in Advanced Mode, then use this technique to simplify the rule.

    • If you cannot simplify the rule, then delete the rule and re-create it.

4.8 Working with Tree Mode Rules

Tree Mode rules make it easier to work with a master detail hierarchy, where there are nested elements that map to a parent child relationship.

4.8.1 Introduction to Tree Mode Rules

To introduce tree mode rules, it is instructive to work with an example. Consider the lifecycle of an application fragment that uses business processes and rules to process a retail purchase order (PO). The purchase order has a header with business terms that apply to the entire PO. The PO also contains a list of shipping destinations. Each destination has an address, a list of items to be shipped to the destination's address, and a list of shipments.

Consider the business rule: the status of a PO is "fully shipped" if the status of every item is either "shipped" or "canceled".

Figure 4-55 shows a sample XML schema representation for the PO example. The XML documents for the PO are tree structured. This allows a natural representation for the PO. For example, the PO itself is the top level document element and destinations are nested elements that contain item elements and shipment elements. Shipment elements also contain item elements that reference the ordered items. Status has a list of valid values.

Figure 4-55 PO Schema for Tree Mode Rules Sample

Description of Figure 4-55 follows
Description of "Figure 4-55 PO Schema for Tree Mode Rules Sample"

Example 4-1 shows the sample purchase order XML schema as represented in Figure 4-55.

Example 4-1 Sample Purchase Order (PO) Schema

<?xml version= '1.0' encoding= 'UTF-8' ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.example.org"
targetNamespace="http://www.example.org"
     elementFormDefault="qualified">
    <xsd:element name="PO">
        <xsd:annotation>
            <xsd:documentation>A sample element</xsd:documentation>
        </xsd:annotation>
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="header">
                    <xsd:complexType>
                        <xsd:attribute name="status" type="Status"/>
                        <xsd:attribute name="order-date" type="xsd:date"/>
                        <xsd:attribute name="customer-value"/>
                    </xsd:complexType>
                </xsd:element>
                <xsd:element name="billing">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element name="address"/>
                            <xsd:element name="payment"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
                <xsd:element name="destination" maxOccurs="unbounded">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element name="address"/>
                            <xsd:element name="item" maxOccurs="unbounded">
                                <xsd:complexType>
                                    <xsd:attribute name="ID"/>
                                    <xsd:attribute name="status"/>
                                    <xsd:attribute name="quantity" type="xsd:int"/>
                                    <xsd:attribute name="availability-date" type="xsd:date"/>
                                    <xsd:attribute name="qoh" type="xsd:int"/>
                                    <xsd:attribute name="price"
                                                   type="xsd:decimal"/>
                                </xsd:complexType>
                            </xsd:element>
                            <xsd:element name="shipment" minOccurs="0" maxOccurs="unbounded">
                                <xsd:complexType>
                                    <xsd:sequence>
                                        <xsd:element name="item" maxOccurs="unbounded">
                                            <xsd:complexType>
                                                <xsd:attribute name="ID"/>
                                                <xsd:attribute name="quantity"/>
                                            </xsd:complexType>
                                        </xsd:element>
                                    </xsd:sequence>
                                    <xsd:attribute name="ship-date"/>
                                    <xsd:attribute name="method"/>
                                </xsd:complexType>
                            </xsd:element>
                        </xsd:sequence>
                        <xsd:attribute name="status" type="xsd:string"/>
                    </xsd:complexType>
                </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:simpleType name="Status">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="open"/>
            <xsd:enumeration value="partially shipped"/>
            <xsd:enumeration value="fully shipped"/>
        </xsd:restriction>
    </xsd:simpleType>
</xsd:schema>

Example 4-2 shows part of the XML for an instance of the PO schema. To use tree mode rules you can create a rule that tests one or more business terms and if the tests pass, one or more business terms are added or changed. Oracle Business Rules has special support to enable error-free authoring of rules on fact trees like the sample PO instance.

For example, consider creating a rule for an instance of the PO schema that states:

IF the time between the order date and the date for availability of an item is more than 30 days
THEN cancel the item

Example 4-2 Sample Abbreviated PO XML Instance

<PO xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.example.org ../../../../Temp/PO.xsd"
    xmlns="http://www.example.org">
  <header/>
  <billing>
    <address/>
    <payment/>
  </billing>
  <destination>
    <address/>
    <item ID="a01"/>
    <item ID="a02"/>
    <item ID="a03"/>
    <shipment>
      <item ID="a01"/>
      <item ID="a02"/>
    </shipment>
  </destination>
</PO>

4.8.1.1 Understanding Tree Mode Rules (Non-Advanced Mode)

You use non-advanced tree mode, or simple tree mode, when the Advanced Mode option is not selected and Tree Mode is selected. With this mode Rules Designer shows ROOT: <fact type> where you enter the root fact type, as shown in Figure 4-56.

Figure 4-56 Simple Tree Mode Rule with Tree Mode Selected

Description of Figure 4-56 follows
Description of "Figure 4-56 Simple Tree Mode Rule with Tree Mode Selected"

When you create rules with Tree Mode selected and Advanced Mode unselected you can reference properties in the tree using qualified names, for example:

  • PO/destination/item.quantity that is similar to item.quantity but only items that are a destination of PO are matched.

  • PO$Destination$item.quantity that refers to a List<item>. This reference is unchanged from non-tree mode.

With Simple Tree Mode you can only choose terms that do not require many-to-many joins or aggregation.

For more information, see Section 4.8.2, "How to Create Simple Tree Mode Rules".

4.8.1.2 Understanding Advanced Tree Mode Rules

You use advanced tree mode when the Advanced Mode option is selected and the Tree Mode option is selected. With this mode Rules Designer shows ROOT: <fact type> where you enter the root fact type, as shown in Figure 4-57. Rules Designer shows patterns for the tree structured facts but the simple tests that join the parent and child facts are hidden.

Figure 4-57 Advanced Tree Mode

Description of Figure 4-57 follows
Description of "Figure 4-57 Advanced Tree Mode"

In advanced tree mode the tree mode patterns, except for the root, display as:

<operator> <variable> is a <fact path>

Where the <fact path> is an XPath-like path through the 1-to-1 and 1-to-many relationships starting at the root. For example, each fact path has a name like PO/destination, where PO is the root fact type and the destination is a property of type List. A 1-to-many relationship in a fact path is indicated with a "/", as in PO/destination.

A 1-to-1 relationship in a fact path is indicated with "." This unchanged from non-tree mode. For example, item.availabilityDate.

Advanced mode exposes the concept of a pattern, the simplest of which is is a. For example, p is a PO causes p to match, iterate over, all the PO facts, and d is a p/destination causes d to match all the destinations of p. The left side of is a is a variable, and the right side is a fact type or a fact path. By default, Oracle Business Rules sets the variable name equal to the fact type or path. For example, PO is a PO. A pattern can also be a pattern block. A pattern block has a logical quantifier, negation, or aggregation that applies to the patterns and tests nested inside the block.

For more information, see Section 4.8.3, "How to Create Advanced Tree Mode Rules".

When you work with advanced tree mode rules, Rules Designer expects you to use an aggregation pattern, including exists and not exists to combine terms from different child forests into the same rule while avoiding a Cartesian product.

4.8.2 How to Create Simple Tree Mode Rules

Given the XML schema shown in Example 4-1 and the schema instance shown in Example 4-2, the following procedure creates the PO rule to cancel non 30-day availability items.

IF the time between the order date and the date for availability of an item is more than 30 days
THEN cancel the item

To create simple tree mode rules:

  1. Create an IF/THEN rule in your ruleset.

    For more information, see Section 4.3.1, "How to Add Rules".

  2. View advanced settings.

    For more information, see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table".

  3. Select Tree Mode as Figure 4-58 shows.

    Figure 4-58 Simple Tree Mode Advanced Settings

    Description of Figure 4-58 follows
    Description of "Figure 4-58 Simple Tree Mode Advanced Settings"

  4. Next to ROOT:, click the <fact type> place holder and select PO from the list as Figure 4-59 shows.

    Figure 4-59 Simple Tree Mode: Configuring the Root

    Description of Figure 4-59 follows
    Description of "Figure 4-59 Simple Tree Mode: Configuring the Root"

  5. Select <insert test>.

    The IF statement now reads IF <operand> == <operand>.

  6. Select the left-hand <operand>.

  7. In the list, select PO/destination/item.availabilityDate.

  8. Select Expression Builder icon, as shown in Figure 4-60.

    Figure 4-60 Adding Simple Tree Mode Expression

    Description of Figure 4-60 follows
    Description of "Figure 4-60 Adding Simple Tree Mode Expression"

  9. In the Expression Builder dialog, copy and delete the item shown in the Expression area.

  10. In the Expression Builder, select the Functions tab.

  11. In the navigator, expand Duration and double-click the daysbetween function.

  12. Remove the daysbetween argument templates, as shown in Figure 4-61.

    Figure 4-61 Using Expression Builder to Add a Simple Tree Mode Rule

    Description of Figure 4-61 follows
    Description of "Figure 4-61 Using Expression Builder to Add a Simple Tree Mode Rule"

  13. In the daysbetween function, paste the value you previously cut as the second argument.

  14. In the Expression Builder dialog, select the Variables tab.

  15. For the daysbetween function first argument, use the navigator to expand PO and expand header, and double-click orderDate.

  16. In the Expression Builder dialog, click OK.

  17. In the list, in the expression area and press Enter.

  18. Select the operator and enter >.

  19. Select the right-hand <operand> and enter the value 30 and press Enter, as shown in Figure 4-62.

    Figure 4-62 Simple Tree Mode: Right-Hand Operand with Value 30

    Description of Figure 4-62 follows
    Description of "Figure 4-62 Simple Tree Mode: Right-Hand Operand with Value 30"

  20. Click <insert action> and from the list select modify.

    The THEN statement now reads: THEN modify <target>.

  21. Click <target> and from the list select PO/destination/item. The THEN statement now reads:

    THEN modify PO/destination/item ( <add property> )

  22. Click <add property>. This displays the properties dialog.

  23. In the properties dialog for the status name, enter the value "canceled", as Figure 4-63 shows.

    Figure 4-63 Simple Tree Mode: Action

    Description of Figure 4-63 follows
    Description of "Figure 4-63 Simple Tree Mode: Action"

  24. In the Properties dialog, click Close.

  25. This displays the finished rule, as shown in Figure 4-64.

    Figure 4-64 Simple Tree Mode Rule Final Rule

    Description of Figure 4-64 follows
    Description of "Figure 4-64 Simple Tree Mode Rule Final Rule"

Note that in the modify statement, PO/destination/item refers to the particular item instance member.

4.8.3 How to Create Advanced Tree Mode Rules

Given the XML schema shown in Example 4-1 and the instance of these facts shown in Example 4-2, the following procedure creates a free shipping rule that can be summarized as:

IF the total cost of "free shipping eligible" items to a given destination is greater than $40
THEN shipping of those items is free

To create advanced tree mode rules:

  1. Create an IF/THEN rule in your ruleset.

    For more information, see Section 4.3.1, "How to Add Rules".

  2. View advanced settings.

    For more information, see Section 4.5.1, "How to Show and Hide Advanced Settings in a Rule or Decision Table".

  3. Select Advanced Mode and select Tree Mode as Figure 4-65 shows.

    Figure 4-65 Advanced Tree Mode Rule for Free Shipping

    Description of Figure 4-65 follows
    Description of "Figure 4-65 Advanced Tree Mode Rule for Free Shipping"

  4. Select the <fact type> place holder and from the list, select PO.

  5. Complete the free shipping rule, as shown in Figure 4-66.

Figure 4-66 Advanced Tree Mode Free Shipping Rule

Description of Figure 4-66 follows
Description of "Figure 4-66 Advanced Tree Mode Free Shipping Rule"

4.8.4 What You Need to Know About Tree Mode Rules

When you select Tree Mode and select a root fact type, the options lists show all available fact types (not just the children of the root fact type). This allows you to view all available fact types as well as the children of the root fact type. There is no option to limit the option list to only show the children of the selected root fact type.

4.9 Using Date Facts, Date Functions, and Specifying Effective Dates

Oracle Business Rules provides functions that make it easier for you to work with times and dates, and provides effective date features to let you determine when rules are effective, based on times and dates:

  • The CurrentDate fact allows you to reason on a fact representing the current date.

  • The Effective Date value lets you specify a start date and end date that defines a date or date and time range when all the rules and Decision Tables in a ruleset, an individual rule, or an individual Decision Table are effective.

Table 4-8 describes the available Effective Date options.

Table 4-8 Effective Date Possible Values

Effective Date Description

Always Valid

Specifies to set neither "From" nor "To" dates.

From (without To date set)

Valid from a certain date indefinitely into the future.

To (without a From date set)

Valid from now until a certain date.

From Set and To set

Valid only between two dates.

An effective date specification other than Always can be one of the following:

  • Date only, with no time specification: In this case, an effective date assumes a time of midnight of that date in each time zone.

  • Date, time zone, with no time specification: In this case, an effective date assumes a time of midnight as of the specified date in the specified time zone.

  • Date, time zone, time specification: In this case, the date and time is fully specified.

  • Time specification only, with no date and no time zone: applies for all days at the specified time.

  • Time and time zone specified, with no date: applies for all days at the specified time.

4.9.1 How to Use the Current Date Fact

You can use the current date fact in a rule or a Decision Table.

To use the CurrentDate fact:

  1. Select a ruleset from the Rulesets navigation tab.

  2. Select a rule within the ruleset.

  3. In the IF area, add a condition that uses the CurrentDate fact and the date method of Calendar type, as shown in Figure 4-67.

    Figure 4-67 Rule with Condition Using CurrentDate Fact

    Description of Figure 4-67 follows
    Description of "Figure 4-67 Rule with Condition Using CurrentDate Fact"

4.9.2 How to Set the Effective Date for a Rule

You can specify an effective start date and or an effective end date for a ruleset, a rule, or a Decision Table. For information on specifying the effective date for a ruleset, see Section 4.2.2, "How to Set the Effective Date for a Ruleset".

To set the effective date for a rule:

  1. Select the ruleset name from the Rulesets navigation tab.

  2. Select a rule within the ruleset.

  3. Next to the rule name click Show Advanced Settings, as shown highlighted in Figure 4-68.

    Figure 4-68 Showing Advanced Settings in a Rule

    Description of Figure 4-68 follows
    Description of "Figure 4-68 Showing Advanced Settings in a Rule"

  4. Select the Effective Date field. This displays the Set Effective Date dialog, as shown in Figure 4-69.

    Figure 4-69 Setting the Effective Date for a Rule

    Description of Figure 4-69 follows
    Description of "Figure 4-69 Setting the Effective Date for a Rule"

  5. Use the Set Effective Date dialog to specify the effective dates for the rule. Clicking the Set Date icon displays a calendar to assist you in entering the From and To field data.

  6. In the Set Effective Date dialog, click OK.

4.9.3 What You Need to Know About Effective Dates

By default, the Oracle Business Rules Engine implicitly manages the clock associated with the CurrentDate fact and the effective date, setting each to the value of the system date. Using the RL Language functions setCurrentDate() and setEffectiveDate() you can explicitly set the current date and the effective date. For more information, see Oracle Fusion Middleware Language Reference Guide for Oracle Business Rules.

An effective start date is defined as the first point in time at which a rule, Decision Table, or ruleset may actively participate in rule evaluations and fire. Thus, if a rule is effective it may fire if its condition is satisfied and if the rule is not effective, it does not fire whether the condition is satisfied or not.

An effective end date is the first moment in time at which the rule, Decision Table, or ruleset no longer actively participates in rule evaluations (not effective means the rule does not fire).

The effective start and end date can be set on a Decision Table, but these dates cannot be set individually for the rules within a Decision Table.

Rules and Decision Tables also include the Rule Active option. This option is set independent of the effective dates and makes dates effective without changing or removing the specified effective date. For more information on using the Rule Active option, see Section 4.5.3, "How to Select the Active Option".

The precedence of the effective date, when it is defined for both a ruleset and for the rules or Decision Tables within a ruleset, is as follows (with the top precedence being 1):

  1. If the ruleset Rule Active option is unselected, then RL Language is not generated for that entity.

  2. If one or both of the effective date properties are selected for a ruleset, then those effective start dates and effective end dates define the range of effective dates allowable for rules or Decision Tables that are defined within the ruleset (that is, if in the ruleset the From checkbox, the To checkbox, or both checkboxes are selected in the Set Effective Date dialog).

    Thus, the effective dates specified for rules or Decision Tables within a ruleset must not violate the boundaries established by the ruleset that contains the rules or Decision Tables. For example, a rule may not have an effective end date that is later than the effective end date specified for a ruleset.

  3. If any individual rule or Decision Table has Rule Active unselected, then RL Language is not generated for that rule or Decision Table.

  4. If the Set Effective Date dialog for a ruleset includes Time selected or this option is selected on a rule or a Decision Table in the ruleset, then all instances of rules or Decision Tables in the ruleset must have Time selected when effective dates are specified. In this case, if Both or Date is selected then Rules Designer shows a validation warning:

    RUL-05742: Calendar form incompatibility detected with forms Time and DateTime.
If the calendar form is set to Time on a rule set or any of the rules or
decision tables within that ruleset then the calendar form for that entire
rule set is restricted to Time.

4.9.4 How to Use Duration, JavaDate, OracleDate, and XMLDate Methods

You can use the Duration, JavaDate, and XMLDate, OracleDate, and OracleDuration extension methods in a rule or a Decision Table. For more information, see Appendix B, "Oracle Business Rules Built-in Classes and Functions".

To use a Duration method:

  1. Select ruleset from the Rulesets navigation tab.

  2. Select a rule within the ruleset (you can also use Duration methods in a Decision Table).

  3. In the IF area, add a condition.

  4. Select an operand in the rule condition.

  5. From the list, select Expression Builder.... For more information, see Section 4.10, "Working with Expression Builder".

  6. In the Expression Builder, select the Functions tab.

  7. In the Expression Builder, in the Navigator, expand the Duration folder.

  8. Double-click to select and insert the appropriate method as needed for your duration test.

  9. Provide the appropriate arguments for the method. For example, see Figure 4-70.

  10. This allows you to create a rule such as that shown in Figure 4-71.

Figure 4-70 Using Duration Methods in a Rule

Description of Figure 4-70 follows
Description of "Figure 4-70 Using Duration Methods in a Rule"

Figure 4-71 Adding a Rule Using Duration Function

Description of Figure 4-71 follows
Description of "Figure 4-71 Adding a Rule Using Duration Function"

4.10 Working with Expression Builder

Use the expression builder to create and edit expressions for Oracle Business Rules.

4.10.1 Introduction to the Expression Builder

You can access the expression builder from different parts of Rules Designer, including in the Edit Globals dialog, and in the conditions area when you work with conditions in Decision Tables, and when you enter rules and Decision Tables in advanced mode with free form expressions selected.

Figure 4-72 shows the Rules Designer expression builder.

Figure 4-72 Rules Designer Expression Builder

Description of Figure 4-72 follows
Description of "Figure 4-72 Rules Designer Expression Builder"

4.10.2 How to Use the Expression Builder

In the expression builder when you double-click items in the Variables or Functions navigation trees, or in the Operators tab, or in the Constants tab, this inserts the item into the expression in the Expression area. You can also create or edit expressions directly by entering text in the Expression area.

When you enter an expression, note that Variables are valid assignment targets and Constants are not valid assignment targets. Thus, you should use both tabs if you are unsure what type of item you want to add to the expression you are building.

Specify an argument for a selected function by placing the cursor inside the function in the Expression field and double-clicking the expression or function to insert. For example, place the cursor inside the parentheses of a function and select a variable. This inserts the variable in the expression at the cursor position.

4.10.3 What You Need to Know About Working with Expressions

XML fact types allow XML Schema types, elements, and attributes to be used when writing rules. Elements and types defined in XML Schema can be imported into the data model and can then be used to create rules and Decision Tables, just as with Java fact types and RL Fact types. The mapping between the XML Schema definition and the XML Fact types uses the Java Architecture for XML Binding (JAXB). By default, Oracle Business Rules uses the JAXB 2.0 shipped with the Oracle Application Server. JAXB as defined in JSR-222 provides a mapping between the types, names, and conventions in an XML Schema definition and the available types, allowed names and conventions in Java. For example, an element named order-id and of type xsd:integer is mapped to a Java Bean property named orderID of type BigInteger (and xsd:int type maps to Java int).

You can use expressions in Oracle Business Rules. Expressions allow arithmetic using the operators *, +, /, %, and other supported operators on primitive numerics, for example double, int, and the numeric types Integer, Long, Short, Float, Double BigDecimal, and BigInteger that are available in the built-in dictionary. For more information on supported primitive numerics, see Oracle Fusion Middleware Language Reference Guide for Oracle Business Rules.

Expressions allow casting between any two numeric types, for example, (short)((BigInteger)1 + (Long)2). Example 4-3 shows a few additional sample expressions.

The expression processor uses the XPath/Xquery rules for type promotion (XML Path Language (XPath) 2.0). For example, BigDecimal is promoted to float/double; type promotion going the other direction requires a cast, except for literals such as 3.3.

Example 4-3 Sample Expressions in Actions with Types and Casting

assign new double db = 3.3
assign new BigDecimal bd = 3.3  // no cast required
assign db = bd // no cast required
assign bd = (BigDecimal)db // cast is required

4.11 Using Bucketsets as Constraints for Options Values in Rules

You can use List of Values Bucketsets and List of Ranges Bucketsets to specify constraints for business terms in rules. This allows you to use Rules Designer to produce validation warnings for possible errors where a value supplied is out of range, or not within a set of possible values as specified in a bucketset. Oracle Business Rules also lets you use bucketsets to specify constraints for global initial values, function return values, or function argument values. For more information, see Section 2.3, "Working with Oracle Business Rules Globals" and Section 3.7, "Associating a Bucketset with Business Terms".

4.11.1 How to Use a List of Ranges Bucketset as a Constraint for a Business Term

You can use a list of ranges bucketset as a constraint for any business term other than a function result.

For more information on using a list of values bucket set as a constraint, see Section 4.11.2, "How to Use a List of Values Bucketset as a Constraint for a Fact Property".

To use a List of Ranges bucketset as a constraint for a fact property:

  1. Specify a bucketset that includes the ranges you want to include and select Allowed in Actions for all valid ranges. To include a range, deselect Allowed in Actions for the top and bottom endpoints.

  2. Select Included Endpoint as needed for the application.

  3. Deselect Include Disallowed Buckets in Tests. For example, for a bucketset that defines valid grades and that does not allow values greater than 100, or less than 0, define the bucketset endpoints as shown in Figure 4-73.

    Figure 4-73 Valid Grades Bucketset for Fact Property

    Description of Figure 4-73 follows
    Description of "Figure 4-73 Valid Grades Bucketset for Fact Property"

  4. Associate this bucketset with a business term. For example, associate the bucketset with test_math1 as shown in Figure 4-74.

    Figure 4-74 Associating a Bucketset with a Fact Property

    Description of Figure 4-74 follows
    Description of "Figure 4-74 Associating a Bucketset with a Fact Property"

Now, if you define a rule with a test that uses the fact property you receive a validation warning when a value is out of range. For example if you define a rule with an expression with the value -10, Rules Designer shows a validation warning as shown in Figure 4-75.

Figure 4-75 Using a Fact Property Value that is not in the Allowed in Actions for Associated Bucketset

Description of Figure 4-75 follows
Description of "Figure 4-75 Using a Fact Property Value that is not in the Allowed in Actions for Associated Bucketset"

4.11.2 How to Use a List of Values Bucketset as a Constraint for a Fact Property

You can use a list of values bucketset as a constraint for a fact property.

For more information on using a list of ranges bucket set as a constraint, see Section 4.11.1, "How to Use a List of Ranges Bucketset as a Constraint for a Business Term".

To use a List of Values bucketset as a constraint for a fact property:

  1. Specify an LOV bucketset that includes the values you want to include, and select Allowed in Actions for all valid values. For more information, see Section 3.6.1, "How to Define a List of Values Global Bucketset".

  2. Deselect Allowed in Actions for the otherwise bucket.

  3. Deselect Include Disallowed Buckets in Tests.

  4. Associate this bucketset with a fact property.

4.11.3 How to Use Bucketsets to Provide Options for Test Expressions

You can use LOV bucketsets to provide options for expressions and actions.

How to use bucketsets to provide options for rule expressions and actions:

  1. In Rules Designer, define an LOV bucketset of a type corresponding to a fact property. For more information, see Section 3.6.1, "How to Define a List of Values Global Bucketset".

  2. Associate the bucketset with a fact property. For more information, see Section 3.7.1, "How to Associate a Bucketset with a Fact Property".

  3. When you enter expressions, Rules Designer shows the bucket values in the values options. For example, when you associate a fact property Driver.eye_test with an LOV bucketset named eyes, with values: pass, fail, and glasses_required, and then you use Driver.eye_test in a test expression, the bucket values are limited as shown in Figure 4-76.

    Figure 4-76 Using a Bucketset to Provide Options for a Rule Test Expression

    Description of Figure 4-76 follows
    Description of "Figure 4-76 Using a Bucketset to Provide Options for a Rule Test Expression"