4 Working with Rulesets and Rules

Ruleset is a Oracle Business Rules data model element that you use to group one or more rules or Decision Tables. Learn how to work with dictionaries, nested tests, and simple and tree mode rules, and Expression Builder.

For more information, see What Are Rulesets?.

4.1 Introduction to Working with Rulesets, Rules, and Business Phrases

Use business rules to define key decisions and policies for a business.

Some of these decisions and policies include:

  • 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 multiple approaches to writing rules:

  • IF/THEN rules - rules are expressed as IF/THEN statements. There are two ways of modeling IF/THEN rules. General rules use a pseudo-code language to express rule logic. Verbal rules use natural language statements to express rule logic.

  • Decision Tables, which display multiple related rules in a single spreadsheet-style view.

Business phrases are used to provide a natural language vocabulary for the construction of verbal rules' tests and actions. They are not used in general rules.

This chapter includes details for working with IF/THEN rules. For information on working with Decision Tables, see Working with Decision Tables.

4.2 Working with Rulesets

A ruleset provides a unit of execution for rules and 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 and off the stack. In rulesets, rule priority specifies the order in which the rules should be fired.

Rulesets also include an effective date specification that controls when a ruleset is active. A ruleset can be:

  • always active

  • active during a time range

  • active during a date range

  • active during a time and date range

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 rule set:

  1. In Rules Designer, go to the Rule Sets tab.
  2. Click the Create rule set button. This displays the Create Rule Set dialog.
  3. Enter a name in the Name field.

    Note:

    The names of ruleset and ruleset alias, business rules, and any other rule objects must begin with a letter and can contain only letters and numbers. They must not contain spaces or special characters like ., -, _, :, ,, "".
  4. Enter a description in the Description field.
  5. Click OK.

4.2.2 How to Set the Effective Date for a Rule Set

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 Using Date Facts_ Date Functions_ and Specifying Effective Dates.

To set the effective date for a ruleset:

  1. Select the ruleset name from the Rule Sets tab.
  2. Click the navigation button 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-1.

    Figure 4-1 Ruleset Showing Effective Date Field

    Description of Figure 4-1 follows
    Description of "Figure 4-1 Ruleset Showing Effective Date Field"
  3. Select the Effective Date entry. This displays the Set Effective Date dialog, as shown in Figure 4-2.

    Figure 4-2 Using the Set Effective Date Dialog

    Description of Figure 4-2 follows
    Description of "Figure 4-2 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 button displays a calendar to assist you in entering the From and To field data.

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 How to Set the Effective Date for a Rule Set.

4.2.3 How to Set the Effective Date for a Rule

You can specify an effective start date and or an effective end date for a rule.

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.
  4. Select the Effective Date field. This displays the Set Effective Date dialog.
  5. Use the Set Effective Date dialog to specify the effective dates for the rule. Clicking the Set Date button displays a calendar to assist you in entering the From and To field data.
  6. In the Set Effective Date dialog, click OK.

4.2.4 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 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-3 shows.

    Figure 4-3 Showing or Hiding a Filter Query in a Rule Set

    Description of Figure 4-3 follows
    Description of "Figure 4-3 Showing or Hiding a Filter Query in a Rule Set"
  3. In the Filter Query field, click <insert test> to insert a default test.

  4. Configure the default test.

    In this case, as shown in Figure 4-4, 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 How to Set a Priority for a Rule.

    start date

    Matches against the rule start date. For more information, see What You Need to Know About Effective Dates.

    end date

    Matches against the rule end date. For more information, see What You Need to Know About Effective Dates.

    minutes until start date

    Matches against a specified number of minutes until the rule start date. For more information, see What You Need to Know About Effective Dates.

    minutes until end date

    Matches against a specified number of minutes until the rule end date. For more information, see What You Need to Know About Effective Dates.

    days until start date

    Matches against a specified number of days until the rule start date. For more information, see What You Need to Know About Effective Dates

    days until end date

    Matches against a specified number of days until the rule end date. For more information, see What You Need to Know About Effective Dates

    years until start date

    Matches against a specified number of years until the rule start date. For more information, see What You Need to Know About Effective Dates

    years until end date

    Matches against a specified number of years until the rule end date. For more information, see What You Need to Know About Effective Dates

    is active

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

    is valid

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

    referenced fact types

    Matches against one or more fact types.

    Figure 4-4 Filter Query Operands

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

    For more information, see How to Define a Test in a Verbal Rule.

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

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

  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 check box.

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

      Figure 4-5 Enable Filter Query in a Rule Set

      Description of Figure 4-5 follows
      Description of "Figure 4-5 Enable Filter Query in a Rule Set"
    2. To disable the filter query, clear the Filter On check box.

      Rules Designer displays all the rules in the ruleset.

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

4.2.5 Using Auto Complete when Selecting Component Values from a List

The Rules Designer enables you to easily set values for the following components of a business rule:

  • Expressions

  • Conditions

  • Operands

  • Actions

You can edit these components by clicking them in the Rules Editor and selecting the desired value from a drop down list or tree. You can also enter the name of the desired value in the text area at the top of the list. When you begin entering text, the list of options are filtered as shown in Figure 4-6.

Figure 4-6 Using the Auto Complete Function

Description of Figure 4-6 follows
Description of "Figure 4-6 Using the Auto Complete Function"

In this figure, only the options beginning with the text entered are displayed.

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 must create a ruleset (or use the default ruleset).

For more information on creating a ruleset, see Working with Rulesets.

You can test rules as you design them without having to deploy your application. For more information, see Testing Decision Functions Using a Rules Function.

