5.1 Declare Expressions & Declarative Network Chaining

5.1 Declare Expressions & Declarative Network Chaining

In traditional software engineering, calculations and data derivations rely on procedural processing—code executes in a rigid, imperative sequence dictated by the developer. If a customer modifies their order quantity, the developer must explicitly invoke a subroutine or method to recalculate line totals, sales tax, shipping fees, and invoice grand totals. If an engineer forgets to invoke this routine in a newly added user interface screen or integration endpoint, the application state desynchronizes, leading to data corruption and audit failures.

Pega Platform eliminates this class of defects through declarative processing. Rather than writing procedural execution logic, architects define declarative rules that specify what relationships exist between properties. The underlying Pega engine (PRPC - PegaRULES Process Commander) automatically manages when and how calculations execute across the application lifecycle.

---

1. Declarative vs. Procedural Processing in Pega

To build robust, low-maintenance Pega applications, a System Architect must clearly distinguish between procedural and declarative paradigms.

The Declarative Principle

Under the declarative model, the developer states: $\text{.TotalAmount} = \text{.SubTotal} + \text{.TaxAmount} - \text{.DiscountAmount}$ The developer does not specify when this formula runs. Whether .SubTotal changes via an interactive web portal, a background mobile sync, or a REST API connector, the Pega engine detects the clipboard alteration and immediately ensures .TotalAmount reflects the accurate result.

---

2. Declare Expressions (Rule-Declare-Expressions)

A Declare Expression is a declarative rule that establishes a computational relationship for a single target property based on one or more source properties.

+-------------------------------------------------------------------------+
|                   DECLARE EXPRESSION RULE STRUCTURE                     |
+-------------------------------------------------------------------------+
| Target Property:    .TotalAmount                                        |
| Context Class:      UPlus-Retail-Work-Order                             |
| Calculation Logic:  .SubTotal + .TaxAmount - .DiscountAmount            |
| Chaining Mode:      Forward Chaining (Immediate UI & Memory Sync)       |
+-------------------------------------------------------------------------+
| Source Properties Monitored:                                            |
|   - .SubTotal                                                           |
|   - .TaxAmount                                                          |
|   - .DiscountAmount                                                     |
+-------------------------------------------------------------------------+

Key Components of a Declare Expression

1. Target Property: The single property whose value is calculated and maintained by the rule. A property managed by a Declare Expression cannot be directly overwritten by manual user input on forms unless specifically configured to allow user override.
2. Expression Context: The class where the rule is defined. Declare Expressions can be authored at the case level (Work-), on embedded data pages (Data-), or within collections (Page List).
3. Calculation Formula: Can be a simple mathematical expression (.Quantity * .UnitPrice), a string concatenation (.FirstName + " " + .LastName), or complex conditional branching using If/Else logic built directly into the rule form.
4. Built-in Functions: Declare expressions can invoke standard Pega functions from the library, such as @round(.Value, 2), @DateTimeDifference(.StartDate, .EndDate, "D"), or @sizeOfPropertyList(.LineItems).

---

3. The Declarative Network & Dependency Graph

When multiple Declare Expressions exist within an application, Pega does not treat them as isolated formulas. Instead, PRPC analyzes the relationships between all target and source properties to construct an internal directed acyclic graph (DAG) called the Declarative Network.

  [ .Quantity ] ---+ 
                   |---> ( .LineItemTotal ) ---+ 
  [ .UnitPrice ] --+                           | 
                                               |---> ( .SubTotal ) ---+ 
  [ .TaxRate ] --------------------------------+                      | 
                                                                      |---> ( .GrandTotal ) 
  [ .DiscountAmount ] ------------------------------------------------+ 

Dependency Propagation (The Ripple Effect)

In the network above:

• .LineItemTotal depends directly on .Quantity and .UnitPrice.
• .SubTotal depends on an aggregation of all .LineItemTotal values.
• .GrandTotal depends on .SubTotal, .TaxRate, and .DiscountAmount.

If a user alters .Quantity from 2 to 5, the engine triggers a cascading recomputation chain:

1. Recomputes .LineItemTotal for that specific item.
2. Recomputes .SubTotal across the order.
3. Recomputes sales tax based on the new .SubTotal.
4. Recomputes .GrandTotal.

Because the Declarative Network is resolved using topological sorting, the engine guarantees that no property is computed before its prerequisite inputs are fully updated, preventing intermediate race conditions.

---

4. Chaining Modes: Forward Chaining vs. Backward Chaining

The Pega engine provides two distinct execution modes that govern when the Declarative Network evaluates calculations: Forward Chaining and Backward Chaining.

Forward Chaining (Immediate Push Model)

Forward chaining is the default and overwhelmingly common mode in Pega Platform.

