5.3 Integration Connectors, Systems of Record & Error Handling

5.3 Integration Connectors, Systems of Record & Error Handling

Enterprise software rarely operates in isolation. A Pega application frequently orchestrates workflows that require accessing customer master records from an Oracle ERP, checking creditworthiness against an Experian bureau API, charging payments through a Stripe gateway, or synchronizing account status with Salesforce. In enterprise architecture, these external data repositories are known as Systems of Record (SOR).

To interact with Systems of Record while preserving high application quality and decoupling business processes from external changes, Pega provides a robust Integration Architecture centered on Connectors, Data Pages, and standardized error-handling frameworks.

---

1. Pega Integration Architecture: Systems of Record (SOR)

In Pega, Pega itself acts as the business process management and workflow engine, while authoritative business data remains anchored in specialized Systems of Record. When designing integrations, Pega enforces a strict separation between integration data contracts and application data models using the Enterprise Class Structure (ECS).

+-------------------------------------------------------------------------+
|                   ENTERPRISE CLASS INTEGRATION LAYERING                 |
+-------------------------------------------------------------------------+
| CASE LAYER:        UPlus-Retail-Work-Order                              |
|                    Binds only to clean canonical Data Pages             |
+-------------------------------------------------------------------------+
| DATA LAYER:        UPlus-Data-Customer                                  |
|                    Canonical business data model (.FirstName, .TaxID)   |
+-------------------------------------------------------------------------+
|                                 ^                                       |
|              Response Data Transform Maps Data Model                    |
|                                 |                                       |
+-------------------------------------------------------------------------+
| INTEGRATION LAYER: UPlus-Int-CustomerAPI-                               |
|                    Mirrors external vendor JSON/REST schema             |
|                    (e.g., cust_first_name, tax_identifier_code)         |
+-------------------------------------------------------------------------+

Why Separate Int- from Data-?

• External Schema Isolation: External APIs frequently use vendor-specific naming conventions (snake_case, abbreviations, legacy IDs). The Int- class hierarchy absorbs these vendor quirks.
• Vendor Agnosticism: If an enterprise replaces its credit scoring vendor from Equifax to TransUnion, only the Int- connector classes and mapping data transforms change. The case workflows and user interfaces, which bind exclusively to canonical Data- classes, remain 100% untouched.

---

2. Connectors vs. Services

The direction of communication defines whether an integration interface is classified as a Connector or a Service.

Exam Rule of Thumb: Remember: Connectors Call out; Services Serve incoming requests.

---

3. REST Connectors (Rule-Connect-REST)

Modern enterprise integrations rely overwhelmingly on REST (Representational State Transfer) web services communicating via HTTP using JSON payloads. In Pega, REST integrations are configured using Connect REST rules (Rule-Connect-REST).

Core Configuration Tabs of a Connect REST Rule