Rules Designer rule validation can assist you when you work with rules by showing warnings for incorrect or incomplete rules. To show the validation log window, click the Validate button or select View>Log and select the Business Rule Validation tab. Note that you must correct all warnings before you can test or deploy rules. For more information on rule validation, see 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 How to Use a Filter to Display Matching Rules in a Ruleset.

4.3.1 How to Add General Rules

To create a general rule, first add the rule to a ruleset, and then insert tests and actions. 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.

By default, Rules Designer creates rules which fire for each matching fact. Select Advanced Mode to enable other options, such as a rule in which the same fact type matches more than once, or never. For more information on advanced mode and showing advanced settings, see Using Advanced Settings with Rules and Decision Tables.

To add a general rule to a ruleset:

  1. In Rules Designer, select the Rule Sets tab and click +.
  2. In the Overview tab, in the General Rules panel, click +. Alternatively, in the General Rules tab, click Create Rule or Create (+).

    For example, click Create Rule to add a rule named Rule_1, as shown in Figure 4-8.

    Figure 4-7 Adding a Rule to a Rule Set

    Description of Figure 4-7 follows
    Description of "Figure 4-7 Adding a Rule to a Rule Set"

    Note:

    Delete rules only from the rule editor region by clicking the delete button. Rules do not get deleted cleanly when you delete them from left tree navigation.

4.3.2 How to Add Verbal Rules

Verbal rules are created and executed in a similar fashion to general rules. However, there are some differences.

To create a verbal rule, first add the rule to a ruleset, and then insert tests and actions. As you define a verbal rule, you add business phrases which can either be automatically derived by the system, or defined by you. You can define business phrases before writing a rule, or after.

Verbal rules do not support Advanced Mode or Tree Mode.

To add a verbal rule to a ruleset:

  1. In Rules Designer, select the Rule Sets tab and click +.
  2. In the Overview tab, in the Verbal Rules panel, click +. Alternatively, in the Verbal Rules tab, click Create Verbal Rule or Create (+).

    For example, click Create Verbal Rule to add a rule named VerbalRule1, as shown in Figure 4-8.

    Figure 4-8 Adding a Verbal Rule to a Rule Set

    Description of Figure 4-8 follows
    Description of "Figure 4-8 Adding a Verbal Rule to a Rule Set"

4.3.3 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 value sets to limit the values for tests and actions in rules. For more information, see Using Value Sets 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, click + from the Rule Sets tab, add or select the rule you want to use, for example, select Rule_1.

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

    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"
  3. In the rule, click <insert test> and choose simple test, for example.

  4. 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-15:

    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.

  5. 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-16.

    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: == (equality), != (not equal), > (greater than), >= (greater than or equal to), < (less than), <= (less than or equal to). For more information on the operators, see Oracle Business Rules Built-in Classes and Functions.

  6. 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 >25 into the text entry area and press Enter or Return, as shown in Figure 4-13.

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

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

4.3.4 How to Define a Test in a Verbal Rule

To create a test in a verbal rule you select a derived or user-defined business phrase, or write a new user-defined business phrase, for which you supply details later.

As you enter text in a verbal rule test, the Rules Editor displays a drop down list of related business phrases.

To define tests in verbal rules:

  1. In Rules Designer, add a new verbal rule, or select the verbal rule you want to use.
  2. The IF area of the rule includes a placeholder <insert test>, as shown in Figure 4-14.

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

    Description of Figure 4-14 follows
    Description of "Figure 4-14 Rule Test with Left-hand-side operand and Right-hand-side operand"
  3. In the rule, click <insert test> and begin to type a test in text entry box that appears.
  4. As you type text (such as 'policy', for example), a list of related business phrases are displayed as shown in Figure 4-15. Select the one you want.

    Figure 4-15 Configuring a Test in a Verbal Rule

    Description of Figure 4-15 follows
    Description of "Figure 4-15 Configuring a Test in a Verbal Rule"
  5. You can refine the list if needed. To display more choices, select a business phrase and press the Tab key. The list is populated with business phrases related to the one you selected, as shown below.

    Figure 4-16 Refining Suggested Business Phrases in a Verbal Rule

    Description of Figure 4-16 follows
    Description of "Figure 4-16 Refining Suggested Business Phrases in a Verbal Rule"
  6. If there are parameters in your business rule, such as '{value}', click on them and specify their details.
  7. If you have written a new business phrase, the rule is put into draft mode. Define the business phrase in the Business Phrases tab. For more information, see How to Create Business Phrases.

4.3.5 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-17 displays a test variable.

Figure 4-17 Rules Test Variable

Description of Figure 4-17 follows
Description of "Figure 4-17 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>.

Note:

Advanced Mode capability has been maintained for backward compatibility only. We recommend that you use extended tests in simple mode to create any kind of condition that you need.

Everything that can be done in Advanced Mode can be done in simple mode. Advanced mode rules can be converted to equivalent simple mode rules simply by clearing the Advanced Mode check box.

For more information, see Working with Extended Tests

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

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

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

    Description of Figure 4-18 follows
    Description of "Figure 4-18 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-19.

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

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

    This adds two more <operand> placeholders.

  8. Configure the <operand> placeholders as you would for any operand.

    For this example, the test is true when the left-most operand (CustomerOrder.annualSpending) is between the values 100 and 2000.

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

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

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

    Description of Figure 4-20 follows
    Description of "Figure 4-20 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-21.

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

    Description of Figure 4-21 follows
    Description of "Figure 4-21 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-22.

    Figure 4-22 In Operator in a Set Test

    Description of Figure 4-22 follows
    Description of "Figure 4-22 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-23.

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

    Description of Figure 4-23 follows
    Description of "Figure 4-23 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.8 How to Define an Action in a General Rule

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 Using Advanced Settings with Rules and Decision Tables.

