@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/references/cdc-guide.md

@@ -0,0 +1,288 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# Change Data Capture (CDC) Guide
+
+## Overview
+
+Change Data Capture publishes change events for Salesforce records, enabling near real-time data synchronization with external systems.
+
+## How CDC Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  CHANGE DATA CAPTURE FLOW                                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Record Created/Updated/Deleted in Salesforce                │
+│     ↓                                                           │
+│  2. Salesforce generates Change Event                           │
+│     ↓                                                           │
+│  3. Event published to {{Object}}ChangeEvent channel            │
+│     ↓                                                           │
+│  4. Apex Trigger or External Subscriber receives event          │
+│     ↓                                                           │
+│  5. Process event (sync, audit, notify)                         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## CDC vs Platform Events
+
+| Feature | CDC | Platform Events |
+|---------|-----|-----------------|
+| Trigger | Automatic on DML | Manual publish |
+| Schema | Predefined (object fields) | Custom defined |
+| Use Case | Data sync/replication | Custom messaging |
+| Control | Limited | Full control |
+
+## Enabling CDC
+
+### Via Setup
+
+1. Go to **Setup → Integrations → Change Data Capture**
+2. Select objects to enable
+3. Save
+
+### Supported Objects
+
+- Most Standard objects (Account, Contact, Opportunity, etc.)
+- Custom objects
+- Some system objects (User, Group, etc.)
+
+## Event Channel Names
+
+| Object Type | Channel Name |
+|-------------|--------------|
+| Standard | `AccountChangeEvent`, `ContactChangeEvent` |
+| Custom | `My_Object__ChangeEvent` (append ChangeEvent) |
+
+## Change Event Structure
+
+### ChangeEventHeader
+
+```apex
+EventBus.ChangeEventHeader header = event.ChangeEventHeader;
+
+// Available methods
+header.getChangeType();       // CREATE, UPDATE, DELETE, UNDELETE
+header.getChangedFields();    // List of changed field API names
+header.getRecordIds();        // Affected record IDs
+header.getEntityName();       // Object API name
+header.getCommitNumber();     // Transaction sequence
+header.getCommitTimestamp();  // When change occurred
+header.getTransactionKey();   // Unique transaction ID
+```
+
+### Change Types
+
+| Type | Description | Event Contains |
+|------|-------------|----------------|
+| CREATE | New record | All field values |
+| UPDATE | Record modified | Changed field values only |
+| DELETE | Record deleted | Record IDs only |
+| UNDELETE | Restored from bin | All field values |
+| GAP_* | Events missed | Affected record IDs |
+| GAP_OVERFLOW | Too many changes | Entity name |
+
+### Field Values
+
+- **Changed fields**: Contain new values
+- **Unchanged fields**: Null
+- Use `getChangedFields()` to know what changed
+
+## Subscribing to CDC
+
+### Apex Trigger
+
+```apex
+trigger AccountCDC on AccountChangeEvent (after insert) {
+    for (AccountChangeEvent event : Trigger.new) {
+        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
+
+        String changeType = header.getChangeType();
+        List<String> changedFields = header.getChangedFields();
+        List<String> recordIds = header.getRecordIds();
+
+        switch on changeType {
+            when 'CREATE' {
+                // Handle new records
+            }
+            when 'UPDATE' {
+                // Handle updates
+            }
+            when 'DELETE' {
+                // Handle deletions
+            }
+        }
+    }
+
+    // Set checkpoint
+    EventBus.TriggerContext.currentContext().setResumeCheckpoint(
+        Trigger.new[Trigger.new.size()-1].ReplayId
+    );
+}
+```
+
+### External (CometD)
+
+```
+Channel: /data/AccountChangeEvent
+```
+
+## Handling Specific Changes
+
+### Filter by Changed Fields
+
+```apex
+// Only process if important fields changed
+Set<String> importantFields = new Set<String>{'Status__c', 'Amount__c'};
+List<String> changedFields = header.getChangedFields();
+
+Boolean relevant = false;
+for (String field : changedFields) {
+    if (importantFields.contains(field)) {
+        relevant = true;
+        break;
+    }
+}
+
+if (!relevant) return;
+```
+
+### Get New Values
+
+```apex
+// Access field values from event (UPDATE: only changed fields have values)
+if (changedFields.contains('Status__c')) {
+    String newStatus = event.Status__c;
+    // Process status change
+}
+```
+
+## Gap Events
+
+Gap events indicate missed events:
+
+### Types
+
+| Event | Meaning | Action |
+|-------|---------|--------|
+| GAP_CREATE | Missed creates | Query and sync records |
+| GAP_UPDATE | Missed updates | Query current state |
+| GAP_DELETE | Missed deletes | Reconcile with source |
+| GAP_UNDELETE | Missed restores | Query and sync |
+| GAP_OVERFLOW | Too many changes | Full sync required |
+
+### Handling Gaps
+
+```apex
+when 'GAP_CREATE', 'GAP_UPDATE', 'GAP_DELETE', 'GAP_UNDELETE' {
+    // Query current state and sync
+    List<Account> records = [
+        SELECT Id, Name, Status__c
+        FROM Account
+        WHERE Id IN :header.getRecordIds()
+    ];
+    syncToExternalSystem(records);
+}
+when 'GAP_OVERFLOW' {
+    // Trigger full sync batch job
+    Database.executeBatch(new FullSyncBatch());
+}
+```
+
+## Replay and Durability
+
+### Retention
+
+CDC events retained for **3 days** (72 hours).
+
+### Replay ID
+
+Each event has unique ReplayId for tracking:
+
+```apex
+String replayId = event.ReplayId;
+```
+
+### Resume Checkpoint
+
+Critical for durability:
+
+```apex
+// Always set checkpoint at end of trigger
+EventBus.TriggerContext.currentContext().setResumeCheckpoint(lastReplayId);
+```
+
+If trigger fails after checkpoint, processing resumes from that point.
+
+## External Sync Pattern
+
+```apex
+public class AccountCDCHandler {
+
+    public static void syncToExternal(AccountChangeEvent event) {
+        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
+
+        Map<String, Object> payload = new Map<String, Object>{
+            'recordIds' => header.getRecordIds(),
+            'operation' => header.getChangeType(),
+            'timestamp' => header.getCommitTimestamp(),
+            'changedFields' => header.getChangedFields()
+        };
+
+        // Add field values for CREATE/UPDATE
+        if (header.getChangeType() != 'DELETE') {
+            payload.put('name', event.Name);
+            payload.put('accountNumber', event.AccountNumber);
+            // Add relevant fields
+        }
+
+        // Queue async callout
+        System.enqueueJob(new ExternalSyncJob(payload));
+    }
+}
+```
+
+## Best Practices
+
+### DO
+
+1. **Set resume checkpoint** in every trigger
+2. **Filter by relevant fields** to reduce noise
+3. **Handle all change types** including GAPs
+4. **Process idempotently** (events may replay)
+5. **Use async** for external callouts
+6. **Log changes** for debugging
+
+### DON'T
+
+1. **Don't throw exceptions** - catch and log
+2. **Don't ignore GAP events** - they indicate data loss
+3. **Don't assume single record** - batch DML creates multi-record events
+4. **Don't block on external calls** - use Queueable
+
+## Monitoring
+
+### Event Delivery
+
+Check for failures in:
+- Setup → Platform Events → Monitor
+- Debug logs for triggers
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Missing events | No CDC enabled | Enable in Setup |
+| Duplicate processing | No idempotency | Check transactionKey |
+| GAP events | Processing too slow | Optimize trigger, scale out |
+| Timeout | Heavy processing | Move to async |
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Objects per org | 100 |
+| Events per 15 minutes | Varies by edition |
+| Event retention | 3 days (72 hours) |
+| Replay window | 3 days |

