@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/references/named-credentials-automation.md

@@ -0,0 +1,201 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# Named Credentials Automation Guide
+
+This guide explains how to automate Named Credential configuration using the building-sf-integrations helper scripts.
+
+> **Key Insight:** Enhanced Named Credentials (API 60+) can be configured programmatically using `ConnectApi.NamedCredentials` - no UI required!
+
+---
+
+## Overview
+
+Enhanced Named Credentials = **External Credential** + **Named Credential** + **Endpoint Security**
+
+```
+External Credential (stores the API key securely)
+         ↓
+Named Credential (references the External Credential)
+         ↓
+Your HTTP Callout (uses callout:NamedCredentialName)
+```
+
+### Why Enhanced Named Credentials?
+
+| Benefit | Description |
+|---------|-------------|
+| **Security** | AES-256 encryption by Salesforce platform |
+| **Flexibility** | Supports Custom, Basic, OAuth, JWT protocols |
+| **Portability** | Easier to manage across multiple orgs |
+| **Automation** | Configurable via ConnectApi (no UI required) |
+| **Compliance** | Passes PCI-DSS, SOC 2 audits |
+
+---
+
+## Deployment Order
+
+**CRITICAL:** Deploy components in this exact order:
+
+```bash
+# 1. Deploy External Credential (defines the credential structure)
+sf project deploy start \
+  --source-dir force-app/main/default/externalCredentials/YourAPI.externalCredential-meta.xml \
+  --target-org YourOrg
+
+# 2. Deploy Named Credential (references the External Credential)
+sf project deploy start \
+  --source-dir force-app/main/default/namedCredentials/YourAPI.namedCredential-meta.xml \
+  --target-org YourOrg
+
+# 3. Deploy endpoint security (allows outbound HTTP calls)
+sf project deploy start \
+  --source-dir force-app/main/default/cspTrustedSites/YourAPI.cspTrustedSite-meta.xml \
+  --target-org YourOrg
+
+# 4. Set the API key using our automation script
+./scripts/configure-named-credential.sh YourOrg
+```
+
+---
+
+## Automation Scripts
+
+### `configure-named-credential.sh`
+
+**Purpose:** Sets API keys for Enhanced Named Credentials using ConnectApi
+
+**Usage:**
+```bash
+./scripts/configure-named-credential.sh <org-alias>
+```
+
+**What it does:**
+1. Validates org connection via `sf org display`
+2. Checks External Credential exists via SOQL
+3. Prompts for API key securely (input hidden)
+4. Generates Apex using `ConnectApi.NamedCredentials.createCredential()`
+5. Handles create vs. patch automatically
+
+**Under the hood:**
+```apex
+ConnectApi.CredentialInput creds = new ConnectApi.CredentialInput();
+creds.externalCredential = 'YourExternalCredential';
+creds.principalName = 'yourPrincipalName';
+creds.authenticationProtocol = ConnectApi.CredentialAuthenticationProtocol.Custom;
+
+Map<String, ConnectApi.CredentialValueInput> params = new Map<String, ConnectApi.CredentialValueInput>();
+ConnectApi.CredentialValueInput apiKey = new ConnectApi.CredentialValueInput();
+apiKey.encrypted = true;
+apiKey.value = 'YOUR_API_KEY';
+params.put('apiKey', apiKey);
+
+creds.credentials = params;
+ConnectApi.NamedCredentials.createCredential(creds);
+```
+
+### `set-api-credential.sh`
+
+**Purpose:** Stores API keys in Custom Settings (legacy/dev approach)
+
+**Usage:**
+```bash
+# Secure input (recommended)
+./scripts/set-api-credential.sh <setting-name> - <org-alias>
+
+# Direct input
+./scripts/set-api-credential.sh <setting-name> <api-key> <org-alias>
+```
+
+**When to use:**
+- Dev/test environments
+- CI/CD pipelines (no Apex execution)
+- Simple API key auth via query parameters
+
+**Not recommended for production** - use Enhanced Named Credentials instead.
+
+---
+
+## Complete Example: Weather API
+
+### Step 1: Create Metadata
+
+**External Credential:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <authenticationProtocol>Custom</authenticationProtocol>
+    <externalCredentialParameters>
+        <parameterGroup>weatherAPIKey</parameterGroup>
+        <parameterName>weatherAPIKey</parameterName>
+        <parameterType>NamedPrincipal</parameterType>
+        <sequenceNumber>1</sequenceNumber>
+    </externalCredentialParameters>
+    <label>Weather API</label>
+</ExternalCredential>
+```
+
+**Named Credential:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
+    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
+    <calloutStatus>Enabled</calloutStatus>
+    <label>Weather API</label>
+    <namedCredentialParameters>
+        <parameterName>Url</parameterName>
+        <parameterType>Url</parameterType>
+        <parameterValue>https://api.weather.com</parameterValue>
+    </namedCredentialParameters>
+    <namedCredentialParameters>
+        <externalCredential>WeatherAPI</externalCredential>
+        <parameterName>ExternalCredential</parameterName>
+        <parameterType>Authentication</parameterType>
+    </namedCredentialParameters>
+    <namedCredentialType>SecuredEndpoint</namedCredentialType>
+</NamedCredential>
+```
+
+### Step 2: Deploy and Configure
+
+```bash
+# Deploy all metadata
+sf project deploy start --metadata ExternalCredential:WeatherAPI \
+  --metadata NamedCredential:WeatherAPI \
+  --metadata CspTrustedSite:WeatherAPI \
+  --target-org MyOrg
+
+# Configure API key
+./scripts/configure-named-credential.sh MyOrg
+```
+
+### Step 3: Use in Apex
+
+```apex
+HttpRequest req = new HttpRequest();
+req.setEndpoint('callout:WeatherAPI/forecast?city=London');
+req.setMethod('GET');
+
+HttpResponse res = new Http().send(req);
+System.debug(res.getBody());
+```
+
+The API key is automatically included - no manual credential handling!
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "External Credential not found" | Not deployed or wrong name | Deploy first, check spelling |
+| "Named Credential not found" | Not deployed | Deploy after External Credential |
+| "No existing credentials to update" | Using patch instead of create | Script handles automatically |
+| "Unable to connect" | Missing endpoint security | Deploy CSP Trusted Site |
+
+---
+
+## Related Documentation
+
+- [named-credentials-guide.md](./named-credentials-guide.md) - Template reference
+- [external-services-guide.md](./external-services-guide.md) - OpenAPI integration
+- [security-best-practices.md](./security-best-practices.md) - Security patterns