To define actions in general rules:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.
  2. In a general rule, in the THEN area, select <insert action>. This displays the add action list as shown in Figure 4-27.

    Figure 4-24 Adding a Modify Action to a Rule

    Description of Figure 4-24 follows
    Description of "Figure 4-24 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 also enter the name of the action in the text area. As you begin entering a name, the list of available choices is automatically filters. This is useful when there are a large number of options available.

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

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

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

    Description of Figure 4-25 follows
    Description of "Figure 4-25 Adding Modify Action to a Rule and Selecting the Target"
  5. Select <edit 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-26.

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

    Description of Figure 4-26 follows
    Description of "Figure 4-26 Adding Modify Action Property and Value to a Rule"
  7. In the Properties dialog, click Close. This displays the rule.

4.3.8.1 Basic Actions in a General Rule

Table 4-2 Rule Action Choices

Action Form Description

assert New

Assert a new fact.

assign,

Assert a new fact.

call

Call a function.

modify

Modify a data value associated with a matched fact.

retract

Retract a fact.

assert

Assert a fact.

asset tree

Asserts a tree of facts given the root.

assign new

Assign a new fact.

expression

Perform expression.

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

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.

if, else, elseif, for, while

Conditional actions.

4.3.9 How to Define an Action in a Verbal Rule

Like general rules, to create a verbal rule you insert tests and actions. Verbal rules tests and actions are composed primarily from business phrases.

To define actions in verbal rules:

  1. In Rules Designer, select a ruleset from the Rulesets navigation tab.
  2. In a verbal rule, in the THEN area, select <insert action>. This displays the add business phrase list as shown in Figure 4-27.

    Figure 4-27 Adding an Action to a Verbal Rule

    Description of Figure 4-27 follows
    Description of "Figure 4-27 Adding an Action to a Verbal Rule"
  3. In the business phrases list, start to type the action you want to display a list of suggested business phrases.

    You can also type keywords if you aren't certain of how to phrase your action. For example, if you know you want to calculate a premium in a particular way, you might type 'calculate Premium' to see related business phrases.

    Figure 4-28 Adding an Action to a Verbal Rule

    Description of Figure 4-28 follows
    Description of "Figure 4-28 Adding an Action to a Verbal Rule"
  4. Select a business phrase if one is available that meets your needs.
  5. To refine the list of business phrases further, select one related to what you want to use and press the Tab key.

    The list is displayed with a refined set of business phrases. Select the phrase you want.

    Figure 4-29 Adding an Action to a Verbal Rule

    Description of Figure 4-29 follows
    Description of "Figure 4-29 Adding an Action to a Verbal Rule"
  6. If no business phrases in the list meet your needs, type a business phrase and select Add New Business Phrase to instantiate a new business phrase. Complete the definition of the business phrase in the Business Phrases tab.

4.3.10 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.11 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 Tuning Performance.

4.4 Introduction to Verbal Rules and Business Phrases

Verbal rules work hand in hand with business phrases to provide a flexible way author rules using natural language statements to express rule logic in domain specific sentences that are similar to spoken language.

Business phrases provide the logic behind conditions that are used in the composition of the verbal rule.

You can write verbal rule tests and actions using derived business phrases as well as user-defined business phrases. Derived business phrases are automatically created using facts, globals and other information in the dictionary while user-defined phrases can be explicitly authored to augment derived phrases. Further, user-defined phrases can either be pre-created or created as needed while composing the verbal rule.

As you write a verbal rule, you can use suggested business phrases, or instantiate your own on the fly and provide their implementation details later. Alternatively, you can create the business phrases you need for your verbal rule first, and then complete the verbal rule.

4.4.1 Working with Business Phrases

You create business phrases in the Business Phrases tab of the Rules Designer.

Business phrases comprise three parts:

  • Parameters - parameters defining the types of variables that can be passed to the business phrase

  • Value - the business phrase expression, including placeholders for parameters if any

  • Mapping - definitions of the logic defining the business phrase conditions

There are two types of business phrases:

  • Test business phrases - define conditions. These provide the same types of logic as the IF part of a general rule. For more information, see How to Define a Test in a Rule.

  • Action business phrases - define the actions to perform if the conditions defined by the test business phrases in a verbal rule are met. These provide the same types of logic as the THEN part of a general rule. For more information, see How to Define an Action in a Verbal Rule.

4.4.1.1 Business Phrases Tab

You create both test and action business phrases in the Business Phrases tab of the Rules Designer, as shown in Figure 4-30.

Figure 4-30 Business Phrases Tab

Description of Figure 4-30 follows
Description of "Figure 4-30 Business Phrases Tab"

The tab includes the following sections:

Business Phrases list

The Business Phrases list displays the business phrases included in the dictionary.

Use the toolbar controls to filter the list by searching, to refresh the list, to add new test or action business phrases, and to delete the currently selected business phrase.

The list displays business phrases and their attributes: Value, Form and Draft.

Mark a business phrase as draft by checking the Draft check box directly in the list.

Business phrases containing validation errors are marked with a red squiggly underscore. Hover over them to see the error in a pop-up.

Parameters

Use the Parameters panel to view and edit parameters.

Click Insert to add a parameter to the value of the business phrase. Click Add and Delete to create and remove parameters.

The Form attribute defines the type of parameter. Choices include:

  • Value - ad hoc value. When selected, the Type can be chosen from boolean, byte, char, double, float, int, long, short or String

  • Variable - a variable which is already defined within the scope of the business phrase. When selected, the Type can be chosen from one of the defined fact types in the dictionary.

  • Expression - enter an expression

