Introduction
In the Pega Platform, the Expression Builder is an essential tool for defining logic within Data Transforms, Activities, and When rules. A common requirement in these expressions is to evaluate a decision rule, such as a Decision Table, to retrieve a value dynamically. To achieve this, developers typically use the ObtainValue function from the DecisionTable library, passing three parameters: tools, myStepPage (the primary page in context), and the name of the Decision Table rule.
However, a closer look at various Pega applications reveals two primary ways to invoke this function — and a third, less explicit form worth being aware of:
-
@DecisionTable.ObtainValue(tools, myStepPage, "TableName") -
@(Pega-RULES:DecisionTable).ObtainValue(tools, myStepPage, "TableName")
While both syntaxes are valid and often yield the same result, they interact with Pega’s Rule Resolution engine in fundamentally different ways. This article provides a technical breakdown of these differences, explaining when to use the library-qualified (shorthand) version and when the fully qualified syntax is necessary for application stability.
Technical Comparison of Call Syntaxes
The core distinction between these calling methods lies in the level of detail provided to the Pega engine regarding the function’s location. The Pega Platform officially documents three distinct forms:
| # | Type | Syntax | Description |
|---|---|---|---|
| 1 | Unqualified | @FunctionName(args) |
No library, no ruleset specified. Highest risk of naming conflict. |
| 2 | Library-Qualified (Shorthand) | @LibraryName.FunctionName(args) |
Specifies the library only. Standard ruleset resolution still applies. |
| 3 | Fully Qualified | @(RuleSet:LibraryName).FunctionName(args) |
Specifies both ruleset and library. Bypasses ruleset resolution entirely. |
Note on syntax casing: In the official Pega documentation, the generic syntax template shows library and function names in lowercase — for example,
@(RuleSet:libraryname).functionname(arg1, arg2... argn). In practice, rule names use their actual casing as stored in the platform (for example,Pega-RULESandDecisionTable).
The Unqualified Call: @ObtainValue
The simplest syntax — just the function name prefixed with @. No library and no ruleset are specified, which means if another developer creates a function with the same name in a different library, the call may be affected by ruleset resolution unpredictably. For this reason, the unqualified form carries the highest risk of naming conflicts and is generally avoided in enterprise development.
The Library-Qualified Call (Shorthand): @DecisionTable.ObtainValue
When a library-qualified call is made, Pega initiates its standard Rule Resolution process. The engine searches the current operator’s ruleset list, starting from the top, for any library named DecisionTable that contains the ObtainValue function. This means the system always executes the most applicable version of the function based on the operator’s runtime ruleset stack — allowing intentional overrides when necessary.
The Fully Qualified Call: @(Pega-RULES:DecisionTable).ObtainValue
A fully qualified call provides an explicit path by naming both the ruleset and the library. The engine bypasses the standard search entirely, ignores any other libraries with the same name that might exist higher in the ruleset stack, and goes directly to the specified system-defined version.
When Full Qualification Is Essential: The “Shadowing” Scenario
In most enterprise applications, the library-qualified (shorthand) version is preferred for its readability. However, full qualification becomes essential when dealing with Rule Shadowing — a situation where a custom rule “hides” a standard Pega rule because it exists higher in the ruleset stack.
The Conflict
Imagine your organization requires a custom auditing mechanism. A developer creates a new function with the exact same name as the OOTB (Out-Of-The-Box) function:
-
Function Name:
ObtainValue -
Library:
DecisionTable -
Ruleset:
Org-Int-Framework(Higher in the stack thanPega-RULES)
The Result
If you use the shorthand @DecisionTable.ObtainValue(tools, myStepPage, "TableName"), Pega will find your custom version in Org-Int-Framework first. If your intent was to use the original, standard Pega logic without the custom auditing, the shorthand call will fail to deliver the expected behavior because the custom rule has “shadowed” the system rule.
The Solution
To force the engine to use the system’s original logic, you must use the fully qualified syntax:
@(Pega-RULES:DecisionTable).ObtainValue(tools, myStepPage, "TableName")
This ensures that the engine ignores any custom overrides in the ruleset stack and executes the core platform logic.
Best Practices and Performance
While there is a theoretical performance gain in using fully qualified names (as it skips the ruleset search), the difference is negligible in modern Pega versions due to Rule Caching. Instead, choose your syntax based on clarity and intent:
-
Use Library-Qualified (Shorthand) by Default: For the vast majority of development,
@Library.Functionis cleaner and follows Pega’s standard rule resolution — selecting the most applicable version based on the operator’s runtime ruleset stack — which allows for intentional overrides when necessary. -
Qualify for Precision: Use
@(Ruleset:Library).Functiononly when you must guarantee that a specific version of a function is called, regardless of the user’s ruleset stack or potential naming collisions. -
Consistency: Avoid mixing both styles within the same rule unless there is a technical requirement to do so, as it can confuse other developers during maintenance.
Conclusion
The choice between @DecisionTable.ObtainValue and @(Pega-RULES:DecisionTable).ObtainValue is more than just a matter of style; it is a choice between flexibility and precision. By mastering these subtle differences in Pega’s expression language, developers can better manage complex rule hierarchies and prevent unexpected behavior in large-scale enterprise applications.
References
| Source | Topic |
|---|---|
| Pega Documentation | Functions in Expressions |
| Pega Documentation | Call-Function Method |
| Pega Documentation | Application Stack Hierarchy and Ruleset Resolution |
| Pega Documentation | Function Rule (Rule-Utility-Function) |