• Mechanism: The engine uses a Push strategy. Whenever any monitored input property changes value on the Clipboard, the engine immediately pushes recomputations forward through every downstream node in the dependency network.
• User Interface Synchronization: Forward chaining integrates tightly with Pega's UI layers. When a form field is configured with an action set (e.g., Event: Change $\rightarrow$ Action: Refresh section or Post value), modifying the field pushes updates to the clipboard, instantly recalculating target values and updating the browser display synchronously.
• Best Use Cases: Interactive form calculations, invoice totals, order balances, dynamic pricing, and real-time validation checks where users expect instant feedback.

Backward Chaining (Deferred Pull Model)

In contrast to forward chaining, backward chaining operates on a Pull strategy.

• Mechanism: The engine does not recalculate the target property when input properties change. Instead, computation is deferred until an external rule, report, user interface, or process explicitly requests or reads the target property from the Clipboard.
• Configuration in Dev Studio: On the Change Tracking tab of the Declare Expression rule form, architects can configure backward chaining under the Calculate Value options:
  1. Compute if missing (Default for Backward Chaining): If the target property already contains a non-null value, PRPC uses it as-is. If the property is empty or null when read, the engine traces backwards through the dependency network, computes missing inputs, and populates the target.
  2. Always compute: Every single time the target property is referenced by any rule or UI element, the engine forces a fresh recalculation from source properties, regardless of whether a value is already present.
  3. Prompt user for missing inputs: If a required source property in the dependency chain is blank, PRPC halts execution and displays a system-generated form asking the user to provide the missing input before completing the calculation.
• Best Use Cases: Computationally expensive or resource-intensive derivations that are rarely needed (e.g., generating complex actuarial risk scores, algorithmic credit limits, or heavy predictive valuations required only at final approval milestones).

---

5. Context-Sensitive Calculations Across Page Lists

Real-world enterprise cases frequently manage collections of records—such as line items on an invoice, dependents on an insurance policy, or assets on a loan application. In Pega, these collections are represented as Page Lists (Data- classes embedded within Work-).

Pega Declare Expressions natively support calculations across Page Lists without requiring procedural loops or temporary iteration variables.

1. Row-Level Expressions (Embedded Context)

To compute a value on every line item, the Declare Expression is authored in the item's data class (e.g., UPlus-Data-LineItem): $\text{.LineItemTotal} = \text{.Quantity} \times \text{.UnitPrice}$ Whenever .Quantity or .UnitPrice is modified on any row in the table, Pega updates that specific row's .LineItemTotal.

2. Collection Aggregate Expressions (Top-Level Case Context)

To aggregate row values into a case-level total, the Declare Expression is authored in the case class (e.g., UPlus-Retail-Work-Order), referencing aggregate functions across the Page List:

Exam Tip: In Pega modern syntax, expressions can also reference collection aggregates using simplified dot notation, such as sum(.LineItems().LineItemTotal). The platform automatically binds change listeners to the collection: inserting a row, deleting a row, or editing a cell immediately triggers the parent aggregate expression.

---

6. Declarative Network Analysis & Diagnostics in Dev Studio

When complex applications contain dozens of interrelated declarative rules, diagnosing unexpected calculation values requires specialized debugging tools rather than guesswork.

Dev Studio Declarative Network Display

Architects can visually inspect the active dependency graph directly within Dev Studio:

1. Open the target Property or Declare Expression rule form.
2. In the toolbar, click Actions $\rightarrow$ View declarative network (or click the Declarative Network button).
3. The platform renders an interactive, visual dependency tree showing:
   • Upstream Nodes (Inputs): All properties and expressions feeding into the current property.
   • Downstream Nodes (Targets): All properties dependent on the current property.
   • Chaining Indicators: Visual markers designating whether each edge is governed by Forward or Backward chaining.

Debugging Declarative Rules with the Tracer

The Pega Tracer is the primary diagnostic tool for inspecting runtime declarative execution:

• Open Tracer Settings and enable the Declare Expression and Declare Rule event types.
• In the Tracer output, declarative events appear with a distinct visual banner.
• Architects can inspect the exact old property value, the new property value, the applied formula, and the ruleset version that resolved the expression.
• If a calculation fails to fire, the Tracer reveals whether the input property was properly posted to the Clipboard or if a precondition halted the evaluation.

---

7. Common Exam Traps & Architectural Pitfalls

• Trap 1: Confusing Forward and Backward Chaining Triggers. Exam questions often describe a scenario where an expensive calculation executes too frequently. The solution is switching from Forward Chaining to Backward Chaining with Compute if missing, not adding an Activity.
• Trap 2: Attempting to proceduralize Declare Expressions. Never call a Declare Expression from a Data Transform or Activity. Declare Expressions fire automatically based on platform dependency monitoring. Explicitly invoking them violates core architecture principles.
• Trap 3: Circular Dependencies in Declarative Networks. If Expression A depends on Property B, and Expression B depends on Property A, Pega cannot construct a directed acyclic graph. Dev Studio rule validation flags circular dependencies as fatal compilation errors.