Value

Edit the definition of the business phrase in the Value panel. The value is also used as the display name of the business phrase in the Business Phrases list, and in business phrases displayed in choice lists when authoring a verbal rule.

Mapping

Edit the logical definition of conditions for the business phrase in the Mapping panel. A business phrase mapping contains similar logical constructs to what you would see if the business phrase logic were authored as a general rule. See the discussions of tests and actions in Working with Rules for principles and procedures which also apply to the creation of business phrase mappings.

4.4.1.2 Draft Business Phrases and Verbal Rules

Business phrases can be marked as being in draft status.

You can set or override the draft status of a business phrase by checking or unchecking Draft in the Business Phrases list.

The draft status of a verbal rule is derived from the business phrases it references and can not be manipulated directly. If a verbal rule contains business phrases marked draft, the rule is also marked draft. The verbal rule description panel is changed to a solid blue color, and the word 'Draft' appears next to the rule name, as shown in Figure 4-31. When all business phrases referenced by the verbal rule are no longer marked draft, the verbal rule is taken out of draft status.

Figure 4-31 Verbal Rule Marked Draft

Description of Figure 4-31 follows
Description of "Figure 4-31 Verbal Rule Marked Draft"

Draft business phrases and verbal rules are not validated and are not included in the dictionary for execution. This allows you to continue to use or test a dictionary as you refine your business phrases and verbal rules.

As you write a verbal rule you can compose business phrases that do not yet exist in the dictionary. These are automatically added to the list of business phrases and marked draft, and the verbal rule is marked draft as well.

4.4.2 How to Create Business Phrases

You create business phrases in the Business Phrases Tab. You can also specify a business phrase while writing a verbal rule and then complete its definition later in the Business Phrases tab.

Use the Business Phrases tab to add, modify, and delete business phrases.

To Create a New Business Phrase

  1. In Rules Designer, select the Business Phrases tab and click Create (+) to create a test business phrase. Select either Test Business Phrase or Action Business Phrase.

    A new business phrase is created.

  2. Enter the definition of the business phrase in the Value panel. Placeholders for parameters that have not yet been defined can be included by typing their name wrapped in curly braces. For example:
    {customer} is single
    
  3. Define parameters in the Parameters panel. Click Create (+) to add a new parameter. Double-click its name to edit it. Specify its Form, and Type. Optionally, specify a Value Set.
  4. To add a parameter to the business phrase value, click Insert.
  5. Define the mapping for the business phrase in the Mapping panel. Begin by clicking <insert test>. Select tests and specify operands. Add additional tests if needed.

4.4.2.1 Example Business Phrase Creation Scenario

For this example, assume you have an Insurance Quote project with most of the project definitions complete. Perhaps you want add a business phrase that tests to see if a customer is a minor, and to invalidate the policy.

You create a new test business phrase and provide the value {customer} is a minor.

Next, you define the parameter customer, and map it to your previously defined Customer fact.

Now you provide the mapping that specifies the condition. You click on <insert test> and select simple test. You click on the left <operand>, expand customer and select customer.age. You click on the right operand and specify the value 21.

The test business phrase looks like Figure 4-32 below.

Figure 4-32 Test Business Phrase Example

Description of Figure 4-32 follows
Description of "Figure 4-32 Test Business Phrase Example"

Now you create an action business phrase to set the deductible to a high value and give it the value Set High Deductible.

You create a variable called policy and map it to your previously defined Policy fact.

You click <insert test> in the Mapping panel and select Expression. You click <expression> and the Expression Editor displays. You navigate to policy.deductible, select it, and click Insert into Expression. You complete the expression with '= 2000' and click OK.

Your action business phrase looks like the Figure 4-33 below.

Figure 4-33 Action Business Phrase Example

Description of Figure 4-33 follows
Description of "Figure 4-33 Action Business Phrase Example"

4.4.2.2 Translating Business Phrases

The Value attribute of Business phrases that have been added to the dictionary can be translated, regardless of whether they originated as derived business phrases or as user-defined business phrases.

In the Business Phrases tab, select the business phrase to translate and click Edit Translation Bundles in the Value panel. Edit translations in the Bundle Editor dialog that appears.

4.4.3 Choosing or Adding Business Phrases in Verbal Rules

Verbal rules use business phrases to specify the IF and THEN tests and actions.

When defining a test or action in a verbal rule, you enter text which triggers a drop-down list of choices. From the list, you can select existing business phrases from the dictionary, automatically generated business phrases, or you can instantiate your a new business phrase based on what you typed, provide its implementation details later in the Business Phrases tab.

4.4.3.1 Instantiating New Business Phrases While Authoring a Verbal Rule

You can instantiate new business phrases while authoring a new verbal rule simply by typing them into a test or action instead of selecting one from the drop down list. These business phrases are marked draft, and the verbal rules which use them are also marked as draft.

In the example below, the desired business phrase Customer is low risk is entered as a test. The business phrase is not shown in the drop down list. It was not automatically generated, and has not previously been defined in the dictionary.

Figure 4-34 Adding a New Business Phrase to a Rule

Description of Figure 4-34 follows
Description of "Figure 4-34 Adding a New Business Phrase to a Rule"

The verbal rule is marked as a draft.

Figure 4-35 New Business Phrase Added and Rule is Marked Draft

Description of Figure 4-35 follows
Description of "Figure 4-35 New Business Phrase Added and Rule is Marked Draft"

The business phrase marked as a draft and is added to the Business Rules list. The parameters (if any) and mapping information must still be specified.

Figure 4-36 Business Phrases Added From Verbal Rule Marked Draft

