1. Oracle Visual Builder Studio Page Model Reference
  2. Understand the Page Model
  3. Constants
  4. Use Rules to Derive the Value for Interface Constants

Use Rules to Derive the Value for Interface Constants

For interface constants defined on a flow, page, or fragment in an extension, you can use rules to define the constant's default value. This is similar to how business rules are used in Layouts.

To illustrate how this feature can be helpful, let's look at a real-world example. Let's say a page author is designing a shopping cart, and wishes to calculate the sales tax for an item added to a cart. To store the sales tax, the author defines a constant salesTax.

Determining the sales tax is a complex calculation that depends on several variables, for example, the country, city, or state where the item is bought, and the tax rates applied to different types of goods. This makes calculating the correct sales tax something that can be challenging to express using a simple expression. A page author could use an action chain that reacts to the 'valueChanged' property for the variables to perform the calculations, but action chains like this can be time consuming to configure. Action chains are also not extendable, making it difficult to delegate their evaluation to a downstream customer extension.

This is where having a separate rules engine provides a simple and convenient way to define rules that:

  • Determine the value for one or more constants, and
  • Establish a predictable lifecycle where the rules are run as needed, in response to state changes.

The rules are run in order of priority, such that values from higher priority rules take precedence over lower priority rules. First, each rule condition is tested to see whether it will provide a value for one or more constants during the current run. The participating rules (the rules whose conditions evaluated to true) are then executed, and the values for the interface constants that are provided by rules are gathered. If multiple rules provide values for the same constant, then the value from a higher priority rule is selected over a lower priority one. Rules defined in a customer extension have higher priority over the rules defined in the base (or factory) extension. Within the same rules model, the rules are listed from highest to lowest priority.

Using rules model to define values for constants

A page author may choose to use rules to determine the values for all the interface constants defined in the base. To do this, the author should:

  • Define a top-level property options on the page model with the sub-property constantsRules with the value set to on. This informs the framework that rules are enabled for the current container's interface constants, as long as the container allows rules. For example, layout containers do not support constants rules.

  • Define a -rules.json file (described below).

  • Remove the defaultValue property set on all interface constants, and instead configure rules that return the same value.

    Note:

    An error will be reported if a defaultValue property is configured and rules are turned "on". The constant can have other properties configured as shown below.

For example, the interface constants in a base extension's page.json with rules might look like this: 

{
  "pageModelVersion": "2504.0.0",
  "title": "allRules-page",

  "options": {
    "constantsRules": "on"
  },
  "interface": {
    "constants": {
      "baseStateTax": {
        "type": "number"
      },
      "salesTax": {
        "type": "number"
      },
      "CATax": {
        "type": "number"
      }
    }
  }
}

A customer extending the base page above can do the following if they want to define rules for the constants in their extension:

  • Define a top-level property options on the page model with the sub-property constantsRules with the value set to on. This informs the framework that rules are enabled for the current container's interface constants, as long as the container allows rules. For example, layout extensions do not support constants rules but page-x and fragment-x do.

  • Define a -rules-x.json file (described below).

  • Remove all constant definitions in the sub-property constants under extensions of the page-x model, and instead define default value rules for the extended constants. For example, page-x.json in a customer's extension might look like the example below, where no 'extensions constants' are defined.

    Note:

    The empty object in this example is shown for clarity, and is not required. 
{
  "pageExtensionModelVersion": "2501.10.0",
  "description": "Extension page",

  "options": {
    "constantsRules": "on"
  },

  "extensions": {
    "constants": {}
  }
}

Note:

Each extension can choose to configure rules or keep the current defaultValue configuration.

Defining and Running Rules

An example of cart-page.json used in a shopping cart page is defined below. In this example there are three interface constants: baseStateTax, salesTax, and CATax. 