1. Service Tab:
   • Endpoint URL: Specifies the base URL of the target resource (e.g., https://api.payments.com/v2/charges).
   • Dynamic System Settings (DSS) Parameterization: Hardcoding environment-specific URLs directly into rule forms violates Pega guardrails. Architects parameterize endpoint URLs using Dynamic System Settings or Application Settings, enabling seamless transitions between Development, Staging, and Production environments without modifying locked rulesets.
   • Authentication: Specifies the authentication profile (Rule-Admin-Security-AuthenticationProfile), supporting Basic Auth, OAuth 2.0 (Client Credentials, Authorization Code), API Keys, and Mutual TLS.
2. Methods Tab:
   • Defines the HTTP verbs supported by the connector:
     • GET: Retrieve resource data (e.g., fetching customer profile by ID).
     • POST: Create a new resource or execute a remote operation (e.g., submitting a credit card charge).
     • PUT / PATCH: Update or replace an existing resource record.
     • DELETE: Remove a resource from the external system.
   • For each HTTP method, the architect configures:
     • Query Parameters: Key-value pairs appended to the URL string (e.g., ?status=active&limit=50).
     • Headers: HTTP headers sent with the request (e.g., Accept: application/json, Content-Type: application/json).
     • Request Data Transform: Maps clipboard properties into the outbound JSON payload (Serialization).
     • Response Data Transform: Parses the incoming JSON payload into Pega properties (Deserialization).

---

4. Accelerating Integration with the REST Integration Wizard

Rather than authoring classes, properties, request transforms, and connectors manually, Dev Studio provides the REST Integration Wizard (Configure $\rightarrow$ Integration $\rightarrow$ Connectors $\rightarrow$ Create REST Integration).

+-------------------------------------------------------------------------+
|                      REST INTEGRATION WIZARD ARTIFACTS                  |
+-------------------------------------------------------------------------+
| 1. Input: OpenAPI / Swagger Specification File OR Sample JSON Payloads  |
|                               |                                         |
|                               v                                         |
| 2. Pega Generates:                                                      |
|    - Integration Base Class:       MyOrg-Int-PaymentService-            |
|    - Request / Response Classes:   MyOrg-Int-PaymentService-Charge-     |
|    - Single-Value & Page Properties for each JSON attribute             |
|    - Connect REST Rule:            PaymentServiceConnector              |
|    - Request & Response Data Transforms                                |
|    - Autonomic Data Page:          D_PaymentTransaction                 |
+-------------------------------------------------------------------------+

The wizard dramatically reduces delivery time while enforcing Pega guardrails by ensuring generated property types match the JSON schema (strings, numbers, booleans, arrays).

---

5. Data Pages as the Integration Abstraction Layer

A cardinal rule of Pega system architecture is: Case workflows and UI views must NEVER call Connectors directly.

Instead, cases interact exclusively with Data Pages (e.g., D_CustomerProfile[CustomerID: .CustID]). The Data Page acts as an abstraction facade that encapsulates integration mechanics:

  Case Workflow / View (Work-) 
             | 
             v 
   Data Page (D_CustomerProfile) 
             | 
             +---> [Option A: In Production]  =======> Connect REST (Real API) 
             | 
             +---> [Option B: In Development] ======> Simulated Data Transform (Mock Data) 

Benefits of the Data Page Abstraction Layer

1. Data Caching & Performance: Data pages support Thread, Requestor, and Node scopes with automated refresh policies (e.g., reload once per interaction or after 60 minutes), preventing repetitive, expensive API calls.
2. Parameterization: Data pages accept runtime parameters (such as customer IDs or account numbers) to fetch individual keyed instances dynamically.
3. Data Simulation: On the Data Page rule form, architects can select the Simulate data source checkbox and associate a simulation Data Transform. When enabled, the Data Page populates realistic mock data on the clipboard without calling the external API. This allows developers to construct and test end-to-end case workflows months before external vendor endpoints are ready.

---

6. Enterprise Error Handling Architecture

Distributed integrations inherently encounter failures: network connections drop, API servers restart, authorization tokens expire, or malformed data triggers validation errors. A resilient Pega application must gracefully intercept, categorize, and handle every failure mode.

Error Classification: Transient vs. Fatal Errors

Standard Error Handling Mechanisms

When a Connect REST rule executes, Pega automatically populates technical execution status properties on the integration page, including pxFeedback, pxMethodStatus, and the HTTP response code.

1. Response Data Transform Error Check:
   • Immediately after the connector completes, the Response Data Transform executes.
   • The transform evaluates a condition checking whether the execution succeeded: @hasMessages() or param.pyStatus != "Good".
2. Applying pxErrorHandlingTemplate:
   • If a failure is detected, the Response Data Transform applies the standard platform data transform pxErrorHandlingTemplate.
   • This standard rule extracts technical error messages, error codes, and stack traces, standardizing the fault structure.
3. Case Status & Work Queue Routing:
   • When a fatal integration error prevents case progression, the case must not be abandoned or crashed in the user's browser.
   • The application updates the case status property: .pyStatusWork = "Open-Error".
   • The assignment is routed away from regular user worklists into a centralized Exception Work Queue (e.g., IntegrationExceptionsQueue).
   • Specialized operations personnel or technical administrators monitor this queue, inspect the payload error logs, rectify the root issue (e.g., renew an expired API token or fix a customer tax ID), and re-submit the case into the workflow.

---

7. Common Exam Traps & Architectural Pitfalls

• Trap 1: Hardcoding Endpoint URLs. Never accept an answer choice recommending typing hardcoded IP addresses or domain URLs directly into the Connect REST rule form. Always use Dynamic System Settings or Application Settings.
• Trap 2: Directly calling connectors from flow action post-processing activities. Connecting directly from UI flows bypasses Data Page caching and prevents data simulation. Always access external data through a Data Page.
• Trap 3: Retrying fatal 4xx errors. Exam scenarios often describe an HTTP 401 Unauthorized or HTTP 400 Bad Request error. The incorrect distractor suggests setting an automated retry loop. Re-attempting a bad request or bad password 50 times will never succeed and may lock the enterprise service account. Fatal errors require administrative exception routing.