Description of Figure 4-36 follows
Description of "Figure 4-36 Business Phrases Added From Verbal Rule Marked Draft"

4.4.3.2 Choosing Business Phrases While Creating a Verbal Rule

A robust list including both previously user-defined and auto-generated derived business phrases, sorted by relevancy, is automatically provided as you author a test or action.

User-defined and derived business phrases are not visually distinguished from one another in the drop down list

4.4.3.3 Derived Business Phrases

Derived business phrases are automatically created and are based on business objects and data model as defined in the dictionary based. These are created on the fly and based on what the system calculates you intend to author, based on your typed input. These are not persisted if they are not added to the verbal rule.

Derived business phrases, once added to a verbal rule, are just normal business phrases and support parameters and translation.

4.4.3.4 Choosing Which Business Phrases to See in the List

Use the Settings tab > Dictionary Settings > Phrase Suggestions > Value drop down to control the types of business phrases seen in the drop down pick lists shown while authoring verbal rules' tests and actions.

Choices include:

  • All - display both user-defined business phrases in the dictionary, and derived business phrases

  • Auto Suggestions - display only derived business phrases

  • Business Phrases - display only user-defined business phrases from the dictionary

4.5 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 button 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-37.

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

Description of Figure 4-37 follows
Description of "Figure 4-37 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.5.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.

4.5.2 Understanding Rule Validation

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

Figure 4-38 Business Rules - Log Validation Messages for a New Rule

Description of Figure 4-38 follows
Description of "Figure 4-38 Business Rules - Log Validation Messages for a New Rule"

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 Testing Decision Functions Using a Rules Function.

4.5.3 Understanding Decision Table Validation

When you click the Validate button Rules Designer displays the validation log. When you first add a Decision Table you see validation warnings similar to those shown for a new rule, as in Figure 4-38.

Figure 4-39 Business Rules - Log Validation Messages for a New Decision Table

Description of Figure 4-39 follows
Description of "Figure 4-39 Business Rules - Log Validation Messages for a New Decision Table"

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.

4.5.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 button (a checkmark).
  2. Select the Business Rules - 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.6 Using Advanced Settings with Rules and Decision Tables

Advanced settings for rules and Decision Tables allow you to work with features that provide advanced options that not all Oracle Business Rules users need.

Advanced settings features are shown in Figure 4-40:

Figure 4-40 Show/Hide Advanced Settings

Show/Hide Advanced Settings

These features include:

  • Advanced Mode: allows additional pattern matching options and nested tests in rules. Only use Advanced Mode if you have used it before. We recommend that you use extended tests in simple mode to create any kind of condition that you need.

    For more information, see:

  • Simple Mode: has been updated and should be used when building complex rules. Only use Advanced Mode if you have used it before. Advanced Mode capability has been maintained for backward compatibility only.

    For more information, see Working with Extended Tests.

  • Tree Mode: makes it easier to work with master detail hierarchy, nested elements that map to a parent child relationship. These parent child relationships among facts are common with XML and ADF Business Components fact types. You can use this option with the Advanced Mode option.

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

  • Rule Active: specifies that a rule or Decision Table is active or inactive. When Rule Active is cleared, Rules Designer does not validate the specified rule or Decision Table.

    For more information, see How to Select the Active Option.

  • Logical: allows you to enable or disable logical dependence between the facts that trigger a rule and the facts asserted by a rule.

    For more information, see How to Select the Logical Option.

  • Allow Gaps (available only with Decision Table advanced settings). This check box determines if validation messages are reported when gaps are detected in a Decision Table. The specific validation message is:

    RUL-05852: Decision Table has gaps
    

    For more information, see Understanding Decision Table Gap Checking and How to Perform Decision Table Gap Checking.

  • Priority: specifies the priority for a rule or a Decision Table. Higher priority rules run before lower priority rules, within a ruleset.

    For more information, see How to Set a Priority for a Rule.

  • Conflict Policy: (available only with Decision Table advanced settings). Specifies the Decision Table conflict policy, one of the following:

    • manual conflicts are resolved by manually specifying a conflict resolution for each conflicting rule.

    • auto override conflicts are resolved automatically using an override conflict resolution when this is possible, using the automatic conflict resolution policies.

    • ignore conflicts are ignored.

    For more information, see Understanding Decision Table Conflict Analysis.

  • Effective Date: specifies effective dates for a rule or a Decision Table.

    For more information, see How to Specify Effective Dates.

4.6.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 button 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-41 (there is a highlighted button shown next to the rule name).

      Figure 4-41 Show or Hide Advance Settings

      Description of Figure 4-41 follows
      Description of "Figure 4-41 Show or Hide Advance Settings"
    2. To hide the advanced settings, next to the rule name click Hide Advanced Settings.

4.6.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 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 button next to the rule or Decision Table name (see How to Show and Hide Advanced Settings in a Rule or Decision Table).
  3. Select the Advanced Mode.

Figure 4-42 and Figure 4-43 are examples of a rule displayed in Advanced versus Simple Mode.

The same forms look different in Advanced Mode and Simple Mode due to the presence and absence of "Patterns."

Figure 4-42 Advanced Mode Checked

Description of Figure 4-42 follows
Description of "Figure 4-42 Advanced Mode Checked"

Figure 4-43 shows the same rule with Advanced Mode cleared:

Figure 4-43 Advanced Mode Cleared

Description of Figure 4-43 follows
Description of "Figure 4-43 Advanced Mode Cleared"

4.6.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 cleared, 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 button next to the rule or Decision Table name (see How to Show and Hide Advanced Settings in a Rule or Decision Table).
  3. Select Rule Active.

