Numeric Rules

This chapter covers the following topics:

Introduction to Numeric Rules

Numeric Rules express constraints between parts of a Model in terms of numeric relationships. Use Numeric Rules to enable end-user selections to contribute to or consume from a Total, Resource, Numeric Feature, Option quantity, or the minimum or maximum number of component instances that are allowed in a runtime Oracle Configurator.

You can create more complex numeric relationships and constraints by defining a Statement Rule. For details, see Overview of Statement Rules.

To create a simple Numeric Rule, see Defining Numeric Rules.

Note: Do not create a Numeric Rule that updates the quantity of the root BOM Model node at runtime. The runtime Oracle Configurator does not support this method of updating the Model quantity (that is, the quantity of the item being configured). The only supported way to update the Model quantity is from the host application. For example, you can change the quantity in the Oracle Order Management Sales Orders window.

Contributes to Numeric Rules

A Contributes to Numeric Rule specifies addition of a numeric value to a Total, Resource, Numeric Feature, Option quantity, or the minimum or maximum number of component instances that are allowed at runtime. Calculation of the numeric value can involve Constants, Boolean values, Numeric Features, Option quantities, System Properties, Totals, the minimum and maximum number of instances, and the instance count.

For example:

Word Processing, Graphics, Spreadsheet * 60 Contributes to Total ’Disk Space’

This rule states that when Word Processing, Graphics, or Spreadsheet is included in the configuration, a value of 60 is added to a Total called Disk Space.

Consumes from Numeric Rules

A Consumes from Numeric Rule specifies subtraction of a numeric value from a Total, Resource, Numeric Feature, Option quantity, or the minimum or maximum number of component instances that are allowed at runtime. Calculation of the numeric value can involve Constants, Boolean values, Numeric Features, Option quantities, Properties, Totals, the Minimum and Maximum number of instances, and the instance count.

For example:

Disk Drive * 10 Consumes from Resource ’Bay Slots Available’

This rule states that when the option called Disk Drive is included in the configuration, a value of 10 is subtracted from the Resource called Bay Slots Available.

Using the Model Quantity in Numeric Rules

To enable the Model’s quantity to affect the quantity of other items in a configuration, you must define a Numeric Rule that uses the root Model node’s Quantity System Property. You must do this, for example, if you want the Model’s quantity to be considered during Quantity Cascade calculations for BOM Model items. See Quantity Cascade Calculations.

Typically, a user specifies the Model quantity in a host application, such as Oracle Order Management, before launching Oracle Configurator. To unit test this type of rule, launch the Model Debugger and enter a Model Quantity in the Session Parameters page. See Unit Testing Using the Model Debugger.

For example, when an end user orders three computers, you want to ensure that the same number of keyboards are included in the order. To do this, create a Numeric Rule that contributes the Model quantity to the quantity of the Keyboard item.

For example:

Sentinal System Model.Quantity * 1 Contributes to Keyboard.Quantity

The rule must also include the Quantity System Property if your Model contains guided buying or selling nodes and you want to trigger a BOM Quantity Cascade calculation when the non-BOM node is selected. For example:

For example:

Option A * 4 * Sentinal System Model.Quantity Contributes to BOM Item S1.Quantity

In this case, a value of 4 times the Model quantity is contributed to the imported item S1 when the end user selects Option A. So, if the end user selects Option A and the Model Quantity is 2, the quantity of S1 is 8.

For more information, see Using Properties when Defining a Numeric Rule.

Contributing to BOM Item Quantities

A common use of Numeric Rules is to contribute to a BOM item’s quantity when an Oracle Configurator end user selects another option, such as a guided buying or selling node. For example, when an end user selects the Custom Laptop BOM item and the "Frequent Traveller" option, an extra rechargeable battery is added to the configuration (in other words, the quantity of the Battery BOM item is set to 2).

To create this type of rule, select a BOM item as a participant on the Second Operand side of the Numeric Rule, and specify the node’s Quantity System Property.

