@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/references/event-patterns.md

@@ -0,0 +1,838 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# Event-Driven Integration Patterns
+
+This document provides detailed implementation patterns for Platform Events and Change Data Capture (CDC) in Salesforce integrations.
+
+> **Parent Document**: [building-sf-integrations/SKILL.md](../SKILL.md)
+> **Related**: [callout-patterns.md](./callout-patterns.md)
+
+---
+
+## Table of Contents
+
+- [Platform Events](#platform-events)
+  - [Platform Event Definition](#platform-event-definition)
+  - [Event Publisher](#event-publisher)
+  - [Event Subscriber Trigger](#event-subscriber-trigger)
+  - [High-Volume vs Standard-Volume Events](#high-volume-vs-standard-volume-events)
+- [Change Data Capture (CDC)](#change-data-capture-cdc)
+  - [CDC Enablement](#cdc-enablement)
+  - [CDC Subscriber Trigger](#cdc-subscriber-trigger)
+  - [CDC Handler Service](#cdc-handler-service)
+  - [Field-Specific Change Detection](#field-specific-change-detection)
+
+---
+
+## Platform Events
+
+Platform Events enable asynchronous, event-driven communication between applications. They provide a publish-subscribe model where publishers fire events and subscribers listen for them.
+
+### Platform Event Definition
+
+**Use Case**: Asynchronous, event-driven communication
+
+**Template**: `assets/platform-events/platform-event-definition.object-meta.xml`
+
+#### Standard Volume Event
+
+Best for moderate event volumes (~2,000 events/hour):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <deploymentStatus>Deployed</deploymentStatus>
+    <eventType>StandardVolume</eventType>
+    <label>{{EventLabel}}</label>
+    <pluralLabel>{{EventPluralLabel}}</pluralLabel>
+    <publishBehavior>PublishAfterCommit</publishBehavior>
+
+    <fields>
+        <fullName>{{FieldName}}__c</fullName>
+        <label>{{FieldLabel}}</label>
+        <type>Text</type>
+        <length>255</length>
+    </fields>
+
+    <fields>
+        <fullName>RecordId__c</fullName>
+        <label>Record ID</label>
+        <type>Text</type>
+        <length>18</length>
+        <description>Salesforce record ID related to this event</description>
+    </fields>
+
+    <fields>
+        <fullName>Timestamp__c</fullName>
+        <label>Timestamp</label>
+        <type>DateTime</type>
+        <description>When the event was triggered</description>
+    </fields>
+</CustomObject>
+```
+
+#### High-Volume Event
+
+Best for millions of events per day:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <deploymentStatus>Deployed</deploymentStatus>
+    <eventType>HighVolume</eventType>
+    <label>{{EventLabel}}</label>
+    <pluralLabel>{{EventPluralLabel}}</pluralLabel>
+    <publishBehavior>PublishAfterCommit</publishBehavior>
+
+    <fields>
+        <fullName>{{FieldName}}__c</fullName>
+        <label>{{FieldLabel}}</label>
+        <type>Text</type>
+        <length>255</length>
+    </fields>
+</CustomObject>
+```
+
+#### Key Configuration Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| **eventType** | `StandardVolume`, `HighVolume` | Event throughput capacity |
+| **publishBehavior** | `PublishAfterCommit`, `PublishImmediately` | When events are published |
+| **deploymentStatus** | `Deployed`, `InDevelopment` | Deployment status |
+
+**PublishBehavior Details**:
+- `PublishAfterCommit`: Event published only if transaction commits (recommended)
+- `PublishImmediately`: Event published immediately, even if transaction rolls back
+
+---
+
+### Event Publisher
+
+**Template**: `assets/platform-events/event-publisher.cls`
+
+#### Bulk Event Publisher
+
+```apex
+public with sharing class {{EventName}}Publisher {
+
+    public static void publishEvents(List<{{EventName}}__e> events) {
+        if (events == null || events.isEmpty()) {
+            return;
+        }
+
+        List<Database.SaveResult> results = EventBus.publish(events);
+
+        for (Integer i = 0; i < results.size(); i++) {
+            Database.SaveResult sr = results[i];
+            if (!sr.isSuccess()) {
+                for (Database.Error err : sr.getErrors()) {
+                    System.debug(LoggingLevel.ERROR,
+                        'Event publish error: ' + err.getStatusCode() + ' - ' + err.getMessage());
+                }
+            }
+        }
+    }
+
+    public static void publishSingleEvent(Map<String, Object> eventData) {
+        {{EventName}}__e event = new {{EventName}}__e();
+
+        // Map fields from eventData
+        event.{{FieldName}}__c = (String) eventData.get('{{fieldKey}}');
+        event.RecordId__c = (String) eventData.get('recordId');
+        event.Timestamp__c = DateTime.now();
+
+        Database.SaveResult sr = EventBus.publish(event);
+        if (!sr.isSuccess()) {
+            throw new EventPublishException('Failed to publish event: ' + sr.getErrors());
+        }
+    }
+
+    public class EventPublishException extends Exception {}
+}
+```
+
+#### Usage Examples
+
+**Single Event**:
+```apex
+Map<String, Object> eventData = new Map<String, Object>{
+    'recordId' => '001xx000003DXXXAAA',
+    'status' => 'Completed',
+    'amount' => 1000.00
+};
+OrderStatusPublisher.publishSingleEvent(eventData);
+```
+
+**Bulk Events**:
+```apex
+List<Order_Status__e> events = new List<Order_Status__e>();
+
+for (Order order : orders) {
+    Order_Status__e event = new Order_Status__e();
+    event.RecordId__c = order.Id;
+    event.Status__c = order.Status;
+    event.Timestamp__c = DateTime.now();
+    events.add(event);
+}
+
+OrderStatusPublisher.publishEvents(events);
+```
+
+#### Best Practices for Publishing
+
+1. **Batch Events**: Publish up to 2,000 events per transaction (governor limit)
+2. **Error Handling**: Always check `Database.SaveResult` for failures
+3. **Transaction Context**: Use `PublishAfterCommit` to ensure events only fire on successful transactions
+4. **Field Population**: Populate all required fields before publishing
+5. **Logging**: Log failed event publishes for debugging
+
+---
+
+### Event Subscriber Trigger
+
+**Template**: `assets/platform-events/event-subscriber-trigger.trigger`
+
+#### Standard Volume Subscriber
+
+```apex
+trigger {{EventName}}Subscriber on {{EventName}}__e (after insert) {
+    // Get replay ID for resumption
+    String lastReplayId = '';
+
+    for ({{EventName}}__e event : Trigger.new) {
+        // Store replay ID for potential resume
+        lastReplayId = event.ReplayId;
+
+        try {
+            // Process event
+            {{EventName}}Handler.processEvent(event);
+        } catch (Exception e) {
+            // Log error but don't throw - allow other events to process
+            System.debug(LoggingLevel.ERROR,
+                'Event processing error: ' + e.getMessage() +
+                ' ReplayId: ' + event.ReplayId);
+        }
+    }
+}
+```
+
+#### High-Volume Subscriber (with Resume Checkpoint)
+
+```apex
+trigger {{EventName}}Subscriber on {{EventName}}__e (after insert) {
+    String lastReplayId = '';
+
+    for ({{EventName}}__e event : Trigger.new) {
+        lastReplayId = event.ReplayId;
+
+        try {
+            {{EventName}}Handler.processEvent(event);
+        } catch (Exception e) {
+            System.debug(LoggingLevel.ERROR,
+                'Event processing error: ' + e.getMessage() +
+                ' ReplayId: ' + event.ReplayId);
+        }
+    }
+
+    // Set resume checkpoint for high-volume events
+    // Allows resuming from this point if subscriber fails
+    EventBus.TriggerContext.currentContext().setResumeCheckpoint(lastReplayId);
+}
+```
+
+#### Event Handler Class
+
+```apex
+public with sharing class {{EventName}}Handler {
+
+    public static void processEvent({{EventName}}__e event) {
+        // Extract event data
+        String recordId = event.RecordId__c;
+        String status = event.Status__c;
+        DateTime timestamp = event.Timestamp__c;
+
+        System.debug('Processing event - RecordId: ' + recordId +
+                     ', Status: ' + status +
+                     ', ReplayId: ' + event.ReplayId);
+
+        // Business logic
+        updateRelatedRecords(recordId, status);
+        syncToExternalSystem(recordId, status);
+    }
+
+    private static void updateRelatedRecords(String recordId, String status) {
+        // Update related records based on event
+        List<Task> tasks = [
+            SELECT Id, Status
+            FROM Task
+            WHERE WhatId = :recordId
+            WITH USER_MODE
+        ];
+
+        for (Task t : tasks) {
+            t.Status = status;
+        }
+
+        update as user tasks;
+    }
+
+    private static void syncToExternalSystem(String recordId, String status) {
+        // Queue async callout
+        Map<String, Object> payload = new Map<String, Object>{
+            'recordId' => recordId,
+            'status' => status
+        };
+        System.enqueueJob(new ExternalSyncQueueable(payload));
+    }
+}
+```
+
+---
+
+<a id="high-volume-vs-standard-volume-events"></a>
+
+### High-Volume vs Standard-Volume Events
+
+| Feature | Standard-Volume | High-Volume |
+|---------|----------------|-------------|
+| **Throughput** | ~2,000 events/hour | Millions/day |
+| **Delivery** | Exactly-once | At-least-once (may deliver duplicates) |
+| **Retention** | 3 days (72 hours) | 24 hours |
+| **Replay** | ReplayId from last 3 days | ReplayId from last 24 hours |
+| **Use Case** | Low-volume integrations, workflows | IoT, real-time analytics, high-traffic |
+| **Cost** | Included in platform | Additional licensing |
+
+#### When to Use High-Volume Events
+
+- **IoT Data**: Sensor data, device telemetry
+- **Real-Time Analytics**: Clickstream, user behavior tracking
+- **High-Traffic Systems**: E-commerce order processing, stock updates
+- **Event Sourcing**: Append-only event logs
+
+#### When to Use Standard-Volume Events
+
+- **Business Workflows**: Order status updates, approval processes
+- **Integration Events**: Sync to external CRM, ERP systems
+- **Notifications**: Email triggers, Slack notifications
+- **Audit Trails**: Record-level change notifications
+
+---
+
+## Change Data Capture (CDC)
+
+Change Data Capture publishes change events whenever records are created, updated, deleted, or undeleted in Salesforce. CDC events are published automatically—no custom code needed.
+
+### CDC Enablement
+
+#### Enable via Setup UI
+
+1. Navigate to **Setup** → **Integrations** → **Change Data Capture**
+2. Select objects to enable (Standard or Custom)
+3. Save
+
+#### Enable via Metadata API
+
+**File**: `force-app/main/default/changeDataCaptures/AccountChangeEvent.cdc-meta.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ChangeDataCapture xmlns="http://soap.sforce.com/2006/04/metadata">
+    <entityName>Account</entityName>
+    <isEnabled>true</isEnabled>
+</ChangeDataCapture>
+```
+
+#### Channel Naming Convention
+
+CDC channels follow the pattern: `{{ObjectAPIName}}ChangeEvent`
+
+**Examples**:
+- `AccountChangeEvent` (Standard object)
+- `Order__ChangeEvent` (Custom object)
+- `OpportunityChangeEvent`
+- `Contact_Request__ChangeEvent`
+
+---
+
+### CDC Subscriber Trigger
+
+**Template**: `assets/cdc/cdc-subscriber-trigger.trigger`
+
+#### Basic CDC Subscriber
+
+```apex
+trigger {{ObjectName}}CDCSubscriber on {{ObjectName}}ChangeEvent (after insert) {
+
+    for ({{ObjectName}}ChangeEvent event : Trigger.new) {
+        // Get change event header
+        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
+
+        String changeType = header.getChangeType();
+        List<String> changedFields = header.getChangedFields();
+        String recordId = header.getRecordIds()[0]; // First record ID
+
+        System.debug('CDC Event - Type: ' + changeType +
+                     ', RecordId: ' + recordId +
+                     ', Changed Fields: ' + changedFields);
+
+        // Route based on change type
+        switch on changeType {
+            when 'CREATE' {
+                // Handle new record
+                {{ObjectName}}CDCHandler.handleCreate(event);
+            }
+            when 'UPDATE' {
+                // Handle update
+                {{ObjectName}}CDCHandler.handleUpdate(event, changedFields);
+            }
+            when 'DELETE' {
+                // Handle delete
+                {{ObjectName}}CDCHandler.handleDelete(recordId);
+            }
+            when 'UNDELETE' {
+                // Handle undelete
+                {{ObjectName}}CDCHandler.handleUndelete(event);
+            }
+        }
+    }
+}
+```
+
+#### ChangeEventHeader Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `getChangeType()` | String | CREATE, UPDATE, DELETE, UNDELETE |
+| `getRecordIds()` | List<String> | Record IDs affected (usually 1, up to 5 for related changes) |
+| `getChangedFields()` | List<String> | Field API names that changed (UPDATE only) |
+| `getCommitTimestamp()` | Long | Transaction commit timestamp |
+| `getCommitUser()` | String | User ID who made the change |
+| `getCommitNumber()` | Long | Monotonically increasing commit number |
+| `getEntityName()` | String | Object API name |
+
+---
+
+### CDC Handler Service
+
+**Template**: `assets/cdc/cdc-handler.cls`
+
+```apex
+public with sharing class {{ObjectName}}CDCHandler {
+
+    public static void handleCreate({{ObjectName}}ChangeEvent event) {
+        // Sync to external system on create
+        Map<String, Object> payload = buildPayload(event);
+        System.enqueueJob(new ExternalSystemSyncQueueable(payload, 'CREATE'));
+    }
+
+    public static void handleUpdate({{ObjectName}}ChangeEvent event, List<String> changedFields) {
+        // Only sync if relevant fields changed
+        Set<String> fieldsToWatch = new Set<String>{'Name', 'Status__c', 'Amount__c'};
+
+        Boolean relevantChange = false;
+        for (String field : changedFields) {
+            if (fieldsToWatch.contains(field)) {
+                relevantChange = true;
+                break;
+            }
+        }
+
+        if (relevantChange) {
+            Map<String, Object> payload = buildPayload(event);
+            payload.put('changedFields', changedFields);
+            System.enqueueJob(new ExternalSystemSyncQueueable(payload, 'UPDATE'));
+        }
+    }
+
+    public static void handleDelete(String recordId) {
+        Map<String, Object> payload = new Map<String, Object>{'recordId' => recordId};
+        System.enqueueJob(new ExternalSystemSyncQueueable(payload, 'DELETE'));
+    }
+
+    public static void handleUndelete({{ObjectName}}ChangeEvent event) {
+        handleCreate(event); // Treat undelete like create
+    }
+
+    private static Map<String, Object> buildPayload({{ObjectName}}ChangeEvent event) {
+        return new Map<String, Object>{
+            'recordId' => event.ChangeEventHeader.getRecordIds()[0],
+            'commitTimestamp' => event.ChangeEventHeader.getCommitTimestamp(),
+            'commitUser' => event.ChangeEventHeader.getCommitUser(),
+            // Add event field values
+            'name' => event.Name,
+            'status' => event.Status__c
+            // Add more fields
+        };
+    }
+}
+```
+
+---
+
+<a id="field-specific-change-detection"></a>
+
+### Field-Specific Change Detection
+
+#### Filtering by Changed Fields
+
+```apex
+public static void handleUpdate(AccountChangeEvent event, List<String> changedFields) {
+    // Only process if billing address changed
+    Set<String> billingFields = new Set<String>{
+        'BillingStreet',
+        'BillingCity',
+        'BillingState',
+        'BillingPostalCode',
+        'BillingCountry'
+    };
+
+    Boolean billingChanged = false;
+    for (String field : changedFields) {
+        if (billingFields.contains(field)) {
+            billingChanged = true;
+            break;
+        }
+    }
+
+    if (billingChanged) {
+        updateShippingPartner(event);
+    }
+}
+```
+
+#### Multi-Field Change Logic
+
+```apex
+public static void handleUpdate(OpportunityChangeEvent event, List<String> changedFields) {
+    Set<String> changedFieldSet = new Set<String>(changedFields);
+
+    // Check if stage AND amount both changed
+    if (changedFieldSet.contains('StageName') && changedFieldSet.contains('Amount')) {
+        // Alert sales ops about significant deal change
+        sendAlert('Deal stage and amount changed', event);
+    }
+
+    // Check if close date moved backward
+    if (changedFieldSet.contains('CloseDate')) {
+        checkCloseDateRegression(event);
+    }
+}
+```
+
+---
+
+## CDC vs Platform Events: When to Use Which
+
+| Use Case | Platform Events | Change Data Capture |
+|----------|----------------|---------------------|
+| **Custom business events** | **Preferred** | Not applicable |
+| **Record change notifications** | Requires custom trigger | **Automatic** (no code) |
+| **External system sync** | Both work | **CDC** (lower maintenance) |
+| **Custom event fields** | Fully customizable | Limited to object fields |
+| **Event filtering** | Filter in publisher code | Filter in subscriber code |
+| **Performance overhead** | Manual event creation | Automatic (minimal overhead) |
+
+### Decision Matrix
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│  WHEN TO USE PLATFORM EVENTS vs CHANGE DATA CAPTURE                   │
+├───────────────────────────────────────────────────────────────────────┤
+│  Use PLATFORM EVENTS when:                                            │
+│  • Custom business event (not tied to record changes)                 │
+│  • Event needs custom fields not on object                            │
+│  • Need to batch/aggregate data before publishing                     │
+│  • Publishing from external system to Salesforce                      │
+│  • Complex event logic (multi-object aggregation)                     │
+│                                                                        │
+│  Use CHANGE DATA CAPTURE when:                                        │
+│  • Syncing record changes to external system                          │
+│  • Audit trail of all record modifications                            │
+│  • Real-time replication to data warehouse                            │
+│  • Event sourcing from Salesforce objects                             │
+│  • Zero-code event publishing required                                │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Advanced Patterns
+
+### Combining CDC with Callouts
+
+```apex
+public with sharing class AccountCDCHandler {
+
+    public static void handleUpdate(AccountChangeEvent event, List<String> changedFields) {
+        // Extract data
+        String recordId = event.ChangeEventHeader.getRecordIds()[0];
+        String accountName = event.Name;
+
+        // Queue async callout to external CRM
+        Map<String, Object> payload = new Map<String, Object>{
+            'salesforceId' => recordId,
+            'name' => accountName,
+            'changedFields' => changedFields,
+            'timestamp' => event.ChangeEventHeader.getCommitTimestamp()
+        };
+
+        System.enqueueJob(new CRMSyncQueueable(payload));
+    }
+}
+```
+
+### Event Replay with Stored ReplayId
+
+```apex
+public with sharing class EventReplayService {
+
+    @future(callout=true)
+    public static void replayFromLastCheckpoint(String eventChannel) {
+        // Get last stored replay ID
+        Event_Checkpoint__c checkpoint = [
+            SELECT ReplayId__c
+            FROM Event_Checkpoint__c
+            WHERE Channel__c = :eventChannel
+            LIMIT 1
+        ];
+
+        if (checkpoint != null) {
+            // Use stored replay ID to resume from last successful event
+            // Note: Replay is typically done via API/streaming API, not Apex
+            System.debug('Last replay ID: ' + checkpoint.ReplayId__c);
+        }
+    }
+
+    public static void storeCheckpoint(String channel, String replayId) {
+        Event_Checkpoint__c checkpoint = new Event_Checkpoint__c(
+            Channel__c = channel,
+            ReplayId__c = replayId,
+            Last_Updated__c = DateTime.now()
+        );
+        upsert checkpoint Channel__c;
+    }
+}
+```
+
+### Error Handling with Dead Letter Queue
+
+```apex
+trigger OrderEventSubscriber on Order_Status__e (after insert) {
+    for (Order_Status__e event : Trigger.new) {
+        try {
+            OrderEventHandler.processEvent(event);
+        } catch (Exception e) {
+            // Log to dead letter queue for manual review
+            Event_Error_Log__c errorLog = new Event_Error_Log__c(
+                Event_Type__c = 'Order_Status__e',
+                Replay_Id__c = event.ReplayId,
+                Error_Message__c = e.getMessage(),
+                Event_Payload__c = JSON.serialize(event),
+                Occurred_At__c = DateTime.now()
+            );
+            insert as user errorLog;
+        }
+    }
+}
+```
+
+---
+
+## Best Practices
+
+### Platform Events
+
+1. **Batch Publishing**: Publish events in batches (up to 2,000 per transaction)
+2. **Idempotent Subscribers**: Design subscribers to handle duplicate events (especially for high-volume)
+3. **ReplayId Tracking**: Store ReplayIds for resume capability
+4. **Error Isolation**: Catch exceptions in subscriber loops to process remaining events
+5. **Resume Checkpoints**: Use `setResumeCheckpoint()` for high-volume events
+
+### Change Data Capture
+
+1. **Field Filtering**: Only process relevant field changes to reduce processing overhead
+2. **Async Processing**: Use Queueable/Future for callouts or long-running operations
+3. **ChangeType Routing**: Use switch statements for different change types
+4. **RecordIds Array**: Handle multiple RecordIds (CDC can batch related changes)
+5. **Commit Metadata**: Use `getCommitTimestamp()` and `getCommitUser()` for audit trails
+
+---
+
+## Governor Limits
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Platform Events published/transaction | 2,000 | Both Standard and High-Volume |
+| Platform Event delivery | Asynchronous | Delivered to subscribers after commit |
+| CDC events/hour (per object) | 250,000 | Auto-throttled if exceeded |
+| Event message size | 1 MB | Total size of all fields |
+| Event retention (Standard) | 3 days | ReplayId available for 72 hours |
+| Event retention (High-Volume) | 24 hours | ReplayId available for 24 hours |
+
+---
+
+## Testing Event-Driven Integrations
+
+### Platform Event Test
+
+```apex
+@isTest
+private class OrderEventTest {
+
+    @isTest
+    static void testEventPublish() {
+        Test.startTest();
+
+        Order_Status__e event = new Order_Status__e(
+            RecordId__c = '006xx000000XXXAAA',
+            Status__c = 'Completed'
+        );
+        Database.SaveResult sr = EventBus.publish(event);
+
+        Test.stopTest();
+
+        System.assert(sr.isSuccess(), 'Event should publish successfully');
+    }
+
+    @isTest
+    static void testEventSubscriber() {
+        // Subscriber triggers execute synchronously in tests
+        Test.startTest();
+
+        Order_Status__e event = new Order_Status__e(
+            RecordId__c = '006xx000000XXXAAA',
+            Status__c = 'Completed'
+        );
+        EventBus.publish(event);
+
+        Test.stopTest();
+
+        // Verify subscriber logic executed
+        // (check that handler updated related records)
+    }
+}
+```
+
+### CDC Test
+
+```apex
+@isTest
+private class AccountCDCTest {
+
+    @isTest
+    static void testAccountUpdate() {
+        Account acc = new Account(Name = 'Test Account');
+        insert acc;
+
+        Test.startTest();
+
+        acc.BillingCity = 'San Francisco';
+        update acc;
+
+        Test.stopTest();
+
+        // CDC events don't fire in test context
+        // Must test handler methods directly
+        AccountChangeEvent mockEvent = new AccountChangeEvent();
+        // Note: Can't instantiate ChangeEvent in Apex
+        // Test handler logic with mock data instead
+    }
+}
+```
+
+---
+
+## Pub/Sub API (Recommended for External Consumers)
+
+The Pub/Sub API is the **recommended mechanism** for external systems subscribing to Platform Events and CDC events. It replaces the legacy Streaming API (CometD).
+
+### Why Pub/Sub API
+
+| Feature | Pub/Sub API | Legacy Streaming API |
+|---------|-------------|---------------------|
+| **Protocol** | gRPC (binary, high performance) | CometD (long-polling, HTTP overhead) |
+| **Authentication** | OAuth 2.0 | Session-based |
+| **Event Types** | Platform Events, CDC, Custom Channels | PushTopic, Generic Events |
+| **Status** | **Current** | **Deprecated — no new investments** |
+
+### Subscription Modes
+
+- **Subscribe**: Stream events from a given replay ID forward
+- **PublishStream**: Bi-directional — publish events via gRPC
+- **ManagedSubscribe**: Salesforce manages replay state (simplest)
+
+### LWC Internal Subscription
+
+For Lightning Web Components, use the `empApi` module:
+
+```javascript
+import { subscribe, unsubscribe, onError } from 'lightning/empApi';
+
+connectedCallback() {
+    subscribe('/event/Order_Status__e', -1, (response) => {
+        this.handleEvent(response.data.payload);
+    }).then((sub) => { this.subscription = sub; });
+}
+
+disconnectedCallback() {
+    unsubscribe(this.subscription);
+}
+```
+
+> **Note**: `empApi` uses CometD internally but is the supported LWC API. For external consumers, always use the gRPC-based Pub/Sub API.
+
+---
+
+## Platform Event Anti-Patterns
+
+### 1. Publishing from Trigger on Same Event Object → Infinite Loop
+
+```apex
+// ❌ WRONG: Trigger on Order_Status__e publishes Order_Status__e
+trigger OrderStatusSubscriber on Order_Status__e (after insert) {
+    for (Order_Status__e event : Trigger.new) {
+        // This creates an infinite loop!
+        EventBus.publish(new Order_Status__e(Status__c = 'Processed'));
+    }
+}
+```
+
+**Fix**: Never publish the same event type from its own subscriber trigger. Use a different event type or update a record instead.
+
+### 2. PublishImmediately When Data Integrity Matters
+
+```apex
+// ❌ WRONG: Event fires even if the transaction rolls back
+Order_Status__e event = new Order_Status__e();
+event.Status__c = 'Completed';
+// publishBehavior = PublishImmediately in event definition
+EventBus.publish(event);
+
+// If subsequent DML fails, the event was already published
+// External system thinks order is "Completed" but it's not
+```
+
+**Fix**: Use `PublishAfterCommit` (the default) when the event represents a state change that depends on the transaction succeeding.
+
+### 3. Using Platform Events for Synchronous-Style Flow Orchestration
+
+```
+// ❌ WRONG: Using events to simulate synchronous request/response
+Flow A → Publish "Request" Event → Subscriber triggers Flow B → Publish "Response" Event → ???
+```
+
+**Fix**: Platform Events are asynchronous and unordered. For synchronous orchestration, use Subflows, @InvocableMethod, or direct Apex calls. Events are for decoupled, fire-and-forget communication.
+
+### 4. Oversized Event Payloads
+
+> **1 MB message size limit.** Balance payload size — smaller = faster delivery, larger = fewer API calls. Include record IDs and essential context; let consumers query Salesforce for full records if needed.
+
+---
+
+## Related Resources
+
+- [Callout Patterns](./callout-patterns.md) - REST and SOAP callout implementations
+- [Event-Driven Architecture Guide](./event-driven-architecture-guide.md) - EDA patterns, Pub/Sub API deep dive, monitoring
+- [Main Skill Documentation](../SKILL.md) - building-sf-integrations overview
+- [Platform Event Templates](../assets/platform-events/) - Event definitions and triggers
+- [CDC Templates](../assets/cdc/) - Change Data Capture triggers