package/skills/building-sf-integrations/references/named-credentials-guide.md

@@ -0,0 +1,173 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# Named Credentials Guide
+
+## Overview
+
+Named Credentials provide secure storage of authentication credentials and endpoint URLs for external system integrations. They eliminate the need to hardcode credentials in Apex code.
+
+## Architecture Evolution
+
+### Legacy Named Credentials (Pre-API 61)
+
+- Single principal per credential
+- Authentication configured directly on Named Credential
+- Simpler setup but less flexible
+
+### External Credentials (API 61+)
+
+- Separate External Credential and Named Credential
+- Named Principal and Per-User Principal support
+- Permission Set-based access control
+- More secure and flexible
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  CREDENTIAL ARCHITECTURE (API 61+)                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  External Credential                                            │
+│  ├── Authentication Protocol (OAuth, JWT, Custom)               │
+│  ├── OAuth/JWT Parameters                                       │
+│  └── Principals                                                 │
+│      ├── Named Principal (shared service account)               │
+│      └── Per-User Principal (individual auth)                   │
+│                                                                 │
+│  Named Credential                                               │
+│  ├── Endpoint URL                                               │
+│  └── References External Credential                             │
+│                                                                 │
+│  Permission Set                                                 │
+│  └── External Credential Principal Access                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Authentication Types
+
+### 1. OAuth 2.0 Client Credentials
+
+**Use Case**: Server-to-server integration without user context
+
+```apex
+// Apex usage - Named Credential handles auth automatically
+HttpRequest req = new HttpRequest();
+req.setEndpoint('callout:MyOAuthCredential/api/resource');
+req.setMethod('GET');
+// Authorization header added automatically
+```
+
+**Setup**:
+1. Create Auth Provider (optional, for complex OAuth)
+2. Create Named Credential with OAuth protocol
+3. Enter Client ID and Client Secret via UI
+
+### 2. OAuth 2.0 JWT Bearer
+
+**Use Case**: Certificate-based server-to-server auth
+
+**Prerequisites**:
+- Certificate in Setup → Certificate and Key Management
+- Connected App configured for JWT Bearer
+- External system configured to trust certificate
+
+**Flow**:
+1. Salesforce creates JWT with claims (iss, sub, aud, exp)
+2. JWT signed with certificate private key
+3. JWT exchanged for access token
+4. Access token used for API calls
+
+### 3. Certificate-Based (Mutual TLS)
+
+**Use Case**: High-security integrations requiring client certificate
+
+**Setup**:
+1. Obtain client certificate from CA or external system
+2. Import to Setup → Certificate and Key Management
+3. Configure Named Credential with certificate
+4. External system must trust Salesforce's certificate
+
+### 4. Basic Auth / API Key
+
+**Use Case**: Simple APIs, internal systems
+
+**Pattern for API Key**:
+```apex
+HttpRequest req = new HttpRequest();
+req.setEndpoint('callout:MyCredential/api/resource');
+req.setHeader('X-API-Key', '{!$Credential.Password}');
+```
+
+## Best Practices
+
+### DO
+
+- **Use Named Credentials** for ALL external callouts
+- **Rotate credentials** regularly using Named Credential update
+- **Use External Credentials** (API 61+) for new development
+- **Limit OAuth scopes** to minimum required
+- **Use Per-User Principal** when user context matters
+- **Test credentials** before deployment
+
+### DON'T
+
+- **Never hardcode** credentials in Apex
+- **Never commit** credentials to source control
+- **Don't share** service account credentials across environments
+- **Don't use** overly broad OAuth scopes
+
+## Common Patterns
+
+### Pattern 1: Service Integration
+
+```apex
+public class ExternalServiceCallout {
+    public static HttpResponse callService(String endpoint, String body) {
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint('callout:ServiceCredential' + endpoint);
+        req.setMethod('POST');
+        req.setHeader('Content-Type', 'application/json');
+        req.setBody(body);
+        return new Http().send(req);
+    }
+}
+```
+
+### Pattern 2: Multiple Environments
+
+```
+Named Credentials:
+├── MyAPI_Dev     → https://api-dev.example.com
+├── MyAPI_UAT     → https://api-uat.example.com
+└── MyAPI_Prod    → https://api.example.com
+```
+
+Use Custom Metadata or Custom Settings to select credential by environment.
+
+### Pattern 3: Per-User OAuth (API 61+)
+
+For APIs requiring user-specific authentication:
+
+1. Create External Credential with Per-User Principal
+2. Create Named Credential referencing External Credential
+3. Users authenticate individually via OAuth flow
+4. Each user's callouts use their own token
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Named credential not found` | Credential doesn't exist or wrong name | Verify credential name in Setup |
+| `Authentication failed` | Invalid credentials | Update credentials via Setup UI |
+| `Insufficient privileges` | User lacks permission | Assign Permission Set with External Credential Principal Access |
+| `Connection refused` | Network/firewall issue | Check Remote Site Settings, firewall rules |
+| `Certificate error` | SSL/TLS issue | Verify certificate chain, expiration |
+
+## Migration: Legacy to External Credentials
+
+1. **Create External Credential** with same auth parameters
+2. **Create new Named Credential** referencing External Credential
+3. **Create Permission Set** with External Credential Principal Access
+4. **Assign Permission Set** to integration users
+5. **Update Apex code** to use new Named Credential
+6. **Test thoroughly** before decommissioning legacy credential
+7. **Delete legacy** Named Credential after validation

package/skills/building-sf-integrations/references/platform-events-guide.md

@@ -0,0 +1,288 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# Platform Events Guide
+
+## Overview
+
+Platform Events enable event-driven architecture in Salesforce. They provide a scalable, asynchronous messaging system for real-time integrations.
+
+## Event Types
+
+### Standard Volume
+
+- Up to ~2,000 events per hour
+- Included in all Salesforce editions
+- Standard delivery guarantees
+
+### High Volume
+
+- Millions of events per day
+- At-least-once delivery
+- 24-hour retention for replay
+- May require additional entitlement
+
+## When to Use Platform Events
+
+| Scenario | Platform Events | Other Options |
+|----------|-----------------|---------------|
+| Real-time notifications | ✅ Best choice | - |
+| Decoupled integrations | ✅ Best choice | - |
+| High-volume streaming | ✅ High Volume | Change Data Capture |
+| Simple record sync | Consider | Change Data Capture |
+| External system notifications | ✅ Best choice | - |
+| Internal process triggers | ✅ Good choice | Process Builder, Flow |
+
+## Creating Platform Events
+
+### Via Metadata (Recommended)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <deploymentStatus>Deployed</deploymentStatus>
+    <eventType>HighVolume</eventType>
+    <label>Order Update Event</label>
+    <pluralLabel>Order Update Events</pluralLabel>
+    <publishBehavior>PublishAfterCommit</publishBehavior>
+    <fields>
+        <fullName>Order_Id__c</fullName>
+        <label>Order ID</label>
+        <type>Text</type>
+        <length>18</length>
+    </fields>
+    <fields>
+        <fullName>Status__c</fullName>
+        <label>Status</label>
+        <type>Text</type>
+        <length>50</length>
+    </fields>
+</CustomObject>
+```
+
+### File Location
+
+```
+force-app/main/default/objects/Order_Update_Event__e/Order_Update_Event__e.object-meta.xml
+```
+
+## Publishing Events
+
+### From Apex
+
+```apex
+// Single event
+Order_Update_Event__e event = new Order_Update_Event__e();
+event.Order_Id__c = orderId;
+event.Status__c = 'Shipped';
+
+Database.SaveResult result = EventBus.publish(event);
+if (result.isSuccess()) {
+    System.debug('Event published: ' + result.getId());
+}
+
+// Multiple events
+List<Order_Update_Event__e> events = new List<Order_Update_Event__e>();
+// ... populate events
+List<Database.SaveResult> results = EventBus.publish(events);
+```
+
+### From Flow
+
+1. Create Record element
+2. Select Platform Event object
+3. Map field values
+
+### From Process Builder
+
+1. Add Immediate Action
+2. Select "Create a Record"
+3. Choose Platform Event
+
+## Subscribing to Events
+
+### Apex Trigger
+
+```apex
+trigger OrderUpdateSubscriber on Order_Update_Event__e (after insert) {
+    for (Order_Update_Event__e event : Trigger.new) {
+        System.debug('Order ' + event.Order_Id__c + ' is now ' + event.Status__c);
+        // Process event
+    }
+
+    // Set checkpoint for durability
+    EventBus.TriggerContext.currentContext().setResumeCheckpoint(
+        Trigger.new[Trigger.new.size() - 1].ReplayId
+    );
+}
+```
+
+### Flow (Record-Triggered)
+
+1. Create Platform Event-Triggered Flow
+2. Select Platform Event object
+3. Build logic with event data
+
+### External (CometD)
+
+External systems can subscribe using CometD streaming:
+
+```
+/event/Order_Update_Event__e
+```
+
+## Publish Behavior
+
+### PublishAfterCommit (Default)
+
+- Event published after transaction commits
+- If transaction rolls back, event NOT published
+- **Recommended for most cases**
+
+### PublishImmediately
+
+- Event published immediately
+- Event still published even if transaction rolls back
+- Use when external system must be notified regardless of outcome
+
+## Durability & Replay
+
+### Replay ID
+
+Each event has a unique `ReplayId` for tracking and replay:
+
+```apex
+String replayId = event.ReplayId;
+```
+
+### Resume Checkpoint
+
+Set checkpoint to ensure durability:
+
+```apex
+// In trigger
+EventBus.TriggerContext.currentContext().setResumeCheckpoint(lastReplayId);
+```
+
+If trigger fails after checkpoint, processing resumes from that point.
+
+### Retention
+
+- High Volume events: 24 hours
+- Standard Volume: 24 hours
+
+## Best Practices
+
+### Publishing
+
+1. **Batch events** when publishing multiple
+2. **Check SaveResults** for publish failures
+3. **Use meaningful correlation IDs** for tracking
+4. **Include timestamp** for ordering
+5. **Keep payloads small** - use IDs, not full records
+
+### Subscribing
+
+1. **Always set resume checkpoint** in triggers
+2. **Don't throw exceptions** - catch and log errors
+3. **Process idempotently** - events may replay
+4. **Keep processing lightweight** - queue heavy work
+5. **Handle duplicates** using correlation ID
+
+### Design
+
+1. **Event granularity** - not too fine, not too coarse
+2. **Include enough context** but not entire records
+3. **Version your events** if schema evolves
+4. **Document event contracts** for consumers
+
+## Error Handling
+
+### Publish Errors
+
+```apex
+List<Database.SaveResult> results = EventBus.publish(events);
+for (Integer i = 0; i < results.size(); i++) {
+    if (!results[i].isSuccess()) {
+        for (Database.Error err : results[i].getErrors()) {
+            System.debug('Publish failed: ' + err.getMessage());
+        }
+    }
+}
+```
+
+### Subscriber Errors
+
+```apex
+trigger MySubscriber on My_Event__e (after insert) {
+    for (My_Event__e event : Trigger.new) {
+        try {
+            processEvent(event);
+        } catch (Exception e) {
+            // Log error, don't throw
+            System.debug('Error processing ' + event.ReplayId + ': ' + e.getMessage());
+            // Create error log record
+        }
+    }
+
+    // Still set checkpoint even if some failed
+    EventBus.TriggerContext.currentContext().setResumeCheckpoint(lastReplayId);
+}
+```
+
+## Monitoring
+
+### Setup → Platform Events
+
+- View event definitions
+- Check usage metrics
+- Monitor delivery status
+
+### Event Delivery Failures
+
+Check for:
+- Unhandled exceptions in triggers
+- Apex CPU timeout
+- Governor limit errors
+
+### Event Publishing
+
+Query `EventBusSubscriber` for subscription health:
+
+```apex
+SELECT Id, Position, ExternalId, Name, Status, Tip
+FROM EventBusSubscriber
+WHERE Topic = 'Order_Update_Event__e'
+```
+
+## Limits
+
+| Limit | Standard Volume | High Volume |
+|-------|-----------------|-------------|
+| Events per hour | ~2,000 | Millions |
+| Retention | 24 hours | 24 hours |
+| Max event size | 1 MB | 1 MB |
+| Fields per event | 100 | 100 |
+
+## External Integration
+
+### Subscribe from External System
+
+Use CometD client to connect to Streaming API:
+
+```
+Endpoint: /cometd/62.0
+Channel: /event/Order_Update_Event__e
+```
+
+### Publish from External System
+
+Use REST API:
+
+```http
+POST /services/data/v66.0/sobjects/Order_Update_Event__e
+Content-Type: application/json
+
+{
+    "Order_Id__c": "001xx000003NGSFAA4",
+    "Status__c": "Shipped"
+}
+```