@salesforce/afv-skills 1.22.0 → 1.23.0

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

@@ -1,201 +0,0 @@
-<!-- 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

@@ -1,173 +0,0 @@
-<!-- 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

@@ -1,288 +0,0 @@
-<!-- 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"
-}
-```