11.2 Web Mashup, Digital Channels & Constellation Embed

Web Mashup, Digital Channels & Constellation Embed

Enterprise organizations rarely force customers or business partners to interact with their systems exclusively through dedicated back-office portals. Instead, modern digital strategies demand that business processes be seamlessly embedded into existing public corporate websites, customer self-service extranets, mobile consumer apps, and conversational channels such as email and chatbots.

The Pega Platform realizes this vision through its Multichannel Architecture. By decoupling business logic, case stages, data validation, and Service Level Agreements (SLAs) from presentation, Pega allows organizations to "Build for Change" once and deploy everywhere. This section contrasts traditional Pega Web Mashup with modern Constellation Embed, details cross-origin security frameworks, and explores conversational digital channels.

---

1. Pega Multichannel Architecture: Build Once, Deploy Everywhere

In traditional software development, supporting multiple engagement channels often meant writing duplicate business logic: one codebase for the web portal, another for mobile apps, and bespoke middleware for email parsing. Pega eliminates this duplication:

+-------------------------------------------------------------------------+
|                    PEGA MULTICHANNEL CORE ARCHITECTURE                  |
+-------------------------------------------------------------------------+
|                [ CENTRALIZED PEGA CASE LIFECYCLE ENGINE ]               |
|   - Case Stages, Steps, and Flow Rules                                  |
|   - Enterprise Data Model & Data Pages                                  |
|   - Declarative Business Rules, Validations, & SLAs                     |
|   - Security Roles, Access Groups, & Attribute-Based Access Control     |
+-------------------------------------------------------------------------+
                                     │
       ┌───────────────┬─────────────┴───────────────┬────────────────┐
       ▼               ▼                             ▼                ▼
+-------------+ +-------------+               +-------------+  +-------------+
| PEGA MOBILE | | WEB MASHUP  |               |CONSTELLATION|  |CONVERSATION | 
|   CLIENT    | | (TRADITIONAL|               |    EMBED    |  |  CHANNELS   |
| Hybrid App  | | DIV/IFRAME) |               | (WEB COMPONENT|  | Email Bot,  |
| iOS/Android | | Portal Div  |               | DX API v2)  |  | Chatbots    |
+-------------+ +-------------+               +-------------+  +-------------+

Regardless of whether a customer initiates an auto insurance claim via an embedded web component on an external portal, an automated email bot, or a smartphone app, the exact same validation rules, calculation engines, and stage transitions govern the case.

---

2. Traditional Pega Web Mashup (Pega Composite Gateway)

Pega Web Mashup (historically known as the Pega Composite Application Gateway) enables organizations to embed Pega application functionality directly into an existing external web page (such as an enterprise intranet or public commercial website).

The Mashup Integration Mechanism

A web mashup operates by injecting a Pega-controlled <div> container into the host page's Document Object Model (DOM). The host page includes Pega mashup JavaScript libraries (pega.web.mashup or pzIncludeMashupScripts) that communicate with the Pega application server, rendering the case interface inside an auto-generated responsive iframe.

Core iaction Directives

The behavior of the embedded mashup gadget is governed by the data-pega-action attribute (or iaction in legacy syntax):

1. createNewWork: Instantiates a new case of the specified class (defined by data-pega-classname) and opens the initial assignment view. Common for public customer self-service forms (e.g., submitting a credit card application or warranty claim).
2. openAssignment: Opens a specific pending assignment directly, identified by its unique assignment key (data-pega-actionparam-assignmentkey). Frequently used when an external system deep-links a manager into an approval task.
3. openWorkItem: Opens an existing case record in read-only or review mode using its business identifier (pyID, specified via data-pega-actionparam-workid).
4. openWorkByHandle: Opens an existing case using its internal unique system identifier (pzInsKey).
5. getNextWork: Evaluates the user's skills, work groups, and assignment urgency to retrieve and present the next highest-priority assignment from the enterprise workbasket or worklist.

Essential Gadget Attributes

A standard Pega Web Mashup snippet embedded in an external HTML page includes several mandatory configuration attributes:

<!-- Pega Web Mashup Gadget Container -->
<div id="PegaGadgetA"
     data-pega-gadgetname="PegaGadgetA"
     data-pega-action="createNewWork"
     data-pega-classname="FSG-Banking-Work-CreditCardApplication"
     data-pega-flowname="pyStartCase"
     data-pega-url="https://pega.enterprise.com/prweb/PRServlet"
     data-pega-application="CreditCardServices"
     data-pega-threadname="STANDARD"
     data-pega-systemid="pega"
     data-pega-parameters="{CustomerTier:'Gold', LeadSource:'CorporatePortal'}">
</div>
<script src="https://pega.enterprise.com/prweb/PRServlet/pzIncludeMashupScripts.js"></script>

• data-pega-gadgetname: Assigns a unique DOM identifier to the gadget instance, enabling JavaScript interactions between the host page and the gadget.
• data-pega-url: The URL of the Pega gateway servlet (typically /prweb/PRServlet or a secure custom access servlet).
• data-pega-threadname: Isolates the Clipboard memory state of the mashup session in a dedicated Pega Thread, preventing cross-session interference.
• data-pega-parameters: Passes contextual data from the parent host page into the Pega Clipboard. These parameters populate properties on pyWorkPage or initialize parameters on the starting flow.
• pzSetDataPage: A specialized mashup action that allows the host page to set or refresh parameters on a designated Clipboard Data Page without refreshing the entire visual layout.

Cross-Origin Security, Domain Whitelisting & CSP

Embedding an enterprise rules engine into third-party web domains introduces significant security risks, including Cross-Site Scripting (XSS), cross-origin data tampering, and clickjacking. Pega enforces three layers of defense:

1. Action Authentication:
   • Mashups can operate under authenticated single sign-on (SSO) using SAML 2.0 or OpenID Connect.
   • For public-facing, unauthenticated scenarios (e.g., public loan applications), the mashup connects through a restricted Anonymous Access Service (utilizing an unauthenticated guest requestor pool, such as pyAnonymous) configured with strict, least-privilege security roles.
