4.2 Data Pages: Scope, Types & Refresh Policies

4.2 Data Pages: Scope, Types & Refresh Policies

CSA Exam Focus: Data Pages represent one of the most heavily tested areas on the Certified Pega System Architect exam. Candidates must master the architectural purpose of Data Pages (formerly Declare Pages, identified by the mandatory D_ prefix), distinguish between Single Page and List structures, configure Read-Only, Editable, and Savable modes, evaluate Thread vs. Requestor vs. Node scopes, configure refresh policies, and leverage parameterized data caching to optimize application memory and performance.

---

Purpose and Mechanics of Data Pages

In Pega applications, a Data Page (Rule-Declare-Pages) is an automated, declarative caching mechanism that retrieves data from an external System of Record (SOR), internal database, or calculation routine and makes that data available to the clipboard on demand.

The Mandatory D_ Naming Convention

Every Data Page rule identifier must begin with the prefix D_ (for example, D_CustomerDetails, D_ProductCatalog, D_ExchangeRates). Pega's rule engine enforces this naming convention across all studio environments.

On-Demand (Just-in-Time) Loading

Data Pages load data on demand. Unlike procedural code that queries databases during system startup or case creation, a Data Page remains unpopulated until an application component—such as a section view, a declare expression, a flow action, or a data transform—actively references it on the clipboard. If a case never navigates to a screen that displays D_ExchangeRates, the data page is never loaded into memory, eliminating wasteful integration queries and memory overhead.

Decoupling Logic from Integration

Data Pages establish a clean abstraction layer between user interface / business rules and technical data access protocols. Case designers configure UI fields to display .CustomerName sourced from D_CustomerDetails[CustomerID: .CustomerID]. The case and UI layers have zero knowledge of whether the underlying data source is a REST connector, a SOAP endpoint, a SQL query, a robotic automation, or a static test data transform. If the enterprise migrates from an Oracle database to a cloud microservice, architects update only the Data Page source configuration; the case types, UI views, and validation rules remain completely unchanged.

---

Data Page Structure: Single Page vs. List

When creating a Data Page, the architect specifies the Structure:

1. Page (Single Page)

Returns a single instance of the designated class. Used when retrieving an individual, discrete record.

• Target Class: Specific data class, such as MyOrg-Data-Customer.
• Clipboard Representation: An individual page containing scalar properties and embedded pages (D_CustomerDetails.FirstName, D_CustomerDetails.CreditScore).
• Common Use Cases: Looking up customer profile details by account ID, retrieving credit ratings by tax identifier, or fetching localized tax rates by postal code.

2. List

Returns an ordered collection of instances of the designated class.

• Target Class: Must be a class derived from Code-Pega-List, with its underlying element class set to the target data object (MyOrg-Data-Product).
• Clipboard Representation: A list page containing a standard pxResults Page List property (D_ProductCatalog.pxResults(1).ProductName).
• Common Use Cases: Populating drop-down menus, radio button options, table grids, product master catalogs, and regional branch directory listings.

---

Data Page Modes: Read-Only, Editable & Savable

The Mode of a Data Page defines how the cached data can be manipulated in memory and whether it can persist updates back to an external System of Record:

                                +---------------------------------+
                                |         Data Page Modes         |
                                +----------------+----------------+
                                                 |
                   +-----------------------------+-----------------------------+
                   |                             |                             |
                   v                             v                             v
              [Read-Only]                   [Editable]                     [Savable]
    - Immutable on clipboard       - Mutable in-memory scratchpad - In-memory editing + persistence
    - Cannot be modified by users  - Can be edited directly       - Configured with Save Options
    - Cached reference/lookup data - Changes NOT saved to SOR     - Saves via Flow Save Data Page
    - Supports Node/Req/Thread     - Scoped to Thread/Requestor   - Modern Pega 8.x / Infinity pattern

1. Read-Only Mode

• Behavior: The data loaded into the Data Page is completely immutable. Neither end users through the UI nor system automations through Data Transforms can modify the properties on a Read-Only data page.
• Intended Use: Reference and lookup data that originates from an external SOR and should not be altered during case processing. Examples include currency conversion rates, state/province code tables, country lists, and corporate interest rate schedules.
• Supported Scopes: Thread, Requestor, and Node.

2. Editable Mode

• Behavior: Acts as an in-memory scratchpad. The Data Page loads initial data from a source (or initializes as an empty page), and users or background automations can freely modify, add, or delete properties directly on the clipboard.
• Limitation: Modifying an Editable Data Page updates only the in-memory clipboard copy; it does not automatically persist those changes back to the external database or SOR.
• Intended Use: Temporary work areas, data staging for complex calculations, or gathering draft information across multiple screen steps before deciding whether to commit.
• Supported Scopes: Thread and Requestor (Node scope is prohibited).

3. Savable Mode

• Behavior: Introduced in Pega 8.x and expanded in Pega Infinity, Savable Data Pages provide a low-code, bidirectional pattern for updating and persisting data back to an external System of Record without writing procedural Java or legacy Activity rules (Rule-Obj-Activity).
• Save Options: The architect configures one or more Save Options on the Data Page definition. Save options specify how changes are committed to the external SOR, such as:
  • Database Save: Saves directly to an external relational database table via Pega's database connector.
  • Connector: Invokes an outbound REST or SOAP integration service to submit updates.
  • Activity: Invokes a custom activity rule for complex multi-system transaction orchestration.
  • Robotic Automation: Passes data to an unattended robotic process automation (RPA) bot.