For example:

Frequent Traveller Option * 2 Contributes to Battery.Quantity

All such rules contribute to the BOM item’s total cascaded quantity but not to the unit, or per-parent, quantity. (See Quantity Cascade Calculations.) If you have an expression for a contribution to the unit quantity, you must multiply that expression by the parent quantity to get the expected result.

For example, suppose that the Custom Laptop is a component of the Computer System Model. Consider a configuration in which the end user specifies a quantity of 3 for the Custom Laptop and also selects the Frequent Traveller Option. The configuration requires a total cascaded Battery quantity of 6, but the above rule would only contribute 2. To correct this, multiply the First Operand side of the rule by the Custom Laptop quantity. The new rule is expressed as a Statement Rule:

CONTRIBUTE (Custom Laptop.Quantity() * Frequent Traveller Option * 2) TO Battery.Quantity()

Because contributions to BOM items are made to the final quantity, it is possible that the contribution will not be divisible by the parent's quantity. In this case, Oracle Configurator finds the closest multiple of the parent's quantity that is less than the contribution. For example, if the parent's quantity is 4 and the contribution toward the child's quantity is 11, the final child's quantity will be 8.

Also, a BOM item's quantity can never be less than its parent BOM item's quantity. Therefore, if the contribution is less than the parent's quantity, then the child's final quantity becomes equal to or greater than the parent's quantity. The exact value depends on the item’s default quantity. See Default BOM Item Quantity.

Default BOM Item Quantity

The default BOM item quantity is defined as the minimum BOM component quantity in Oracle Bills of Material. The default quantity is the default quantity of the BOM item when an end user selects it in a runtime Oracle Configurator. Typically, the default quantity for BOM items is 1.

The default BOM quantity is a unit quantity. For example, the default quantity of Standard Item X is 2. An end user sets the quantity of X’s parent to 2, and then selects ABC. This results in a quantity of 4 for Item X.

Contributing to a BOM Item when its default quantity is greater than 1 results in different final quantity depending on the contribution. If the contribution is less than the parent's quantity multiplied by the default BOM quantity, the child's quantity becomes the multiple of the parent's quantity and the child's default quantity.

For example, if a parent's quantity is 4 and the child's default quantity is 1 (which is the same as not specifying a quantity), a contribution of 3 to the child's quantity results in a final quantity of 4 for the child (parent's quantity 4 * child's default quantity 1). However, if in the same example the child's default quantity is 2, a contribution of 3 results in a final quantity of 8 for the child (parent's quantity 4 * child's default quantity 2).

Using Numeric Features in Numeric Rules

Although it is not common practice, it is possible to define a Numeric Rule in which a Numeric Feature contributes to or consumes from another Numeric Feature. In other words, the participants on both sides of the rule are Numeric Features. If you define rules such as this, it is important to understand that the runtime behavior may produce unpredictable results. This is because:

Consider the following rule in which both participants are Numeric Features:

Feature A * (Constant 1) Contributes to Feature B

At runtime, an end user enters 10 for Feature A, which sets Feature B to 10. Later in the configuration, the end user changes Feature B by entering a value of 20 (this has no effect on Feature A). Then the end user changes the value of Feature A to 30. When this happens, Oracle Configurator sets Feature B to 40.

In the example above, Oracle Configurator initially sets Feature B to 0 (zero). However, when an end user manually enters a value for the Feature on the right side of the rule, the system also maintains an internal value for the Feature. This internal value is not visible to the end user and is determined by subtracting the Feature’s old value from the new value (that is, new value - old value). Therefore, when the end user changes the value of Feature B from 10 to 20, this Feature’s internal value is set to 10. Then, when the end user changes Feature A to 30, Oracle Configurator contributes 30 to Feature B’s internal value (10) and displays 40 to the end user.

It is generally better practice to use a Total or a Resource on the right side of Numeric Rules, since end users may find the behavior described in the example to be confusing. Totals and Resources are read-only at runtime, so an end user cannot enter a value for the node that (in this example) appears on the right side of the rule.