{
  "options": {
    "constantsRules": "on"
  },

  "interface": {
    "constants": {
      "baseStateTax": {
        "type": "number"
      },
      "salesTax": {
        "type": "number"
      },
      "CATax": {
        "type": "number"
      }
    }
  },
  "variables": {
    "address": {
      "type": {
        "addressLine": "string",
        "city": "string",
        "county": "string",
        "state": "string",
        "zip": "number"
      }
    },
    "city": {
      "type": "string",
      "defaultValue": "{{ $variables.address.city }}"
    },
    "county": {
      "type": "string",
      "defaultValue": "{{ $variables.address.county }}"
    },
    "state": {
      "type": "string",
      "defaultValue": "{{ $variables.address.state }}"
    },
    "purchaseDate": {
      "type": "string",
      "description": "the date when items are bought"
    }
  }
}

Their values are provided by cart-page-rules.json, which is shown below. The suffix '-rules', identifies it as a rules artifact associated with the cart-page.

Note:

For the most part, the structure of the rule definition below mirrors that for layout business rules. 
{
  "rules": [
    {
      "id": "salesTaxRuleWithDate",
      "description": "calculates state tax if purchase date falls earlier than 2020",
      "condition": {
        "expression": "{{ $modules.utils.checkYear($variables.purchaseDate) < 2020 }}",

        "referencedContext": {
          "generated": [
            "$variables.purchaseDate"
          ],
          "extra": []
        }
      },

      "overlay": {
        "$constants.salesTax": "{{ $modules.utils.getSalesTaxForPrior($variables.state, $variables.county, $variables.city) }}"
      }
    },
    {
      "id": "salesTaxRule",
      "description": "calculates state tax for when state or county or city properties change",
      "condition": {
        "expression": "{{ $variables.state || $variables.county || $variables.city  }}",
        "referencedContext": {
          "generated": [
            "$variables.state",
            "$variables.county",
            "$variables.city"
          ],
          "extra": []
        }
      },

      "overlay": {
        "$constants.baseStateTax": "{{ $modules.utils.getBaseTaxForState($variables.state) }}",
        "$constants.salesTax": "{{ $modules.utils.getSalesTax($variables.state, $variables.county, $variables.city) }}"
      }
    },
    {
      "id": "taxDefaultsRule",
      "description": "provides base values",

      "condition": {
        "referencedContext": {
          "generated": [
            "$constants.CATax"
          ]
        }
      },
      "overlay": {
        "$constants.baseStateTax": "{{ $constants.CATax }}",
        "$constants.salesTax": "{{ $constants.CATax }}"
      }
    },
    {
      "id": "CATax-defaultValueRule",
      "description": "default value expression in rules for CATax",

      "overlay": {
        "$constants.CATax": 6.25
      }
    }

  ]
}

Rules property

Multiple rules are defined and listed in order of priority, from highest to lowest, under the rules property, and the rules are executed from lowest priority to highest priority. Each rule is identified by an "id" (for example, salesTaxRuleWithDate, salesTaxRule). Each rule is run until values for all constants have been determined. A single rule has the following properties:

  • id: a string identifier
  • description: a string description
  • condition: an object containing two properties:

    • expression: optional boolean, whether the rule can be executed or not. The conditional expression can call a module function, but it cannot return a Promise.

    • referencedContext: array of variables and constants that cause a rule to be part of a rules engine execution when their values change. This array, when set, can be a fast way to include a rule for the current run.

      • generated is generally set by the design time.
      • extra is provided by the rules author.
  • overlay: an object containing the interface constants (static values or expressions) as its properties. In the example above, some rules provide values for $constants.salesTax, whereas others for $constants.CATax. When multiple values for the same constant are provided, then the value from the higher priority rule is used. The source expressions (the rhs expressions) used in the overlay can call a module function, but it cannot return a Promise, or be async methods. For example, make a Rest fetch.

    Note:

    If an "overlay" has multiple constants mapping, where the value of one constant depends on the other, it is recommended that separate rules be defined as the order that constants would be evaluated within a single overlay cannot be guaranteed.

The following table describes the rules in the example above.

Rule Description
CATax-defaultValueRule

