Accessing RuleApp and ruleset properties at run time

The execution unit (XU) makes RuleApp and ruleset properties available at run time by storing them in the metadata of the RunContext.

This mechanism allows rule authors to retrieve RuleApp and ruleset properties through BOM B2X and use their values in rule artifacts, such as in rule conditions, rule actions, ruleflows, or functions. RuleApp and ruleset properties are runtime configuration elements and are evaluated exclusively on the Rule Execution Server.

How XU provides properties

At run time, the XU collects all the existing RuleApp and ruleset properties set by the users and stores them in the RunContext metadata.

These properties can include:
  • Custom RuleApp properties
  • Custom ruleset properties
  • Built-in RuleApp or ruleset properties, when explicitly set
  • Read-only properties: ruleset.engine, ruleset.engine.version, ruleset.deployment.date and ruleapp.deployment.date
Only properties that exist at run time are stored and can be retrieved through B2X.
Note: RuleApp properties are retrieved only when rulesets are loaded or updated. As a result, changes to RuleApp property values are not dynamic but will take effect only when the ruleset is initially loaded or when it is updated.

Accessing properties in rules

The RunContext can only be accessed from the BOM B2X code. Rule artifacts, including BAL, decision tables, decision trees, ruleflows, and functions, cannot access it directly.

To use a property in a rule:
  1. Define a BOM attribute or method.
  2. Implement its B2X to retrieve the property.
  3. Use the attribute or method in rule artifacts.

B2X access patterns

RuleApp and ruleset properties are stored in the RunContext metadata as string values. However, the return type of the BOM attribute or method determines which navigation phrases are available in rule conditions and actions.

For this reason, different B2X implementations are required depending on how the property is intended to be used in rules.

B2X code examples

This section provides B2X code examples for retrieving different types of runtime information.
String-based access
Retrieves a property value as a String. Use this pattern when the property must be treated as text (for example, presence checks, string comparison, or logging).
com.ibm.decision.run.RunContextrc = getRunContext();
java.lang.Stringresult = null;
key = "ruleset." + key;
if (rc != null && rc.getMetadata().get(key) != null && rc.getMetadata().get(key) instanceof java.lang.String) {
    result = (java.lang.String) rc.getMetadata().get(key);
}
return result;
Usage in rules (string navigation phrases)
When a BOM attribute or method returns a String, rule conditions and actions can use only string-based navigation phrases, for example:
  • If the ruleset property my.custom.prop is not null.
  • If the ruleset property my.custom.prop contains ABC.
With a String return type, numeric or range-based comparisons are not available
Numeric (typed) access
Converts the string value to a number in B2X so it can be used in numeric comparisons.
com.ibm.decision.run.RunContextrc = getRunContext();
java.lang.Numberresult = 0;
key = "ruleset." + key;
if (rc != null && rc.getMetadata().get(key) != null && rc.getMetadata().get(key) instanceof java.lang.String) {
    try {
        result = java.lang.Double.valueOf(
            (java.lang.String) rc.getMetadata().get(key)
        );
    }
    catch (java.lang.NumberFormatExceptione) {
        // Invalid numeric value: default result is used
    }
}
return result;
Usage in rules (numeric navigation phrases)
When the same property is exposed as a numeric type (for example, Number), rules can use numeric navigation phrases, such as:
  • If the ruleset property my.custom.prop is greater than 10.
  • If the ruleset property my.custom.prop is less than 100.
These comparisons are only possible when the conversion from String to a numeric type is performed in B2X.
Note: The same principle applies to other logical types. If a property represents a boolean or a date, it should be converted in B2X to the corresponding type so that the appropriate navigation phrases are available in rule conditions and actions.
Retrieve ExecutionId/DecisionId
The execution identifier uniquely identifies a single ruleset execution. Unlike RuleApp or ruleset properties, this information is not stored in metadata but is retrieved directly from the RunContext through B2X code:
getRunContext().getExecutionId();
Retrieve RulesetPath
The ruleset path identifies the deployed ruleset that is being executed. This information is provided by the XU as a runtime attribute, and like the ExecutionId, it is retrieved directly from the RunContext through B2X code:
getRunContext().get("rulesetPath");
Error Handling Considerations
RuleApp and ruleset properties may be missing, not set, or contain unexpected values.B2X implementations should always perform null checks, handle conversion errors, and define safe default values to avoid runtime exceptions during rule execution.

Property naming and collision avoidance

RuleApp and ruleset properties share the same metadata storage. To prevent naming conflicts, the XU systematically prefixes property keys:
  • RuleApp properties: ruleapp
  • Ruleset properties: ruleset
Example
If both a RuleApp and a ruleset define the same custom property named:
my.custom.prop
At run time, they are stored as:
  • ruleapp.my.custom.prop
  • ruleset.my.custom.prop
Handling this in B2X
Users keep the original logical name (my.custom.prop) in the BOM and rules. When retrieving properties in B2X, the prefix must be applied to the key, where key represents the original logical name.
For example, if the original property name is my.custom.prop:
  • For ruleset properties: key = "ruleset." + key;

    This transforms my.custom.prop into ruleset.my.custom.prop.

  • For RuleApp properties: key = "ruleapp." + key;.

    This transforms my.custom.prop into ruleapp.my.custom.prop.

This ensures that the correct property is retrieved from the RunContext metadata.

Summary

The XU exposes runtime RuleApp and ruleset properties via the RunContext metadata, which can only be accessed through BOM B2X code. As a XU feature, it is supported by all the Rule Execution Server execution methods, including HTDS and rule sessions.

Key points include:

  • Property storage: Properties are stored as string values in RunContext metadata and can be retrieved only through B2X implementations.
  • Property prefixing: The UX systematically prefixes properties with ruleapp. or ruleset.. Apply these prefixes in B2X code to use original property names in rules.
  • Type conversion: B2X code must convert property values to appropriate types, such as number, boolean or date, to enable corresponding navigation phrases in rules.
  • Runtime attributes: ExecutionId and rulesetPath are also retrieved through B2X but accessed directly from RunContext, not from the metadata
  • Property update behavior: RuleApp property values are refreshed only when rulesets are loaded or updated (for example, ruleset redeployment or ruleset property changes), not on every execution.
  • Error handling: B2X implementations should check nulls, handle conversion errors, and provide safe default values.