4.3 Data Transforms & Object Mapping

4.3 Data Transforms & Object Mapping

CSA Exam Focus: Mastering Data Transforms is essential for achieving high Pega application quality and strict guardrail compliance. The Certified Pega System Architect exam heavily emphasizes Data Transform action types (particularly distinguishing Append to versus Append and Map to), the relationship between pySetFieldDefaults and pyDefault, the execution mechanics of the 'Call superclass data transform' pattern across the inheritance hierarchy, and the architectural mandate to use Data Transforms instead of procedural Activities for data manipulation.

---

Declarative Object Mapping: The Role of Data Transforms

In Pega, a Data Transform (Rule-Obj-Model) is a declarative rule that converts data from one format or structure to another, initializes default property values on clipboard pages, and copies information between case types and data objects.

The Guardrail Mandate: Data Transforms vs. Activities

In early versions of the Pega platform, developers frequently wrote procedural Activity rules (Rule-Obj-Activity) using methods such as Property-Set, Page-New, and Page-Copy to manipulate data. In modern Pega (Infinity), using activities for data manipulation severely violates Pega guardrails and degrades the application's Guardrail Compliance Score.

Architectural Rule: Always use Data Transforms for initializing case properties, mapping data between pages, copying collection elements, and formatting values. Reserve Activities strictly for operations that cannot be handled declaratively, such as invoking legacy integrations, interacting with hardware interfaces, or executing complex transactional database commits (Obj-Save / Commit).

---

Data Transform Action Types

A Data Transform rule consists of an ordered sequence of action rows configured in Dev Studio. Each row specifies an action type, a target property or page, a source expression, and optional conditional logic:

+---------------------------------------------------------------------------------------+
| Action Type            | Target Context        | Source Context    | Primary Purpose  |
+------------------------+-----------------------+-------------------+------------------+
| Set                    | .Customer.FullName    | Param.InputName   | Value assignment |
| Remove                 | .TempCreditScorePage  | (None)            | Memory cleanup   |
| Update Page            | .BillingAddress       | (None)            | Context switch   |
| Apply Data Transform   | (Current or Specified)| Rule Name         | Modular reuse    |
| Append to              | .TargetList           | .SourceList       | Direct copy      |
| Append and Map to      | .TargetList           | .SourceList       | Schema mapping   |
| When / Otherwise When  | Conditional Logic     | Boolean Expression| Dynamic branching|
| Comment                | (None)                | Text Annotation   | Documentation    |
+---------------------------------------------------------------------------------------+

Detailed Action Descriptions

1. Set: Assigns a value from a source to a target. The source can be a literal string, another property, a calculation expression, a parameter (Param.TaxRate), or a Data Page (D_CustomerSummary.CreditTier).
2. Remove: Deletes a property, an embedded page, or a collection element from clipboard memory (Page-Remove). Crucial for purging sensitive data or temporary calculation pages before case persistence.
3. Update Page: Temporarily sets the execution context to a designated target page. Any indented child actions nested beneath Update Page execute in the context of that target page, simplifying property references without repeating full page path qualifiers.
4. Apply Data Transform: Invokes another Data Transform rule modularly. Architects can pass parameters into the invoked transform and execute it in the current page context or against a different target page.
5. Append to: Copies elements from a source list or single page directly into a target Page List or Value List without altering property names or structures. Copies entire pages as-is.
6. Append and Map to: Appends a new, empty page to a target Page List, establishes the context of that newly created page, and executes indented child actions to map and transform properties between disparate source and target schemas.
7. When / Otherwise When / Otherwise: Evaluates boolean expressions or references When condition rules (Rule-Obj-When). Child rows indented beneath the condition execute only when the expression evaluates to true.
8. Comment: Allows architects to document business intent, requirement traceability, and non-obvious logic directly within the rule definition.

---

Case Initialization: pySetFieldDefaults vs. pyDefault

When a new case is created (during the pyNewWork process), Pega automatically executes standard data transforms to initialize the case work object (pyWorkPage). Understanding how Pega coordinates pySetFieldDefaults and pyDefault is a core CSA competency.

The pySetFieldDefaults Pattern

When citizen developers or architects configure default values for fields in App Studio (for example, setting default priority to "Medium" or auto-populating initial customer structures), App Studio automatically generates and updates the pySetFieldDefaults Data Transform.

• Maintenance: App Studio manages pySetFieldDefaults. System architects should allow App Studio to own this rule and avoid manually modifying it in Dev Studio to prevent low-code synchronization conflicts.
• Scope: Focuses strictly on initializing default values for user-facing fields and simple embedded page structures defined on views.

The pyDefault Pattern

pyDefault is the standard, specialized framework data transform executed whenever a case instance is instantiated.

• System Responsibilities: Initializes core operational case properties, including:
  • Case Status (.pyStatusWork = "New")
  • Initial Case Urgency (.pxUrgencyWork = 10)
  • Default work party roles (.pyWorkParty)
  • Complex embedded data structures and foreign keys
• Developer Best Practice: Dev Studio architects specialize pyDefault to configure complex business initialization rules, call sub-transforms, and establish pre-populated data page references.

Execution Relationship