This rule provides a default value for the CATax constant. This rule has no conditions set, so it is always run.

taxDefaultsRule

This rule provides values for the constants baseStateTax and salesTax, using the current value for CATax. It has a "referencedContext" property set, that depends on another constant CATax. This means that any time the value of the interface constant changes, this rule is likely to run.

The value for CATax happens to be provided by a lower priority rule (CATax-defaultValueRule) in the current run. In such cases, the value determined by this rule for the CATax constant is used by taxDefaultsRule, in determining the values for baseStateTax and salesTax.

salesTaxRule

This rule is slightly more complex where the "condition" is tested (for boolean true), before the values for salesTax and baseStateTax constants are returned via "overlay".

Let's say that during init the "address" variableis empty. When this is the case then the condition evaluates to false, and the rule is skipped. When the "address" variable updates, causing city or state or county to be updated, then this rule is executed because one of its listed referencedContext variables has changed, meaning the condition now evaluates to true.

Because tax calculations are complex, module methods getBaseTaxForState() and getSalesTax() are used. They use the state, county, and city information to determine the right tax values.

salesTaxRuleWithDate

This rule uses the purchase date in addition to the address to determine the tax values. It defines a "condition" that uses a module function method to validate the purchase date. If the provided date is earlier than 2020, the rule is run to determine the salesTax constant, and returned via "overlay".

Rules execution behavior

Generally, rules are executed during initialization at the beginning of the lifecycle, and every time the 'rules context' changes. Supported containers are flow, page, and fragment.

During init, the sub-property expression under condition alone is checked before a rule is selected for execution. condition can also be a plain string expression or boolean.

After the initial values are determined, any time a referenced variable or constant that is listed in the referencedContext sub-property of condition changes, then the rules engine is re-executed, and the new list of participating rules determined, by running each rule in order of priority.

At the end of a run, the final values of (interface) constants are updated on the associated scope.

Note:

During execution, both the referencedContext and condition expression are checked to see whether the rule participates. For instance, if the valueChange is for a variable that is not present in the referencedContext the rule is skipped. Otherwise, the condition is checked before a rule is considered for the run. As stated before, when multiple participating rules provide values for the same constant(s), then the value evaluated by the rule with higher priority is used over the value provided by a lower priority rules.

What context is available within rules?

VB business rules can use all context properties that are generally available to a container. For example, $variables, $constants, $modules from the current scope, or properties from an outer scope such as $flow, and $application can be used.

Note:

This is done for backwards compatibility with existing customer extensions pages that may have defaultValue expressions already defined that refer to any available scope properties. If the customer chooses to combine the defaultValue expressions from all interface constants into rules, they must be able to do so without having to redefine new expressions.

In addition, rules associated with a customer's extension page can access the interface constants or variables from its base (via $base.constants, $base.variables).

Each rules engine run is synchronous, so at the beginning of the run, a snapshot of the current context is used when evaluating expressions in rules.

Evaluating Rules at Init time

Generally, values returned by the rules, defined both in factory and customer extensions, are taken as the initial values for the constants.

When a customer extension has a defaultValue property set on its extended constants (meaning, there are no rules defined), then these values win over any rule values from the base because customer overrides in an extension always have priority over the base. This ensures current pages are backwards compatible.

Evaluating Rules after ValueChange

Post-init, the rules engine executes every time the value for any of the referencedContext variables or constants changes. In the example below, ExtA defines the interface constants mode, greeting, name, and anonUser, whose values are provided by rules. $variables user, along with other scope properties for the current page, are also accessible from rules.

ExtA: page.json ExtA: page-rules.json 
{
  "options": {
    "constantsRules": "on"
  },

  "interface": {
    "constants": {
      mode: { 
        type: "string" 
      }, 
      salutation: { 
        type: "string"
      },
      anonUser: {
        type: "string"
      },
      "greeting": {
        "type": "string"
      }
    },
    "variables": {
      "user": {
        "type": "userType",
        "defaultValue": "{{ $application.variables.user }}",
        "mode": "readOnly"
      }
    }
  },
  "types": {
    "userType": {
      "name": "string",
      "title": "string",
      "role": "string"
    }
  }
}
 