2. Domain Whitelisting (CORS Protection):
   • Pega strictly prohibits cross-origin communication from untrusted websites.
   • In the Pega Application rule (or Mashup Channel interface under Trusted domains), architects must explicitly define all permissible parent origins (e.g., https://www.mycompany.com, https://intranet.mycompany.com).
   • During runtime, the Pega mashup script checks the window.postMessage origin. If the host page domain is not explicitly whitelisted, the Pega engine blocks all script communication and refuses to render the gadget.
3. Content Security Policy (CSP) & Frame-Ancestors:
   • To protect against Clickjacking (where an attacker embeds the Pega mashup inside a transparent iframe on a malicious website to hijack user clicks), Pega administrators configure Content Security Policy rules (Rule-Access-CSP).
   • The HTTP response header Content-Security-Policy: frame-ancestors https://www.mycompany.com instructs the client browser that only designated enterprise origins are permitted to frame the Pega application.

---

3. Modern Constellation Embed: Web Components & DX API v2

While traditional Pega Web Mashup remains widely deployed in legacy architectures, modern enterprise front-end development has converged on component-driven Single Page Application (SPA) frameworks (React, Angular, Vue). Embedding legacy iframes into modern SPAs introduces well-known challenges: rigid styling boundaries, double vertical scrollbars, mobile responsive layout glitches, and browser cookie restrictions (SameSite cookie blocking).

Pega resolves these limitations with Constellation Embed.

+-------------------------------------------------------------------------+
|                    CONSTELLATION EMBED ARCHITECTURE                     |
+-------------------------------------------------------------------------+
| [ HOST SINGLE-PAGE APPLICATION (REACT / ANGULAR / VUE / HTML5) ]        |
|                                                                         |
|   <pega-embed                                                           |
|     caseTypeID="FSG-Banking-Work-Loan"                                  |
|     appAlias="loans"                                                    |
|     pegaServerUrl="https://pega.enterprise.com"                         |
|     authConfig="{authService: 'oauth2', clientId: '... '}">            |
|   </pega-embed>                                                         |
+-------------------------------------------------------------------------+
          │                                            │                   
          │ Headless RESTful JSON                      │ Modern Token      
          │ via DX API v2                              │ Exchange (PKCE)   
          ▼                                            ▼                   
+----------------------------------+     +--------------------------------+
| DIGITAL EXPERIENCE API (DX API)  |     | OAUTH 2.0 AUTHORIZATION SERVER |
| - UI Metadata & Raw Data Payload |     | - Zero Third-Party Cookies     |
| - Lightweight, Stateless REST    |     | - JWT Bearer Tokens            |
+----------------------------------+     +--------------------------------+

The <pega-embed> Web Component

Constellation Embed is built on the standardized W3C Web Components specification:

• It exposes a custom HTML element: <pega-embed>.
• Frontend developers import the lightweight Constellation Embed JavaScript module into their modern web project. The component can be placed anywhere in a React JSX template, Angular component, or static HTML file.
• Shadow DOM & Styling Consistency: Unlike legacy mashups that clash with external stylesheets, <pega-embed> encapsulates its internal markup within the Shadow DOM or inherits the parent portal's CSS design tokens, ensuring cohesive typography, colors, and responsive reflow.

Digital Experience API v2 (DX API v2)

Constellation Embed communicates with the Pega Platform strictly headlessly via the Digital Experience API (DX API v2):

• The browser does not receive server-rendered HTML markup fragments.
• DX API v2 delivers lightweight JSON payloads that separate UI Metadata (which fields to render, layout slot definitions, display modes) from Transactional Data (raw case property values).
• Network payloads are drastically smaller, eliminating the latency and DOM flickering characteristic of traditional iframe refreshes.

Modern Authentication: OAuth 2.0 & PKCE

Modern web browsers (such as Apple Safari with Intelligent Tracking Prevention and Google Chrome) aggressively restrict or block third-party cookies inside iframes, which frequently breaks traditional mashup sessions.

• Constellation Embed eliminates reliance on third-party session cookies by utilizing OAuth 2.0 Authorization Code Grant with Proof Key for Code Exchange (PKCE) or JSON Web Token (JWT) bearer exchange.
• The host application negotiates an access token directly with the enterprise identity provider and attaches the bearer token to outbound DX API requests, establishing a secure, stateless session.

---

4. Conversational Digital Channels: Email & Chatbots

Beyond visual browser embedding, Pega's multichannel framework natively supports automated conversational channels that transform unstructured customer communications into structured case workflows.

The Pega Email Channel (Email Bot)

Enterprise customer service centers receive millions of emails daily. The Pega Email Channel integrates natural language processing with automated case lifecycle execution:

1. Inbound Email Listener: Monitors dedicated enterprise mailboxes via IMAP, POP3, or Microsoft Graph API.
2. Text Analytics & Natural Language Processing (NLP): When an email arrives, Pega's integrated text analyzer evaluates the message body and attachments:
   • Intent Detection: Determines the customer's goal (e.g., Address Change, Dispute Transaction, Request Policy Cancellation).
   • Entity Extraction: Identifies and parses critical business data entities (e.g., Account Number, Customer Name, Monetary Amount, Vehicle VIN).
   • Sentiment Analysis: Flags hostile or distressed customer emails for expedited priority routing.
3. Automated Case Instantiation & Routing: Based on detected intent, the Email Bot automatically creates the corresponding case type, maps extracted entities directly to case properties, attaches incoming email attachments to the case record, and routes the assignment to the appropriate work queue.
4. Contextual Auto-Reply: The system drafts or dispatches an automated, templated email response acknowledging receipt and quoting the newly created Case ID.

Pega Virtual Assistant (Chatbot & Messaging)

Pega Virtual Assistant extends the multichannel engine to conversational chat interfaces—including web-based chat widgets and third-party messaging networks (SMS, WhatsApp, Facebook Messenger, Microsoft Teams):

• Conversational Flows: Guides customers through structured dialog flows to resolve inquiries or initiate service cases.
• Omnichannel State Preservation: If a customer starts a loan inquiry on a web chatbot, pauses, and later resumes via SMS, Pega preserves the case state.
• Human Escalation: If the chatbot detects high customer frustration or an intent falling below confidence thresholds, it seamlessly transfers the session to a live customer service representative, delivering the complete conversational transcript and pre-populated case context.

---

5. Architectural Comparison Matrix: Integration Paradigms