In standard Pega case types, pyDefault explicitly invokes pySetFieldDefaults as its very first action row (Apply Data Transform: pySetFieldDefaults). This ensures that App Studio field defaults are applied first, after which pyDefault applies advanced system and operational defaults.

---

Superclass Data Transforms & Class Inheritance Hierarchy

Pega's Enterprise Class Structure (ECS) relies heavily on object-oriented inheritance. When building specialized case types that inherit from parent application or framework layers, architects must ensure that enterprise-wide default properties and compliance rules are consistently applied.

The "Call Superclass Data Transform" Option

On the Data Transform rule form in Dev Studio, the architect can select the Call superclass data transform checkbox.

                                [Work-Cover- (Core Pega Engine)]
                                               |
                                               v (Executes 1st)
                                  [MyOrg-Work (Enterprise Layer)]
                                  - Sets .ComplianceRegion = "Global"
                                  - Sets .CorporateLegalDisclaimer = true
                                               |
                                               v (Executes 2nd)
                                [MyOrg-App-Work (Application Layer)]
                                - Sets .ApplicationVersion = "2.4"
                                - Sets .pyStatusWork = "New"
                                               |
                                               v (Executes 3rd)
                           [MyOrg-App-Work-Loan (Specialized Case Type)]
                           - Overrides .pyStatusWork = "Draft-Underwriting"
                           - Sets .DefaultLoanTerm = 360

Top-Down Inheritance Execution Order

Critical CSA Exam Rule: When "Call superclass data transform" is enabled, Pega navigates up the inheritance hierarchy (evaluating both pattern and directed inheritance) to find the highest superclass containing a data transform of the exact same name.

Pega executes the transforms in top-down order (from the highest superclass down to the child class):

1. The highest superclass data transform executes first, setting foundational enterprise defaults.
2. Intermediate application layer transforms execute second, applying divisional defaults.
3. The local child class data transform executes last.

Overriding Behavior: Because the child class transform executes last, any properties set by the child transform cleanly override values established by the superclasses. Conversely, any properties set by the superclasses that are not explicitly touched by the child transform remain intact on the clipboard. This enforces corporate governance while preserving local specialization.

---

Deep Dive: Append to vs. Append and Map to

A frequent source of confusion on the CSA exam is knowing when to use Append to versus Append and Map to when manipulating collections:

Pattern 1: Append to (Direct Page Copy)

Use Append to when copying pages between two collections that share the exact same class and schema, where no property renaming, data transformation, or filtering of individual attributes is required.

• Action Row: Append to
• Target: .CaseLineItems (Page List of class MyOrg-Data-Item)
• Relation: an existing page or each page in
• Source: D_FavoriteItems.pxResults (Page List of class MyOrg-Data-Item)
• Result: Pega copies each entire page from the source list directly into the target list as-is.

Pattern 2: Append and Map to (Schema Transformation)

Use Append and Map to when the source collection and the target collection have different classes or property names, or when specific attributes must be calculated, formatted, or initialized during the copy process.

Step-by-Step Walkthrough: Product Catalog to Case Order Items

Consider an enterprise scenario where a case worker selects items from a product catalog data page (D_ProductCatalog.pxResults, class MyOrg-Data-CatalogItem) and copies them into the case order line items (.OrderItems, class MyOrg-Data-OrderItem):

Row 1: Append and Map to
       Target: .OrderItems
       Relation: each page in
       Source: D_ProductCatalog.pxResults

    Row 1.1: Set  .SKU               =  <CURRENT>.ProductID
    Row 1.2: Set  .ItemDescription   =  <CURRENT>.CatalogName
    Row 1.3: Set  .UnitPrice         =  <CURRENT>.WholesalePrice * 1.20
    Row 1.4: Set  .QuantityOrdered   =  1
    Row 1.5: Set  .AddedDate         =  @CurrentDateTime()

Runtime Mechanics of Append and Map to:

1. Pega iterates over each page in the source collection (D_ProductCatalog.pxResults).
2. For each source item, Pega creates a new, blank page at the end of the target Page List (.OrderItems).
3. Inside the indented rows (1.1 through 1.5), Pega sets the primary context to the newly created target page. Properties written as .SKU or .UnitPrice automatically target the new line item.
4. To reference properties on the source collection row being copied, Pega provides the special contextual keyword <CURRENT> (e.g., <CURRENT>.ProductID).
5. The indented logic executes, transforms the data, and proceeds to the next source element.

---

Best Practices for Data Transform Design

1. Maintain Single-Purpose Transforms: Build modular, reusable data transforms focused on a single responsibility (e.g., SetAddressDefaults, CalculateTaxTotal, MapCustomerProfile) and coordinate them using Apply Data Transform.
2. Avoid Procedural Activities for Data Manipulation: Never write activities containing Property-Set steps. Data Transforms are declarative, self-documenting, and preserve application guardrail scores.
3. Leverage <CURRENT> and <TARGET> Contexts: When writing nested collection mapping, use Pega's built-in contextual keywords rather than hardcoding complex clipboard paths.
4. Clean Up Ephemeral Data: Always include a Remove action to delete temporary calculation pages or sensitive credentials from the clipboard before the case advances to assignments or resolution.