@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/generating-lwc-components/references/async-notification-patterns.md

@@ -0,0 +1,661 @@
+<!-- Parent: generating-lwc-components/SKILL.md -->
+# Async Notification Patterns in LWC
+
+This guide covers real-time notification patterns for Lightning Web Components using Platform Events, Change Data Capture, and the Emp API.
+
+---
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    ASYNC NOTIFICATION ARCHITECTURE                       │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   ┌──────────────┐        Platform Events        ┌──────────────┐       │
+│   │    Apex      │ ─────────────────────────────▶│     LWC      │       │
+│   │  Queueable   │    /event/My_Event__e         │  empApi      │       │
+│   └──────────────┘                               └──────────────┘       │
+│                                                                          │
+│   ┌──────────────┐        Change Data Capture    ┌──────────────┐       │
+│   │    DML       │ ─────────────────────────────▶│     LWC      │       │
+│   │  Operation   │    /data/AccountChangeEvent   │  empApi      │       │
+│   └──────────────┘                               └──────────────┘       │
+│                                                                          │
+│   Use Cases:                                                             │
+│   • Queueable/Batch job completion notification                          │
+│   • Real-time record updates across users                                │
+│   • External system webhook processing notification                      │
+│   • Background AI generation completion                                  │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Emp API Basics
+
+The `lightning/empApi` module enables LWC to subscribe to Streaming API channels.
+
+### Import and Setup
+
+```javascript
+import { LightningElement } from 'lwc';
+import { subscribe, unsubscribe, onError, setDebugFlag } from 'lightning/empApi';
+
+export default class NotificationListener extends LightningElement {
+    subscription = null;
+    channelName = '/event/Job_Complete__e';
+
+    connectedCallback() {
+        // Enable debug logging (development only)
+        setDebugFlag(true);
+
+        // Register global error handler
+        this.registerErrorListener();
+
+        // Subscribe to channel
+        this.handleSubscribe();
+    }
+
+    disconnectedCallback() {
+        // CRITICAL: Always unsubscribe to prevent memory leaks
+        this.handleUnsubscribe();
+    }
+}
+```
+
+### Subscribe to Platform Events
+
+```javascript
+async handleSubscribe() {
+    // Callback invoked when event received
+    const messageCallback = (response) => {
+        console.log('Event received:', JSON.stringify(response));
+        this.handleEvent(response.data.payload);
+    };
+
+    try {
+        // Subscribe and store reference
+        this.subscription = await subscribe(
+            this.channelName,
+            -1,  // -1 = all new events, -2 = replay last 24h
+            messageCallback
+        );
+        console.log('Subscribed to:', JSON.stringify(this.subscription));
+    } catch (error) {
+        console.error('Subscribe error:', error);
+    }
+}
+
+handleUnsubscribe() {
+    if (this.subscription) {
+        unsubscribe(this.subscription, (response) => {
+            console.log('Unsubscribed:', JSON.stringify(response));
+        });
+    }
+}
+
+registerErrorListener() {
+    onError((error) => {
+        console.error('Streaming API error:', JSON.stringify(error));
+        // Attempt reconnection after delay
+        setTimeout(() => this.handleSubscribe(), 5000);
+    });
+}
+```
+
+---
+
+## Pattern 1: Queueable Job Completion
+
+Notify users when async Apex processing completes.
+
+### Platform Event Definition
+
+```xml
+<!-- force-app/main/default/objects/Job_Complete__e/Job_Complete__e.object-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <deploymentStatus>Deployed</deploymentStatus>
+    <eventType>StandardVolume</eventType>
+    <label>Job Complete</label>
+    <pluralLabel>Job Complete Events</pluralLabel>
+    <publishBehavior>PublishAfterCommit</publishBehavior>
+    <fields>
+        <fullName>Job_Id__c</fullName>
+        <label>Job ID</label>
+        <type>Text</type>
+        <length>50</length>
+    </fields>
+    <fields>
+        <fullName>User_Id__c</fullName>
+        <label>User ID</label>
+        <type>Text</type>
+        <length>18</length>
+    </fields>
+    <fields>
+        <fullName>Status__c</fullName>
+        <label>Status</label>
+        <type>Text</type>
+        <length>20</length>
+    </fields>
+    <fields>
+        <fullName>Message__c</fullName>
+        <label>Message</label>
+        <type>TextArea</type>
+    </fields>
+    <fields>
+        <fullName>Record_Id__c</fullName>
+        <label>Record ID</label>
+        <type>Text</type>
+        <length>18</length>
+    </fields>
+</CustomObject>
+```
+
+### Apex Queueable with Event Publishing
+
+```apex
+public class AIGenerationQueueable implements Queueable, Database.AllowsCallouts {
+
+    private Id recordId;
+    private Id userId;
+
+    public AIGenerationQueueable(Id recordId, Id userId) {
+        this.recordId = recordId;
+        this.userId = userId;
+    }
+
+    public void execute(QueueableContext context) {
+        String status;
+        String message;
+
+        try {
+            // Perform async work (AI generation, callout, etc.)
+            performGeneration();
+            status = 'SUCCESS';
+            message = 'AI content generated successfully';
+        } catch (Exception e) {
+            status = 'ERROR';
+            message = e.getMessage();
+        }
+
+        // Publish completion event
+        publishCompletionEvent(status, message);
+    }
+
+    private void publishCompletionEvent(String status, String message) {
+        Job_Complete__e event = new Job_Complete__e();
+        event.Job_Id__c = 'AI_GEN_' + recordId;
+        event.User_Id__c = userId;
+        event.Status__c = status;
+        event.Message__c = message;
+        event.Record_Id__c = recordId;
+
+        Database.SaveResult result = EventBus.publish(event);
+        if (!result.isSuccess()) {
+            System.debug('Event publish failed: ' + result.getErrors());
+        }
+    }
+
+    private void performGeneration() {
+        // AI generation logic...
+    }
+}
+```
+
+### LWC Listener Component
+
+```javascript
+// jobCompletionListener.js
+import { LightningElement, api } from 'lwc';
+import { subscribe, unsubscribe, onError } from 'lightning/empApi';
+import { ShowToastEvent } from 'lightning/platformShowToastEvent';
+import { refreshApex } from '@salesforce/apex';
+import userId from '@salesforce/user/Id';
+
+export default class JobCompletionListener extends LightningElement {
+    @api recordId;
+
+    subscription = null;
+    channelName = '/event/Job_Complete__e';
+
+    // Reference to wired data for refresh
+    wiredResult;
+
+    connectedCallback() {
+        this.registerErrorListener();
+        this.subscribeToChannel();
+    }
+
+    disconnectedCallback() {
+        this.unsubscribeFromChannel();
+    }
+
+    async subscribeToChannel() {
+        if (this.subscription) return;
+
+        try {
+            this.subscription = await subscribe(
+                this.channelName,
+                -1,
+                (message) => this.handleMessage(message)
+            );
+        } catch (error) {
+            console.error('Subscription error:', error);
+        }
+    }
+
+    unsubscribeFromChannel() {
+        if (this.subscription) {
+            unsubscribe(this.subscription);
+            this.subscription = null;
+        }
+    }
+
+    handleMessage(message) {
+        const payload = message.data.payload;
+
+        // Filter: Only process events for current user and record
+        if (payload.User_Id__c !== userId) return;
+        if (payload.Record_Id__c !== this.recordId) return;
+
+        // Show toast notification
+        const variant = payload.Status__c === 'SUCCESS' ? 'success' : 'error';
+        this.dispatchEvent(new ShowToastEvent({
+            title: payload.Status__c === 'SUCCESS' ? 'Complete' : 'Error',
+            message: payload.Message__c,
+            variant: variant
+        }));
+
+        // Refresh data if successful
+        if (payload.Status__c === 'SUCCESS' && this.wiredResult) {
+            refreshApex(this.wiredResult);
+        }
+
+        // Dispatch custom event for parent components
+        this.dispatchEvent(new CustomEvent('jobcomplete', {
+            detail: {
+                jobId: payload.Job_Id__c,
+                status: payload.Status__c,
+                message: payload.Message__c
+            }
+        }));
+    }
+
+    registerErrorListener() {
+        onError((error) => {
+            console.error('EmpApi error:', JSON.stringify(error));
+            // Reconnect after delay
+            this.subscription = null;
+            setTimeout(() => this.subscribeToChannel(), 3000);
+        });
+    }
+}
+```
+
+---
+
+## Pattern 2: Real-Time Record Updates (CDC)
+
+Use Change Data Capture to sync UI when records change.
+
+### Enable CDC for Object
+
+1. Setup → Integrations → Change Data Capture
+2. Select objects to track
+3. Deploy (or enable via metadata)
+
+### CDC Channel Names
+
+| Object Type | Channel Pattern |
+|-------------|-----------------|
+| Standard Object | `/data/AccountChangeEvent` |
+| Custom Object | `/data/My_Object__ChangeEvent` |
+
+### LWC CDC Listener
+
+```javascript
+// recordChangeListener.js
+import { LightningElement, api, wire } from 'lwc';
+import { subscribe, unsubscribe, onError } from 'lightning/empApi';
+import { getRecord, getFieldValue } from 'lightning/uiRecordApi';
+import { refreshApex } from '@salesforce/apex';
+
+const FIELDS = ['Account.Name', 'Account.Industry', 'Account.AnnualRevenue'];
+
+export default class RecordChangeListener extends LightningElement {
+    @api recordId;
+
+    subscription = null;
+    channelName = '/data/AccountChangeEvent';
+
+    @wire(getRecord, { recordId: '$recordId', fields: FIELDS })
+    wiredRecord;
+
+    get accountName() {
+        return getFieldValue(this.wiredRecord.data, 'Account.Name');
+    }
+
+    connectedCallback() {
+        this.registerErrorListener();
+        this.subscribeToChanges();
+    }
+
+    disconnectedCallback() {
+        if (this.subscription) {
+            unsubscribe(this.subscription);
+        }
+    }
+
+    async subscribeToChanges() {
+        try {
+            this.subscription = await subscribe(
+                this.channelName,
+                -1,
+                (message) => this.handleChange(message)
+            );
+        } catch (error) {
+            console.error('CDC subscription error:', error);
+        }
+    }
+
+    handleChange(message) {
+        const payload = message.data.payload;
+        const changeType = payload.ChangeEventHeader.changeType;
+        const recordIds = payload.ChangeEventHeader.recordIds;
+
+        // Only process changes for our record
+        if (!recordIds.includes(this.recordId)) return;
+
+        console.log(`Record ${changeType}:`, payload);
+
+        // Refresh the wire
+        if (this.wiredRecord) {
+            refreshApex(this.wiredRecord);
+        }
+
+        // Notify parent
+        this.dispatchEvent(new CustomEvent('recordchange', {
+            detail: {
+                changeType,
+                changedFields: payload.ChangeEventHeader.changedFields,
+                payload
+            }
+        }));
+    }
+
+    registerErrorListener() {
+        onError((error) => {
+            console.error('CDC error:', error);
+            this.subscription = null;
+            setTimeout(() => this.subscribeToChanges(), 5000);
+        });
+    }
+}
+```
+
+### CDC Payload Structure
+
+```javascript
+{
+    "data": {
+        "schema": "...",
+        "payload": {
+            "ChangeEventHeader": {
+                "entityName": "Account",
+                "recordIds": ["001xx000003ABCDE"],
+                "changeType": "UPDATE",  // CREATE, UPDATE, DELETE, UNDELETE
+                "changedFields": ["Name", "Industry"],
+                "changeOrigin": "com/salesforce/api/soap/58.0",
+                "transactionKey": "...",
+                "sequenceNumber": 1,
+                "commitTimestamp": 1705612800000,
+                "commitUser": "005xx000001AAAAA",
+                "commitNumber": 123456789
+            },
+            // Changed field values
+            "Name": "Updated Account Name",
+            "Industry": "Technology"
+        }
+    }
+}
+```
+
+---
+
+## Pattern 3: Multi-User Collaboration
+
+Notify all users viewing the same record.
+
+```javascript
+// collaborativeEditor.js
+import { LightningElement, api } from 'lwc';
+import { subscribe, unsubscribe, onError } from 'lightning/empApi';
+import userId from '@salesforce/user/Id';
+
+export default class CollaborativeEditor extends LightningElement {
+    @api recordId;
+
+    subscription = null;
+    channelName = '/event/Edit_Activity__e';
+    activeEditors = [];
+
+    connectedCallback() {
+        this.registerErrorListener();
+        this.subscribeToActivity();
+        this.announcePresence();
+    }
+
+    disconnectedCallback() {
+        this.announceExit();
+        this.unsubscribe();
+    }
+
+    async subscribeToActivity() {
+        this.subscription = await subscribe(
+            this.channelName,
+            -1,
+            (message) => this.handleActivity(message)
+        );
+    }
+
+    handleActivity(message) {
+        const { Record_Id__c, User_Id__c, User_Name__c, Action__c } = message.data.payload;
+
+        // Ignore our own events, only track this record
+        if (User_Id__c === userId || Record_Id__c !== this.recordId) return;
+
+        if (Action__c === 'JOINED') {
+            this.addEditor(User_Id__c, User_Name__c);
+        } else if (Action__c === 'LEFT') {
+            this.removeEditor(User_Id__c);
+        } else if (Action__c === 'EDITING') {
+            this.showEditingIndicator(User_Name__c, message.data.payload.Field__c);
+        }
+    }
+
+    addEditor(userId, userName) {
+        if (!this.activeEditors.find(e => e.id === userId)) {
+            this.activeEditors = [...this.activeEditors, { id: userId, name: userName }];
+        }
+    }
+
+    removeEditor(userId) {
+        this.activeEditors = this.activeEditors.filter(e => e.id !== userId);
+    }
+
+    // Call Apex to publish presence event
+    announcePresence() {
+        // publishEditActivity({ recordId: this.recordId, action: 'JOINED' });
+    }
+
+    announceExit() {
+        // publishEditActivity({ recordId: this.recordId, action: 'LEFT' });
+    }
+
+    unsubscribe() {
+        if (this.subscription) {
+            unsubscribe(this.subscription);
+        }
+    }
+
+    registerErrorListener() {
+        onError((error) => {
+            console.error('Collaboration error:', error);
+        });
+    }
+}
+```
+
+---
+
+## Pattern 4: Polling Fallback
+
+When empApi isn't available (Communities, some mobile contexts), use polling.
+
+```javascript
+// pollingFallback.js
+import { LightningElement, api } from 'lwc';
+import checkJobStatus from '@salesforce/apex/JobStatusController.checkJobStatus';
+
+export default class PollingFallback extends LightningElement {
+    @api jobId;
+
+    pollingInterval = null;
+    pollFrequencyMs = 3000;
+    maxAttempts = 60;
+    attemptCount = 0;
+
+    connectedCallback() {
+        this.startPolling();
+    }
+
+    disconnectedCallback() {
+        this.stopPolling();
+    }
+
+    startPolling() {
+        this.pollingInterval = setInterval(() => {
+            this.checkStatus();
+        }, this.pollFrequencyMs);
+    }
+
+    stopPolling() {
+        if (this.pollingInterval) {
+            clearInterval(this.pollingInterval);
+            this.pollingInterval = null;
+        }
+    }
+
+    async checkStatus() {
+        this.attemptCount++;
+
+        if (this.attemptCount >= this.maxAttempts) {
+            this.stopPolling();
+            this.handleTimeout();
+            return;
+        }
+
+        try {
+            const result = await checkJobStatus({ jobId: this.jobId });
+
+            if (result.status === 'COMPLETE' || result.status === 'ERROR') {
+                this.stopPolling();
+                this.handleCompletion(result);
+            }
+        } catch (error) {
+            console.error('Polling error:', error);
+        }
+    }
+
+    handleCompletion(result) {
+        this.dispatchEvent(new CustomEvent('complete', { detail: result }));
+    }
+
+    handleTimeout() {
+        this.dispatchEvent(new CustomEvent('timeout'));
+    }
+}
+```
+
+---
+
+## Replay Options
+
+| Replay ID | Behavior |
+|-----------|----------|
+| `-1` | Only new events (after subscription) |
+| `-2` | All stored events (last 24 hours) + new |
+| Specific ID | Events after that replay ID |
+
+### Storing Replay Position
+
+```javascript
+// For durable subscriptions, store last processed replay ID
+handleMessage(message) {
+    const replayId = message.data.event.replayId;
+
+    // Process message...
+
+    // Store replay ID for recovery
+    this.lastReplayId = replayId;
+    localStorage.setItem('myapp_replay_id', replayId);
+}
+
+connectedCallback() {
+    // Recover from stored position
+    const storedReplayId = localStorage.getItem('myapp_replay_id');
+    const replayFrom = storedReplayId ? parseInt(storedReplayId, 10) : -1;
+
+    this.subscribeFromReplayId(replayFrom);
+}
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+
+| Practice | Reason |
+|----------|--------|
+| Always unsubscribe in `disconnectedCallback` | Prevents memory leaks |
+| Filter events by user/record ID | Reduces unnecessary processing |
+| Register error handler | Enables reconnection on failure |
+| Use `refreshApex` after events | Keeps wire data in sync |
+| Set reasonable replay ID | `-1` for real-time, `-2` for recovery |
+
+### DON'T ❌
+
+| Anti-Pattern | Problem |
+|--------------|---------|
+| Subscribe without unsubscribing | Memory leak, duplicate handlers |
+| Process all events without filtering | Performance impact |
+| Ignore error handler | Silent failures, no reconnection |
+| Mutate wire data directly | Breaks reactivity |
+| Use CDC for high-frequency updates | Rate limits, performance |
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| No events received | Subscription failed silently | Check error handler, verify channel name |
+| Duplicate processing | Component re-mounted | Track subscription state, dedupe by replay ID |
+| Events delayed | High server load | Normal behavior, events are async |
+| "Handshake denied" | Missing permissions | Verify Streaming API access in profile |
+| Events stop after time | Session expired | Handle error event, resubscribe |
+
+---
+
+## Cross-Skill References
+
+| Topic | Resource |
+|-------|----------|
+| Platform Event definition | [building-sf-integrations/references/platform-events-guide.md](../../building-sf-integrations/references/platform-events-guide.md) |
+| Publishing from Apex | [sf-apex/references/best-practices.md](../../sf-apex/references/best-practices.md) |
+| State management | [state-management.md](state-management.md) |
+| Agentforce Models API | [developing-agentforce/references/models-api.md](../../developing-agentforce/references/models-api.md) |