The behavior described in the example occurs whether the rule uses the Consumes from or the Contributes to relation.

Using Properties when Defining a Numeric Rule

You can use both System and User Properties when defining Numeric Rules. For an overview of User and System Properties, see Introduction to Properties . For more information about using System Properties when defining rules, see Introduction to Rules, Node Types, and System Properties .

When specifying System Properties on the Second Operand side of the rule, only Properties that can logically be contributed to or consumed from are available. For example, when you add a BOM Option Class node to the right side of the rule, you can select the Quantity System Property, but not State, MinQuantity, or MaxQuantity.

Contributing to the Count of an Option

Each time an Option from Feature X is added to the configuration, you need to ensure that the quantity of Option Y increases by 1. To create this Numeric Rule:

  1. Add Feature X to the First Operand side of the rule, and enter 1 as the Quantity Multiplier.

  2. Add Option Y to the Second Operand, and click Choose Nodes.

  3. In the Choose Nodes page, click Choose Properties. Select the Quantity System Property from the list, and then save the rule.

The rule now has the following definition:

Options{Feature X} * Constant 1, Contributes to Option Y.Quantity

Note that in this example, the Enable Option Quantities setting must be selected for the Feature to which Option Y belongs; otherwise, Option Y is simply set to True when an Option from Feature X is selected, since it has no numeric value.

Contributing to the Maximum Number of Component Instances

When the end user orders a specific quantity of Integer Feature A, you want to increase how many instances of Model Z (a referenced Model) are allowed in the configuration. In Configurator Developer, the Instantiability setting for the Model Z Reference node is set to Multiple or Variable Instances, and the Initial Maximum is set to 3. You define a Numeric Rule in which Feature A contributes to the Model Z Reference node, and specify the Reference node’s MaxInstances System Property.

The Numeric Rule in this example has the following definition:

Total or Numeric Feature{Feature A} * Constant 1, 
Contributes to Model Z.MaxInstances

At runtime, the end user specifies a quantity of 6 for Feature A. When this occurs, the maximum number of instances of Model Z allowed in the configuration dynamically changes to 9 (that is, a value of 6 is contributed to the Initial Maximum setting, which was 3).

To consume from the minimum number of instances allowed at runtime, use the System Property MinInstances.

Note: A rule such as the one described in Contributing to the Maximum Number of Component Instances affects only the minimum and maximum number of instances allowed in a runtime Oracle Configurator. This type of rule cannot actually add instances to the configuration and does not modify the node’s instantiability settings in Oracle Configurator Developer.

Negative Contributions

A negative contribution occurs when the right side of a Numeric Rule is either an Option quantity or a Count Feature, and:

If the sum of contributions is a negative value, Oracle Configurator ignores it. If the sum of contributions is positive, the result is contributed in the ordinary way. For example, if you have a Counted Option with three rules contributing 5, 4, and -3, the value contributed is 6.

Contributions to a BOM Model are handled similarly. For example, you have a BOM Model with a Quantity count of 3, a BOM Option Class with a Quantity count of 2, and three rules contributing 5, 4, and -3, to the BOM Option Class’s Quantity count. The contribution is calculated as:

  5  +  4  +   (-3)  =   6
(rule1)(rule2) (rule3)  (contributions)

The final count of the BOM Option Class is calculated as:

Floor(   6    /   3   )*   3   =        6   
     (contributions)   (parent count)  (parent count)

The sum of contributions (6) is exactly divisible by the parent count (3), so the final result is 6.

If the sum of contributions is not exactly divisible by the parent count, the result is the closest smaller exact multiple of the parent count. For example, if the contributions are 5, 4, and -4, the result is 3.

If the sum of contributions is smaller than the parent count, then the result becomes the default count. For example if the rule contributions are 5, 4, and -7, the result is 6 (which comes from 2 * 3).