• Execution in Workflows: In Case Designer, architects persist a Savable Data Page by inserting a Save Data Page automation step directly into a stage process, or by linking it as a post-processing save on a Flow Action (Rule-Obj-FlowAction).
• Supported Scopes: Thread and Requestor (Node scope is prohibited).

---

Data Page Scopes: Thread, Requestor & Node

The Scope of a Data Page defines its memory boundary, lifecycle, and accessibility across concurrent users and processes within the Pega engine:

1. Thread Scope

• Memory Boundary: Isolated to a single case or user thread (pyWorkPage execution context). Every open case tab in an operator's workspace runs in its own thread.
• Lifecycle: Created when first referenced within that specific thread. Discarded automatically when the user closes the case tab or when the case thread terminates.
• Isolation: Changes or parameters in Thread A have zero visibility or impact on Thread B, even for the same logged-in user.
• Best Used For: Data tightly bound to a specific case transaction, such as applicant credit checks, case-specific shipping quotes, or vehicle damage inspection reports.

2. Requestor Scope

• Memory Boundary: Shared across all threads and case tabs belonging to a single logged-in user session (a single Requestor connection).
• Lifecycle: Created on first reference within any thread. Persists in memory across multiple open cases and browser tabs until the user logs out, the HTTP session times out, or the cache is explicitly flushed.
• Memory Optimization: If a customer service representative opens four different complaint cases for the same enterprise customer, a Requestor-scoped D_CustomerProfile loads from the backend system exactly once, sharing the cached data across all four case tabs.
• Best Used For: User session preferences, current operator organization profiles, localized currency settings, or multi-case customer profile caching.

3. Node Scope

• Memory Boundary: Shared across all requestors and all threads running on an entire application server (JVM) node. Every logged-in user and background process on that server shares the exact same memory instance.
• Lifecycle: Loaded once by the first requestor that accesses it. Remains in JVM memory until server shutdown, memory eviction, or scheduled refresh expiration.
• Critical Restriction: Node scope is strictly restricted to Read-Only mode. Pega actively blocks configuring Node scope with Editable or Savable modes. Allowing multiple concurrent requestors to write to a single in-memory Node page would create catastrophic race conditions and database inconsistencies.
• Best Used For: Global, immutable enterprise reference tables that are identical for every user, such as global currency exchange rates, postal code geographical tables, product catalogs, and corporate holiday calendars.

---

Refresh Strategies & Cache Invalidation

Cached data inevitably becomes stale over time. Pega provides declarative Refresh Strategies on the Data Page definition to govern when and how cached pages are invalidated and re-executed:

1. Reload Once Per Interaction

Pega checks whether the data page has already been loaded during the current client-server HTTP interaction. If the page was loaded earlier in the same interaction, Pega reuses it. As soon as the user performs a new interaction (submitting a form, clicking a button, refreshing a screen), Pega flushes the cached instance and reloads the data source upon the next reference.

• Best Used For: Highly dynamic transactional data that changes frequently within an active case.

2. Do Not Reload If Older Than (Time-Based Expiration)

Specifies a time threshold (in days, hours, minutes, or seconds) during which the cached data is considered fresh. When an application references the Data Page:

• If the elapsed time since last load is less than the threshold, Pega returns the cached page immediately without querying the backend.
• If the elapsed time exceeds the threshold, Pega automatically re-executes the data source, refreshes the clipboard, and resets the timer.
• Best Used For: Reference data with predictable update schedules (e.g., refreshing daily FX rates after 24 hours, or refreshing inventory levels after 15 minutes).

3. Reload Based On When Condition

Pega evaluates a specified When condition rule (Rule-Obj-When) each time the Data Page is referenced. If the When rule evaluates to true, Pega flushes the current cache and reloads the page from its data source.

• Best Used For: Event-driven invalidation, such as reloading customer account details when .AccountStatusChanged == true or when a user switches customer accounts.

---

Parameterized Data Pages

Real-world applications require retrieving specific subsets of data based on context. Pega supports Parameterized Data Pages, allowing callers to pass one or more parameters into the data page reference:

• Syntax: D_CustomerDetails[CustomerID: .CustomerID, AccountType: "Checking"]

Parameter-Driven Caching Mechanics

When a Data Page is configured with parameters, Pega does not maintain a single static page. Instead, Pega maintains a family of cached instances on the clipboard, keyed by the unique combination of parameter values passed in:

• If User 1 accesses D_CustomerDetails[CustomerID: "C-100"], Pega loads and caches Customer 100.
• If User 1 subsequently accesses D_CustomerDetails[CustomerID: "C-200"], Pega loads and caches Customer 200 as a separate instance alongside Customer 100.
• If User 1 returns to Customer 100, Pega accesses the existing cached page instantly without re-querying the database.

Clear-on-Parameter-Change vs. Retain Multiple Instances

On the Data Page definition, architects can configure whether Pega retains multiple parameterized instances simultaneously in memory or clears existing instances whenever parameter values change. Retaining multiple instances maximizes response speed for multi-tab workers, while clearing on change minimizes memory consumption in resource-constrained environments.

---

Scope vs. Mode vs. Refresh Compatibility Matrix