package/skills/building-sf-integrations/references/cli-reference.md

@@ -0,0 +1,94 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+
+# CLI Commands & Helper Scripts
+
+## Named Credentials
+
+```bash
+# List Named Credentials
+sf org list metadata --metadata-type NamedCredential --target-org {{alias}}
+
+# Deploy Named Credential
+sf project deploy start --metadata NamedCredential:{{Name}} --target-org {{alias}}
+
+# Retrieve Named Credential
+sf project retrieve start --metadata NamedCredential:{{Name}} --target-org {{alias}}
+```
+
+## External Services
+
+```bash
+# List External Service Registrations
+sf org list metadata --metadata-type ExternalServiceRegistration --target-org {{alias}}
+
+# Deploy External Service
+sf project deploy start --metadata ExternalServiceRegistration:{{Name}} --target-org {{alias}}
+```
+
+## Platform Events
+
+```bash
+# List Platform Events
+sf org list metadata --metadata-type CustomObject --target-org {{alias}} | grep "__e"
+
+# Deploy Platform Event
+sf project deploy start --metadata CustomObject:{{EventName}}__e --target-org {{alias}}
+```
+
+## API Requests (Beta)
+
+```bash
+# REST API request
+sf api request rest /services/data/v66.0/sobjects/Account/describe --target-org {{alias}}
+
+# REST with POST body
+sf api request rest /services/data/v66.0/sobjects/Account --method POST \
+  --body '{"Name":"Test Account"}' --target-org {{alias}}
+
+# GraphQL query
+sf api request graphql --body '{"query":"{ uiapi { query { Account { edges { node { Name { value } } } } } } }"}' --target-org {{alias}}
+```
+
+> **[Beta]** These commands simplify API exploration. For production, use Named Credentials and Apex callouts.
+
+---
+
+## Helper Scripts
+
+building-sf-integrations includes automation scripts to configure credentials without manual UI steps.
+
+### Available Scripts
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `configure-named-credential.sh` | Set API keys via ConnectApi (Enhanced NC) | `./scripts/configure-named-credential.sh <org-alias>` |
+| `set-api-credential.sh` | Store keys in Custom Settings (legacy) | `./scripts/set-api-credential.sh <name> - <org-alias>` |
+
+### Auto-Run Behavior
+
+| File Pattern | Suggested Action |
+|--------------|------------------|
+| `*.namedCredential-meta.xml` | Run `configure-named-credential.sh` |
+| `*.externalCredential-meta.xml` | Run `configure-named-credential.sh` |
+| `*.cspTrustedSite-meta.xml` | Deploy endpoint security |
+
+### Example Workflow
+
+```bash
+# 1. Deploy metadata first
+sf project deploy start --metadata ExternalCredential:WeatherAPI \
+  --metadata NamedCredential:WeatherAPI \
+  --target-org MyOrg
+
+# 2. Run automation script
+./scripts/configure-named-credential.sh MyOrg
+# Enter API key when prompted (secure, hidden input)
+```
+
+### Prerequisites
+
+- **Salesforce CLI v2+**: `sf` command available
+- **Authenticated org**: `sf org login web -a <alias>`
+- **Deployed metadata**: External Credential and Named Credential deployed
+
+See [references/named-credentials-automation.md](../references/named-credentials-automation.md) for complete guide.