{
  "rules": [
    {
      "id": "extA/anonRule",
      "condition": {
        "expression": "{{ $variables.user.name === '' || $variables.user.name === undefined }}",
        "referencedContext": {
          "generated": [
            "$variables.user"
          ]
        }
      },
      "overlay": {
        "$constants.mode": "oracle-public",
        "$constants.greeting": "{{ $constants.salutation + ' ' + $constants.anonUser + '!' }} "
      }
    },

    {
      "id": "extA/nonAdminRule",
      "condition": {
        "expression": "{{ $variables.user.name && $variables.user.role !== 'admin' }}",
        "referencedContext": {
          "generated": [
            "$variables.user"
          ]
        }
      },
      "overlay": {
        "$constants.mode": "oracle-internal",
        "$constants.greeting": "{{ $constants.salutation + ' ' + $functions.toTitleCase($variables.user.name) + '!' }} "
      }
    },

    {
      "id": "extA/adminRule",
      "condition": {
        "expression": "{{ $variables.user.name && $variables.user.role == 'admin' }}",
        "referencedContext": {
          "generated": [
            "$variables.user"
          ]
        }
      },
      "overlay": {
        "$constants.mode": "oracle-restricted",
        "$constants.greeting": "{{ $constants.salutation + ' ' + $functions.toTitleCase($variables.user.name) + '!' }} "
      }
    },

    {
      "id": "extA/defaultValuesRule",
      "overlay": {
        "$constants.anonUser": "Jane Doe",
        "$constants.salutation": "Hello"
      }
    }
  ]
}

Extending Rules in Extensions

An extension page can already extend (interface) constants from its base extension. Now, an extension container (page-x) can additionally define its own rules that provide values for the extended constants. Factory rules cannot themselves be extended by a customer extension. Instead, new rules can be introduced that tweak the values of the extended constants.

Any constants, variables, and generally all scope properties that are available to extensions can be used in rules.

Rules created in extensions are run before the base rules are.