4.6.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, see Rule Definitions in the Rules Language Reference forOracle Business Process Management.

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 button next to the rule or Decision Table name (see How to Show and Hide Advanced Settings in a Rule or Decision Table).
  3. Select Logical.

4.6.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 button next to the rule or Decision Table name (see 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.

    2. To specify an integer priority, click in the Priority field and enter a positive or negative integer value and press Enter.

4.6.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 button next to the rule or Decision Table name (see 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.

4.7 Working with Nested Tests

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

To use nested tests:

  1. Select the rule where you want to use a nested test.
  2. In the IF area, click and select Nested Test.
  3. With a test selected right-click to display the list, as shown in Figure 4-44.

    Figure 4-44 Adding a Nested Test to a Rule

    Description of Figure 4-44 follows
    Description of "Figure 4-44 Adding a Nested Test to a Rule"
  4. Complete the test as necessary.

4.8 Working with Advanced Mode Rules

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

Note:

Advanced Mode capability has been maintained for backward compatibility only. We recommend that you use extended tests in simple mode to create any kind of condition that you need.

Everything that can be done in Advanced Mode can be done in simple mode. Advanced mode rules can be converted to equivalent simple mode rules simply by clearing the Advanced Mode check box.

For more information, see Working with Extended Tests.

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 What You Need to Know About Advanced Mode Rules.

4.8.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 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 button next to the rule or Decision Table name (see 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-45.

    Figure 4-45 Surrounding with an Option

    Description of Figure 4-45 follows
    Description of "Figure 4-45 Surrounding with an Option"

    Figure 4-46 Surrounding With Option

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

    The Surround With dialog appears.

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

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

    Description of Figure 4-47 follows
    Description of "Figure 4-47 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-48.

    Figure 4-48 Adding an Advanced Pattern Match Option

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

4.8.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-49 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-49 Rule Using a Pattern Binding Variable

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

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

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

Description of Figure 4-50 follows
Description of "Figure 4-50 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 button next to the rule name (see 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-51. For example, enter the matched fact name Order$LineItem1 and then press Enter.

    Figure 4-51 Adding a Matched Fact Variable Name

    Description of Figure 4-51 follows
    Description of "Figure 4-51 Adding a Matched Fact Variable Name"
  6. Create the rule as Figure 4-52 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-52 Choosing a Matched Fact Variable Name as an Operand

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

Note in Figure 4-52 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 How Do I Correctly Express a Self-Join?.

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

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 button next to the rule or Decision Table name (see 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-53.

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

    Description of Figure 4-53 follows
    Description of "Figure 4-53 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.8.3.1 Advanced Mode Action Options in Rule Designer

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.

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

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 button next to the rule or Decision Table name (see How to Show and Hide Advanced Settings in a Rule or Decision Table).
  3. Select Advanced Mode and enter the fact type you want to work with.
  4. Select <insert pattern> to add a pattern and select the pattern.
  5. Right-click the pattern and select Surround With.... This displays the Surround With dialog.
  6. In the Surround With dialog select Pattern Block. Click OK.
  7. In the pattern select the first field. By default this field contains (for each case where), as shown in Figure 4-54.

    Figure 4-54 Adding an Advanced Pattern Match Option

    Description of Figure 4-54 follows
    Description of "Figure 4-54 Adding an Advanced Pattern Match Option"
  8. Select the aggregate option. This adds the context sensitive fields for an aggregate, as shown in Figure 4-55.

    Figure 4-55 Using Aggregate Functions in a Rule

    Description of Figure 4-55 follows
    Description of "Figure 4-55 Using Aggregate Functions in a Rule"
    • Click <function> and select a function from the list.

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

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

    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-56 shows a completed rule using aggregate. In this example, for clarity the rule shows the variable names total_cost and item_x.

    Figure 4-56 Completed Aggregate Function in a Rule

    Description of Figure 4-56 follows
    Description of "Figure 4-56 Completed Aggregate Function in a Rule"
  9. Enter additional tests as required. For this example you enter the test for items with color "red", as Figure 4-57 shows.

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

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

4.8.4.1 Using Aggregate Functions

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

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

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

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

4.8.5.1 How to Clear Advanced Mode Option

  1. Select the rule or Decision Table where you want to clear Advanced Mode.
  2. Click the Show Advanced Settings button next to the rule or Decision Table name (see 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 button changes from gray to enabled). Then simplify the rule and when Advanced Mode is enabled, clear 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.9 Working with Extended Tests

Extended tests should be used when building complex rules. Extended tests, or Simple Mode, replaces Advanced Mode rules.

Note:

Advanced Mode capability has been maintained for backward compatibility only. For more information about Advanced Mode, see Working with Advanced Mode Rules.

Everything that can be done in Advanced Mode can now be done in Simple Mode. The UI has been streamlined and improved to enable you to more easily create complex rules and tests, as shown Figure 4-59.

Figure 4-59 List of Extended Tests

Description of Figure 4-59 follows
Description of "Figure 4-59 List of Extended Tests"

Advanced mode rules can be converted to the equivalent simple mode rules by clearing the Advanced Mode check box.

Extended tests are only applicable to general rules, decision tables, and while defining business phrases. They are not visible in verbal rules.

4.9.1 Extended Test Forms

In addition to the original four tests (shown first in Table 4-8) there are new forms:

Table 4-8 Extended Tests

Forms Description

simple test

This is the building block for conditions. Compares a value against another value, range or set.

For example: Emp.salary > 1000

variable

Initializes variables.

For example: age = Duration.years between(Emp.birthdate,RL.date.get current())

nested test(...)

Encapsulates tests in a containing block.

For example: (age > 50 or Emp.salary > 50000)

negated test(...)

Negates a test.

For example: not(age > 50 and Emp.salary > 50000)

all of the following

all of the following are true.

For example: (age > 50 and Emp.salary > 50000)

any of the following

some of the following are true.For example:

IF
  e is a Emp and  there is no Emp where     Emp.salary < e.salary     <insert test>  <insert test>THEN  assign e.isLowestPaid = true

is a

Defines a fact.

For example: e is a Emp

boolean expression

Captures a boolean expression.

For example: isEligible(Emp)

there is a case where

This test has 1 or more child tests that are ANDed.

The child tests are all true for at least 1 case. A case is a binding of facts to contained is a tests.

Must have is a descendant.

Example:

There is a case where

e is a Emp and

d is a Dept and

e.salary > 1000000 and

d.name == "Marketing" and

d.employees contains e

there is a <factType1>,...<factTypeN> where#*

This test has N or more child tests that are ANDed

Hidden <factType> is a <factType> tests as first N children.

The child tests are all true for at least 1 case.

It is legal to have no visible child tests, in which case the where keyword should be suppressed.

Example:

IF
  there is a Emp, Dept where
  Emp.salary > 1000000 and
  Dept.name == "Marketing" and
  Dept.employees contains Emp
THEN
  call print "there is a highly paid marketer!"
IF
there is a Emp
THEN  call print "somebody works here!"

there is no case where

This test has 1 or more child tests that are ANDed.

The child tests are true for no case (no binding of facts to contained is a tests satisfy all the other tests).

Must have is a descendant.

there is no <factType1>,...,<factTypeN> where

Hidden <factType> is a <factType> as first N children

The child tests are true for no case

aggregation

This test has 0 or more child tests that are ANDed.

Must have is a child (may be hidden).

v is the sum|average|minimum|maximum|count|collection of<expression> where

Where clause omitted when there are no visible child tests.

IF
  number of employees is the count of Emp
THEN
  call print "number of employees: " + number of employees
 
IF
  number of male employees is the count of Emp where
    Emp.gender == "M"
THEN
  call print "number of male employees: " + number of male employees

Note that in both rules above, the SDK will create a hidden nested is a test for Emp.

You can also use an explicit is a

IF
  number of male employees is the count of e where
    e is Emp and
    e.gender == "M"
THEN
  call print "number of male employees: " + number of male employees

Figure 4-60 is an example where "there is a case where" form is used:

Figure 4-60 Extended Test Example 1

Description of Figure 4-60 follows
Description of "Figure 4-60 Extended Test Example 1"

Figure 4-61 is an example where "there is no case where" form is used:

Figure 4-61 Extended Test Example 2

Description of Figure 4-61 follows
Description of "Figure 4-61 Extended Test Example 2"

For information about how to build complex rules, see Working with Rules.

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

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-62 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-62 PO Schema for Tree Mode Rules Sample

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

The following example of sample Purchase Order (PO) schema shows the sample purchase order XML schema as represented in Figure 4-62.

<?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>

4.10.1 Sample Abbreviated PO XML Instance

Example 4-1 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-1 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.10.2 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.

When you create rules with Tree Mode selected and Advanced Mode cleared, 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 How to Create Simple Tree Mode Rules.

4.10.3 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-63. Rules Designer shows patterns for the tree structured facts but the simple tests that join the parent and child facts are hidden.

Figure 4-63 Advanced Tree Mode

Description of Figure 4-63 follows
Description of "Figure 4-63 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 pattern. 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 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.10.4 How to Create Simple Tree Mode Rules

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 and view the advanced settings.

    For more information on adding general rules, see How to Add General Rules.

    For more information on advanced settings, see How to Show and Hide Advanced Settings in a Rule or Decision Table.

  2. Select Tree Mode. Next to ROOT:, click the <fact type> placeholder and select from the list.

    Figure 4-64 Simple Tree Mode: Configuring the Root

    Description of Figure 4-64 follows
    Description of "Figure 4-64 Simple Tree Mode: Configuring the Root"
    • Select <insert test> and select from the list.

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

    • Select the left-hand <operand> and select an option from the list.

  3. Select the Expression Builder button, as shown in Figure 4-65.

    Figure 4-65 Adding a Simple Tree Mode Expression

    Description of Figure 4-65 follows
    Description of "Figure 4-65 Adding a Simple Tree Mode Expression"
    • In the Expression Builder dialog, copy and delete the item shown in the Expression area.

    • In the Expression Builder, select the Functions tab.

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

    • Remove the daysbetween argument templates.

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

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

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

    • In the Expression Builder dialog, click OK.

      For more information, see Introduction to Expression Builder.

  4. In the list, in the expression area and press Enter. Select the operator and enter >.
  5. Select the right-hand <operand> and enter the value 30 and press Enter, as shown in Figure 4-66.

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

    Description of Figure 4-66 follows
    Description of "Figure 4-66 Simple Tree Mode: Right-Hand Operand with Value 30"
    • Click <insert action> and from the list select modify.

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

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

      THEN modify PO/destination/item ( <add property> )
      
    • Click <add property>. This displays the properties dialog.

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

      Figure 4-67 Simple Tree Mode: Action

      Description of Figure 4-67 follows
      Description of "Figure 4-67 Simple Tree Mode: Action"
  6. In the Properties dialog, click Close.

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

    Figure 4-68 Simple Tree Mode Rule Final Rule

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

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

4.10.5 How to Create Advanced Tree Mode Rules

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 How to Add General Rules.

  2. View advanced settings.
  3. Select Advanced Mode and select Tree Mode as Figure 4-69 shows.

    Figure 4-69 Advanced Tree Mode Rule for Free Shipping

    Description of Figure 4-69 follows
    Description of "Figure 4-69 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-70.

Figure 4-70 Advanced Tree Mode Free Shipping Rule

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

4.10.6 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.11 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-9 describes the available Effective Date options.

Table 4-9 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.11.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-71.

    Figure 4-71 Rule with Condition Using CurrentDate Fact

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

4.11.2 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 Built-in Functions in the Rules Language Reference for Oracle Business Process Managementguide.

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 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 cleared, 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 check box, the To check box, or both check boxes 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 cleared, 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.11.3 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 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 Introduction to 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-72.
  10. Click OK to review your rule.

Figure 4-72 Using Duration Methods in a Rule

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

4.12 Introduction to 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 select

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

Figure 4-73 shows the Rules Designer expression builder.

Figure 4-73 Rules Designer Expression Builder

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

4.12.1 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.12.2 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.

Expressions allow casting between any two numeric types, for example, (short)((BigInteger)1 + (Long)2). The following code example shows a few additional 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 

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.

4.13 Using Value Sets as Constraints for Options Values in Rules

You can use List of Values value set and List of Ranges value sets to specify constraints for business terms in rules. This enables 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 value set.

Oracle Business Rules also lets you use value sets to specify constraints for global initial values, function return values, or function argument values. For more information, see Working with Oracle Business Rules Globals and Associating a Value Set with Business Terms.

4.13.1 How to Use a List of Ranges Value Set as a Constraint for a Business Term

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

For more information on using a list of values value set as a constraint, see How to Use a List of Values Value Set as a Constraint for a Fact Property.

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

  1. In the Value Sets tab, double-click a value set to open the Edit Value Set dialog.
  2. Specify a value set that includes the ranges you want to include and select Allowed in Actions for all valid ranges. To include a range, clear Allowed in Actions for the top and bottom endpoints.
  3. Select Included Endpoint as needed for the application.
  4. Clear Include Disallowed Values in Tests. For example, for a value set that defines valid grades and that does not allow values greater than 100, or less than 0, define the value set endpoints.

    Figure 4-74 Valid Value Sets for a Fact Property

    Description of Figure 4-74 follows
    Description of "Figure 4-74 Valid Value Sets for a Fact Property"
  5. Associate this value set with a business term. For this example, associate the value set with test_math1.

Now, if you define a rule with a test that uses the fact property you will 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 will show a validation warning.

4.13.2 How to Use a List of Values Value Set as a Constraint for a Fact Property

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

For more information on using a list of ranges value set as a constraint, see How to Use a List of Ranges Value Set as a Constraint for a Business Term.

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

  1. Specify an LOV value set that includes the values you want to include, and select Allowed in Actions for all valid values. For more information, see How to Define a List of Values Global Value Set.
  2. Clear Allowed in Actions for the otherwise value set.
  3. Clear Include Disallowed Values in Tests.
  4. Associate this value set with a fact property.

4.13.3 How to Use Value Sets to Provide Options for Test Expressions

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

To use value sets to provide options for rule expressions and actions:

  1. In Rules Designer, define an LOV value set of a type corresponding to a fact property. For more information, see How to Define a List of Values Global Value Set.
  2. Associate the value set with a fact property. For more information, see How to Associate a Value Set with a Fact Property.
  3. When you enter expressions, Rules Designer shows the values in the values options. For example, when you associate a fact property Driver.eye_test with an LOV value set named eyes, with values: pass, fail, and glasses_required, and then you use Driver.eye_test in a test expression, the values are limited.

4.14 Importing Runtime Rules Changes From Repository Into JDeveloper

Import changes to a rule implemented in SOA Composer into the JDeveloper.

When you make changes to a dictionary in SOA Composer, you must upload them to MDS repository as described in Publishing Changes for an Oracle Business Rules Dictionary. However, these changes do not get updated in JDeveloper. You need to import the changes from MDS repository into JDeveloper manually.

To import the changes into the JDeveloper,

  1. Select the rule in the application navigator for which changes were made.
  2. Click the Import From MDS button in Rule Editor as shown in Figure 4-75.

    Figure 4-75 Importing Changes from the MDS Repository

    Description of Figure 4-75 follows
    Description of "Figure 4-75 Importing Changes from the MDS Repository"
  3. Select the MDS Repository from the Import Dictionary dialog.
  4. Click OK.

    Changes are updated in JDeveloper and you can view the changes in the Rule Editor.

4.15 How to Model Rules When the Data Model is Deep

Use the following tips to avoid overly complex rules:

  • Use rule test variables (inline aliases) to create a simple test.

  • Any 1:1 prefix can be removed from the fact path.

Rule test variables:

Use rule test variables (inline aliases) to create a simple test that can help you model rules when there is a deep data model.

For example, a rule like this:

IF
task/payload/purchaseOrder/line.amount > 100
THEN
modify ...

Can be rewritten like this:

Root: task 
IF 
amount = task/payload/purchaseOrder/line.amount and 
amount > 100.0 
THEN
modify ... 

(OR)

Root: task 
IF 
line = task/payload/purchaseOrder/line and line.amount > 100.0 and line.amount < 1000.0 
THEN 
modify ...

Remove 1:1 prefixes:

Note that any 1:1 prefix can be removed from the fact path (if not referenced in tests). For example, if you know that a task has at most 1 payload and a payload has at most one purchase order, and tests do not reference the task or the payload attributes, then you can use the shorter example as follows:

Root: PurchaseOrder 
IF 
line = PurchaseOrder/line and 
line.amount > 100.0 and line.amount < 1000.0 
THEN 
...

You can also use the shorter path if the relationships are 1:many and you do not care about what task or payload contains which purchase order. You just want to process all the purchase orders.