package/skills/building-sf-integrations/references/event-driven-architecture-guide.md

@@ -0,0 +1,266 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# Event-Driven Architecture Guide
+
+> **Source**: Salesforce Architect Decision Guides — Event-Driven Architecture, Async Processing
+> **Related**: [event-patterns.md](./event-patterns.md) | [callout-patterns.md](./callout-patterns.md)
+
+---
+
+## Overview
+
+Event-Driven Architecture (EDA) decouples producers from consumers, enabling scalable, resilient integrations. Salesforce supports multiple event mechanisms — choosing the right one depends on volume, latency, and consumer location.
+
+---
+
+## 5 Core EDA Patterns
+
+### Pattern Comparison Matrix
+
+| Pattern | Description | Salesforce Implementation | Best For |
+|---------|-------------|--------------------------|----------|
+| **Pub/Sub** | Publisher emits, multiple subscribers consume | Platform Events + Pub/Sub API | Multi-consumer notifications, cross-system sync |
+| **Fanout** | One event → multiple independent consumers | Platform Events + multiple subscribers | Parallel processing, diverse downstream systems |
+| **Passed Messages** | Event carries data payload for consumer processing | Platform Events with rich fields | External systems needing full context in message |
+| **Streaming** | Continuous data feed for real-time consumers | CDC + Pub/Sub API | Data replication, real-time dashboards |
+| **Queueing** | Ordered, guaranteed-delivery message processing | Platform Events (High-Volume) with checkpoints | Sequential processing, backpressure handling |
+
+### When to Use Each
+
+**Pub/Sub**: Default choice for most event-driven integrations. Works for both internal (Apex triggers) and external (Pub/Sub API) consumers.
+
+**Fanout**: When a single business event (e.g., "Order Placed") needs to notify billing, shipping, analytics, and notifications simultaneously.
+
+**Passed Messages**: When the consumer needs all context in the event itself (no callback to Salesforce). Keep payloads lean — 1 MB limit.
+
+**Streaming**: For data replication to warehouses or lakes. CDC + Pub/Sub API replaces legacy Streaming API.
+
+**Queueing**: When processing order matters and you need backpressure handling. Use High-Volume Platform Events with resume checkpoints.
+
+---
+
+## Pub/Sub API (Recommended External Subscription)
+
+The Pub/Sub API is the **recommended mechanism for external consumers** subscribing to Platform Events and CDC events. It replaces the legacy Streaming API (CometD).
+
+### Key Characteristics
+
+| Feature | Pub/Sub API | Legacy Streaming API (Deprecated) |
+|---------|-------------|----------------------------------|
+| **Protocol** | gRPC | CometD (long-polling) |
+| **Authentication** | OAuth 2.0 | Session-based |
+| **Event Types** | Platform Events, CDC, Custom Channels | PushTopic, Generic Events, Platform Events |
+| **Performance** | High throughput, binary protocol | Limited by long-polling overhead |
+| **Status** | **Current — use for all new development** | Deprecated — no new investments |
+
+### Subscription Modes
+
+- **Subscribe**: Stream events from a given replay ID forward
+- **PublishStream**: Bi-directional — publish events via gRPC (no Apex needed)
+- **ManagedSubscribe**: Salesforce manages replay state (simplest for external consumers)
+
+### External Consumer Architecture
+
+```
+Salesforce Org
+  └── Platform Event / CDC Event
+        └── Pub/Sub API (gRPC endpoint)
+              └── External Consumer (Java, Python, Node.js, Go)
+                    ├── Process event
+                    ├── Commit replay ID
+                    └── Handle failures with retry
+```
+
+### LWC Subscription (Internal)
+
+For Lightning Web Components subscribing to Platform Events, use **empApi**:
+
+```javascript
+import { subscribe, unsubscribe, onError } from 'lightning/empApi';
+
+const channelName = '/event/Order_Status__e';
+let subscription = {};
+
+connectedCallback() {
+    subscribe(channelName, -1, (response) => {
+        console.log('Event received:', JSON.stringify(response));
+        this.handleEvent(response.data.payload);
+    }).then((sub) => {
+        subscription = sub;
+    });
+
+    onError((error) => {
+        console.error('empApi error:', JSON.stringify(error));
+    });
+}
+
+disconnectedCallback() {
+    unsubscribe(subscription);
+}
+```
+
+---
+
+## Event Relays to AWS EventBridge
+
+Salesforce Event Relays forward Platform Events to AWS EventBridge, enabling cloud-native event processing.
+
+### Architecture
+
+```
+Salesforce Platform Event
+  └── Event Relay Definition (Metadata)
+        └── AWS EventBridge Partner Event Source
+              ├── AWS Lambda
+              ├── AWS SQS
+              ├── AWS Step Functions
+              └── Any EventBridge target
+```
+
+### When to Use
+
+- AWS-native architecture needing Salesforce events
+- Complex event processing requiring AWS services (Step Functions, SQS, SNS)
+- Fan-out to multiple AWS consumers from a single Salesforce event
+- Event archival in AWS S3 or data lakes
+
+### Limitations
+
+- One-way only (Salesforce → AWS)
+- Adds latency (~seconds) compared to direct Pub/Sub API
+- Requires AWS account configuration and IAM setup
+- Platform Event limits still apply on the Salesforce side
+
+---
+
+## Apache Kafka on Heroku
+
+For organizations needing long-retention, high-throughput event streaming beyond Platform Event limits.
+
+### Comparison with Platform Events
+
+| Feature | Platform Events | Kafka on Heroku |
+|---------|----------------|-----------------|
+| **Retention** | 24h (HV) / 72h (SV) | 1-6 weeks (configurable) |
+| **Throughput** | Millions/day (HV) | Millions/second |
+| **Consumer groups** | Limited | Unlimited |
+| **Replay** | ReplayId-based | Offset-based, topic-level |
+| **Cost** | Included / Platform Event add-on | Heroku Kafka add-on |
+
+### When to Choose Kafka
+
+- Retention > 72 hours required
+- Need multiple independent consumer groups
+- Event throughput exceeds Platform Event limits
+- Existing Kafka ecosystem in organization
+- Need topic partitioning for ordered processing
+
+### Integration Pattern
+
+```
+Salesforce → Platform Event → Apex/Flow subscriber → Heroku Kafka producer
+                                                        └── Consumer Group A (analytics)
+                                                        └── Consumer Group B (data lake)
+                                                        └── Consumer Group C (external CRM)
+```
+
+---
+
+## When NOT to Use Events
+
+Events are not always the right choice. Prefer synchronous patterns when:
+
+| Scenario | Why Not Events | Better Alternative |
+|----------|---------------|-------------------|
+| **Need synchronous response** | Events are async — no return value | REST callout with Named Credential |
+| **Infrequent data changes** | Event infrastructure overhead not justified | Scheduled batch sync |
+| **Target system lacks event support** | Consumer can't subscribe to events | Outbound Messages or REST callout |
+| **Simple record sync** | Over-engineering for basic needs | Salesforce Connect / External Objects |
+| **Data volume < 100 records/day** | Platform Event overhead unnecessary | Scheduled Flow with REST callout |
+
+---
+
+## High-Volume Outbound Pattern
+
+For scenarios requiring high-volume data push to external systems:
+
+> **Do NOT use async Apex directly for high-volume outbound.** Apex async limits (250K daily Queueable, 250K daily @future) are shared across all org operations. Consuming them for outbound sync starves other automation.
+
+### Recommended Pattern: Middleware + Platform Events
+
+```
+Salesforce Record Change
+  └── After-Save Flow / Trigger
+        └── Publish Platform Event (lightweight payload)
+              └── External Middleware (MuleSoft, Pub/Sub API consumer)
+                    ├── Enrich data (callback to Salesforce REST API if needed)
+                    ├── Transform to target format
+                    ├── Deliver to target system with retry logic
+                    └── Report status back via Platform Event or REST callback
+```
+
+### Benefits
+
+- **No Apex async limit consumption** — events don't count against daily limits
+- **Middleware handles retries** — exponential backoff, dead letter queues
+- **Scalable** — middleware scales independently of Salesforce
+- **Observable** — middleware provides logging, monitoring, alerting
+
+---
+
+## Monitoring Event-Driven Systems
+
+### AsyncApexJob Monitoring
+
+Query job status for async Apex that processes events:
+
+```apex
+List<AsyncApexJob> jobs = [
+    SELECT Id, JobType, Status, NumberOfErrors, MethodName, CreatedDate
+    FROM AsyncApexJob
+    WHERE CreatedDate = TODAY
+    AND Status IN ('Failed', 'Aborted')
+    ORDER BY CreatedDate DESC
+    LIMIT 50
+];
+```
+
+> **Polling limit**: AsyncApexJob queries are subject to SOQL limits. Max polling frequency: every 5 minutes.
+
+### Platform Event Metrics
+
+- **Setup → Platform Events → Usage**: View publish/subscribe counts
+- **EventBusSubscriber**: Query for subscriber status and position
+- **Proactive Monitoring**: Set up Flow or Apex to alert on failed event processing
+
+```apex
+// Check subscriber lag
+List<EventBusSubscriber> subs = [
+    SELECT Name, Position, Retries, LastError, Status
+    FROM EventBusSubscriber
+    WHERE Topic = 'Order_Status__e'
+];
+```
+
+### Key Metrics to Monitor
+
+| Metric | Source | Alert Threshold |
+|--------|--------|-----------------|
+| Failed events | `EventBusSubscriber.Retries` | > 3 consecutive retries |
+| Subscriber lag | `EventBusSubscriber.Position` vs latest ReplayId | Lag > 1000 events |
+| Async job failures | `AsyncApexJob.NumberOfErrors` | Any failure |
+| Event publish errors | `Database.SaveResult` in publisher | Any failure |
+| Daily event usage | Setup → Company Information → Platform Event Usage | > 80% of allocation |
+
+---
+
+## Summary: EDA Decision Tree
+
+```
+Need real-time data sync?
+  ├── YES → Is consumer external?
+  │    ├── YES → Pub/Sub API + Platform Events (or CDC for record changes)
+  │    └── NO → Platform Event trigger subscriber (or empApi for LWC)
+  └── NO → Is volume high (>10K records/day)?
+       ├── YES → Middleware + Platform Events (high-volume outbound pattern)
+       └── NO → Scheduled batch sync (simplest, most maintainable)
+```