To take the example above, a customer extension page extends the interface constant salutation, providing a locale-specific value. (For example, "Hola Señora (| Señor | ''). The correct salutation is based on the user's gender.

Either the defaultValue property on the constant can be set, or the extension can define a rules model to provide the value. Both configurations are shown, and the behavior is the same if the expression or value configured on the constant's defaultValue is used as is in the rules model.

ExtB: page-x.json - with only defaultValue properties and rules disabled

{
  "extension": {
    "constants": {
      "salutation": {
        "defaultValue": "{{ $functions.getLocaleSalutation($base.variables.user) }}"
      }
    }
  }
}

A customer extension that wishes to use rules instead, will have the configurations below:

ExtB: page-x.json - with extended constants defined in rules

{
  "options": {
    "constantsRules": "on"
  },

  "extension": {},
  ...
}

and

ExtB: page-rules-x.json

{
  "rules": [
  {
      "id": "extB/defaultsRule",
      "condition": {
        "referencedContext": {
          "generated": [ "$base.variables.user" ]
        }
      },
      "overlay": {
        "$base.constants.salutation": "{{ $functions.getLocaleSalutation($base.variables.user) }}"
      }
    }
  ]
}

In this example, the rules file defines a condition with a referencedContext sub-property that includes the variable user referenced in the expression (that was set as the defaultValue property). This is needed if it is required for the rule to participate every time the user variable changes.

Additionally, the overlay object assigns a value to the base constant $base.constants.salutation from ExtA.

The table below assumes that rules are configured for the page on both extensions. When the page loads, the user is not logged in, so an anonymous user, Jane Doe, is used. Then Mia, a sales rep, logs in, causing the variable user, defined on extA, to change. Then she changes her role to 'admin'.

Event Constant Evaluated Value Rule Value
User not logged in at init. $variables.user is not set

mode

salutation

anonUser

greeting

oracle-public

Hola

Jane Doe

Hola Jane Doe!

from extA

from extB. Overrides rule value in extA

from extA

from extA
User Mia logs in. $variables.user is updated and rules are re-run

mode

name

salutation

greeting

oracle-internal

mia

Hola Senora

Hola Senora Mia!

from extA

from extA

from extB. rule amends value based on user's gender

from extA
Mia changes $variables.user.role = "admin". Rules are re-run

mode

salutation

greeting

oracle-restricted

Hola Senora

Hola Senora Mia!

from extA

from extB. rule runs again as a condition is not set

from extA

Note:

Generally, while evaluated rule values are made available to higher priority rules, in the example above, it is noteworthy that the higher priority rule from extB (defaultsRule) provides the value for the constant salutation, this value is available to a lower priority rule (extA/adminRule) that is lower in the run order, as an optimization. All final rule values for the interface constants are assigned to the (page) constants at the end, after the rules have run.

Items to remember about configuring rules in interface constants:

  • Only interface constants are eligible for rules evaluation.
  • All interface constants defined on the base container, must either have its values come from rules, or have the defaultValue property set. An error is flagged if both are present.
  • An extension container that extends one or more interface constants must also either configure a defaultValue property on all constants, or provide values for the same from a rules model.
  • An extension container may choose to provide values (for constants) from rules even if the base container does not have rules.

Usage Scenarios

Let's consider these simple examples involving rules and their behavior.

Note:

For readability, the definitions are condensed.

In this example, ExtC depends on ExtB, which depends on ExtA.

ExtA ExtB ExtC

page.json

{
  "options/constantsRules": "on",
  "interface/constants": {
    foo: { "type": "string" },
    bar: { "type": "string" },

    lucy: { "type": "string" },
    charlie: { "type": "string" }
  }
}

page-x.json

{
  "options/constantsRules": "on",
  "extension/constants": {
    foo: { "type": "string" },
    bar: { "type": "string" },

    charlie: { "type": "string"  }
  }
}

page-x.json

{
  "extension/constants": {
    foo: { "defaultValue": "override from c" },

    lucy: { "defaultValue": "" }
  }
}

page-rules.json

{
    "rule-a1": {
      "foo": "r1 from a"
    },
    "rule-a2": {
      "foo": "r2 from a",
      "bar": "r2 from a"
    },
    "rule-a3": {
      "foo": "r3 from a",
      "bar": "r3 from a",
      "lucy": "r3 from a"
    },
    ...
    "rule-a10": {
      "condition": false
      "lucy": "r10 from a"
    }
}

page-rules-x.json

{
  "rule-b1": {
    condition: false,        
    bar: "r1 from b"
  },
  "rule-b2": {
    foo: "r2 from b"
  },
  "rule-b3: {
    condition: false,
    lucy: "r3 from b" // Error!
  },
  "rule-b4": {
    charlie: "r4 from b"
  }
}

No page-rules-x.json present

In the table below, the final value/expression for the interface constants defined above when evaluated in base and customer extensions are marked in bold.

A constant value from the leaf extension (ExtC) has higher priority over a value provided by a lower extension. The value itself can come from either the defaultValue configuration or from rules. Rules are executed progressively from lowest priority to highest priority, so a value from a leaf extension gets a higher priority.

  • ExtC provides a value for constants ($base.constants.foo, $base.constants.lucy) that overrides rule values from extension ExtB.

  • ExtC does not provide values for other constants (bar and charlie), so values from lower priority extensions are used.
Expression Rules Values in ExtA Rules Values in ExtB Rules Values in ExtC Final Value Why?
$base.constants.foo "r1 from a" "r2 from b" "override from c" "override from c" ExtB value overwrites ExtA
$base.constants.bar "r2 from a" - Blank "r2 from a" Blank
$base.constants.lucy "r3 from a" - '' '' topmost defaultValue is always used it for backwards compatibility.
$base.constants.charlie - "r4 from b" - "r4 from b" Blank