@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/assets/named-credentials/custom-auth.namedCredential-meta.xml

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Named Credential Template: Custom Authentication (API Key / Basic Auth)
+
+    Use Case: Simple APIs with API key or username/password
+    - Internal APIs
+    - Legacy systems
+    - APIs with simple authentication
+    - Development/testing environments
+
+    Authentication Types:
+    - Basic Auth: Username + Password in Authorization header
+    - API Key: Custom header with API key value
+
+    Setup Steps:
+    1. Replace all {{placeholder}} values
+    2. Deploy to org
+    3. Enter credentials via Setup → Named Credentials UI
+
+    File Location: force-app/main/default/namedCredentials/{{CredentialName}}.namedCredential-meta.xml
+-->
+<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>{{CredentialName}}</fullName>
+    <label>{{CredentialLabel}}</label>
+
+    <!-- Base URL for the external service -->
+    <endpoint>{{BaseEndpoint}}</endpoint>
+
+    <!--
+    Authentication Configuration
+
+    For Basic Auth:
+    - principalType: NamedUser
+    - protocol: Password
+    - generateAuthorizationHeader: true
+
+    For API Key (via custom header):
+    - principalType: Anonymous
+    - protocol: NoAuthentication
+    - Use calloutOptions or Apex to add header
+    -->
+    <principalType>NamedUser</principalType>
+    <protocol>Password</protocol>
+
+    <!--
+    Username for Basic Auth
+    Password is entered via UI after deployment (NOT stored in metadata)
+    -->
+    <username>{{Username}}</username>
+
+    <!-- Request Options -->
+    <generateAuthorizationHeader>true</generateAuthorizationHeader>
+    <allowMergeFieldsInBody>true</allowMergeFieldsInBody>
+    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
+
+    <!--
+    SECURITY WARNING:
+    - Password is stored securely by Salesforce, NOT in this file
+    - After deployment, configure password via:
+      Setup → Named Credentials → Edit → Enter Password
+    - Never commit passwords to source control
+
+    For API Key pattern (in Apex):
+
+    HttpRequest req = new HttpRequest();
+    req.setEndpoint('callout:{{CredentialName}}/endpoint');
+    req.setHeader('X-API-Key', '{!$Credential.Password}');
+
+    Or use External Credentials (API 61+) with Custom headers for cleaner API key handling.
+    -->
+</NamedCredential>

package/skills/building-sf-integrations/assets/named-credentials/oauth-client-credentials.namedCredential-meta.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Named Credential Template: OAuth 2.0 Client Credentials Flow
+
+    Use Case: Server-to-server integration without user context
+    - Machine-to-machine authentication
+    - Backend service integrations
+    - Scheduled jobs calling external APIs
+
+    Setup Steps:
+    1. Replace all {{placeholder}} values
+    2. Create corresponding Auth Provider if using OAuth
+    3. Deploy to org
+    4. Store client credentials in Setup → Named Credentials
+
+    File Location: force-app/main/default/namedCredentials/{{CredentialName}}.namedCredential-meta.xml
+-->
+<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>{{CredentialName}}</fullName>
+    <label>{{CredentialLabel}}</label>
+
+    <!-- Base URL for the external service (without trailing slash) -->
+    <endpoint>{{BaseEndpoint}}</endpoint>
+
+    <!-- Authentication Configuration -->
+    <principalType>NamedUser</principalType>
+    <protocol>Oauth</protocol>
+
+    <!-- OAuth Settings -->
+    <!-- Token endpoint where Salesforce requests access tokens -->
+    <oauthTokenEndpoint>{{TokenEndpoint}}</oauthTokenEndpoint>
+
+    <!-- Space-separated OAuth scopes (e.g., "read write") -->
+    <oauthScope>{{Scopes}}</oauthScope>
+
+    <!-- Auth Provider reference (create this first in Setup → Auth Providers) -->
+    <!-- <authProvider>{{AuthProviderName}}</authProvider> -->
+
+    <!-- Request Options -->
+    <generateAuthorizationHeader>true</generateAuthorizationHeader>
+    <allowMergeFieldsInBody>true</allowMergeFieldsInBody>
+    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
+
+    <!--
+    Client ID and Secret are stored via UI, NOT in metadata for security.
+    After deployment:
+    1. Go to Setup → Named Credentials
+    2. Edit the credential
+    3. Enter Client ID and Client Secret
+    -->
+</NamedCredential>

package/skills/building-sf-integrations/assets/named-credentials/oauth-jwt-bearer.namedCredential-meta.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Named Credential Template: OAuth 2.0 JWT Bearer Flow
+
+    Use Case: Server-to-server with certificate-based authentication
+    - CI/CD pipelines
+    - Backend service integrations
+    - Automated jobs requiring strong authentication
+
+    Prerequisites:
+    1. Create certificate in Setup → Certificate and Key Management
+    2. Create Connected App with JWT Bearer enabled
+    3. Upload public certificate to external system
+    4. Pre-authorize Connected App for users
+
+    Setup Steps:
+    1. Replace all {{placeholder}} values
+    2. Ensure certificate is uploaded
+    3. Configure Connected App for JWT
+    4. Deploy to org
+
+    File Location: force-app/main/default/namedCredentials/{{CredentialName}}.namedCredential-meta.xml
+-->
+<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>{{CredentialName}}</fullName>
+    <label>{{CredentialLabel}}</label>
+
+    <!-- Base URL for the external service -->
+    <endpoint>{{BaseEndpoint}}</endpoint>
+
+    <!-- Authentication Configuration -->
+    <principalType>NamedUser</principalType>
+    <protocol>Oauth</protocol>
+
+    <!-- JWT Bearer Settings -->
+    <oauthTokenEndpoint>{{TokenEndpoint}}</oauthTokenEndpoint>
+    <oauthScope>{{Scopes}}</oauthScope>
+
+    <!--
+    Certificate for signing JWT assertions
+    Must exist in Setup → Certificate and Key Management
+    -->
+    <certificate>{{CertificateName}}</certificate>
+
+    <!-- Auth Provider (configure for JWT Bearer) -->
+    <!-- <authProvider>{{AuthProviderName}}</authProvider> -->
+
+    <!-- Request Options -->
+    <generateAuthorizationHeader>true</generateAuthorizationHeader>
+    <allowMergeFieldsInBody>true</allowMergeFieldsInBody>
+    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
+
+    <!--
+    JWT Bearer Flow Details:
+    1. Salesforce creates JWT assertion signed with certificate
+    2. JWT is sent to token endpoint
+    3. External system validates signature
+    4. Access token returned
+    5. Access token used for API calls
+
+    JWT Claims (automatically generated):
+    - iss: Client ID
+    - sub: Username (for SF-to-SF) or service account
+    - aud: Token endpoint
+    - exp: Expiration timestamp
+    -->
+</NamedCredential>

package/skills/building-sf-integrations/assets/platform-events/event-publisher.cls

@@ -0,0 +1,191 @@
+/**
+ * @description Platform Event Publisher for {{EventName}}__e
+ *
+ * Use Case: Publish events from Apex
+ * - Trigger-based event publishing
+ * - Service layer event notifications
+ * - Batch job completion events
+ *
+ * Features:
+ * - Single and bulk event publishing
+ * - Error handling and logging
+ * - Partial success handling for bulk publishes
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+public with sharing class {{EventName}}Publisher {
+
+    /**
+     * @description Publish a single event
+     * @param recordId ID of the triggering record
+     * @param operation Operation type (CREATE, UPDATE, DELETE)
+     * @param payload JSON payload data
+     * @throws EventPublishException if publish fails
+     */
+    public static void publishEvent(Id recordId, String operation, Map<String, Object> payload) {
+        {{EventName}}__e event = new {{EventName}}__e();
+        event.Record_Id__c = recordId;
+        event.Operation__c = operation;
+        event.Payload__c = JSON.serialize(payload);
+        event.Correlation_Id__c = generateCorrelationId();
+        event.Event_Timestamp__c = Datetime.now();
+
+        Database.SaveResult result = EventBus.publish(event);
+
+        if (!result.isSuccess()) {
+            String errorMessage = getErrorMessage(result);
+            System.debug(LoggingLevel.ERROR, 'Event publish failed: ' + errorMessage);
+            throw new EventPublishException('Failed to publish event: ' + errorMessage);
+        }
+
+        System.debug(LoggingLevel.DEBUG, 'Event published successfully. Correlation ID: ' + event.Correlation_Id__c);
+    }
+
+    /**
+     * @description Publish multiple events in bulk
+     * @param events List of events to publish
+     * @return List of publish results
+     */
+    public static List<PublishResult> publishEvents(List<{{EventName}}__e> events) {
+        if (events == null || events.isEmpty()) {
+            return new List<PublishResult>();
+        }
+
+        // Ensure correlation IDs and timestamps
+        for ({{EventName}}__e event : events) {
+            if (String.isBlank(event.Correlation_Id__c)) {
+                event.Correlation_Id__c = generateCorrelationId();
+            }
+            if (event.Event_Timestamp__c == null) {
+                event.Event_Timestamp__c = Datetime.now();
+            }
+        }
+
+        List<Database.SaveResult> results = EventBus.publish(events);
+
+        List<PublishResult> publishResults = new List<PublishResult>();
+        for (Integer i = 0; i < results.size(); i++) {
+            Database.SaveResult sr = results[i];
+            {{EventName}}__e event = events[i];
+
+            PublishResult pr = new PublishResult();
+            pr.correlationId = event.Correlation_Id__c;
+            pr.success = sr.isSuccess();
+
+            if (!sr.isSuccess()) {
+                pr.errorMessage = getErrorMessage(sr);
+                System.debug(LoggingLevel.ERROR,
+                    'Event publish failed for correlation ' + pr.correlationId + ': ' + pr.errorMessage);
+            }
+
+            publishResults.add(pr);
+        }
+
+        return publishResults;
+    }
+
+    /**
+     * @description Publish events for record changes (use in triggers)
+     * @param records Changed records
+     * @param operation Operation type
+     */
+    public static void publishForRecords(List<SObject> records, String operation) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+
+        List<{{EventName}}__e> events = new List<{{EventName}}__e>();
+
+        for (SObject record : records) {
+            {{EventName}}__e event = new {{EventName}}__e();
+            event.Record_Id__c = record.Id;
+            event.Operation__c = operation;
+            event.Payload__c = JSON.serialize(record);
+            event.Correlation_Id__c = generateCorrelationId();
+            event.Event_Timestamp__c = Datetime.now();
+            events.add(event);
+        }
+
+        List<PublishResult> results = publishEvents(events);
+
+        // Log any failures
+        for (PublishResult pr : results) {
+            if (!pr.success) {
+                System.debug(LoggingLevel.ERROR, 'Publish failed: ' + pr.errorMessage);
+            }
+        }
+    }
+
+    /**
+     * @description Create event from Map (flexible payload)
+     * @param eventData Map containing event fields
+     * @return Constructed event
+     */
+    public static {{EventName}}__e createEvent(Map<String, Object> eventData) {
+        {{EventName}}__e event = new {{EventName}}__e();
+
+        if (eventData.containsKey('recordId')) {
+            event.Record_Id__c = (String) eventData.get('recordId');
+        }
+        if (eventData.containsKey('operation')) {
+            event.Operation__c = (String) eventData.get('operation');
+        }
+        if (eventData.containsKey('payload')) {
+            Object payload = eventData.get('payload');
+            event.Payload__c = payload instanceof String
+                ? (String) payload
+                : JSON.serialize(payload);
+        }
+        if (eventData.containsKey('correlationId')) {
+            event.Correlation_Id__c = (String) eventData.get('correlationId');
+        } else {
+            event.Correlation_Id__c = generateCorrelationId();
+        }
+
+        event.Event_Timestamp__c = Datetime.now();
+
+        return event;
+    }
+
+    /**
+     * @description Generate unique correlation ID
+     * @return UUID-like correlation ID
+     */
+    private static String generateCorrelationId() {
+        Blob b = Crypto.generateAesKey(128);
+        String h = EncodingUtil.convertToHex(b);
+        return h.substring(0, 8) + '-' +
+               h.substring(8, 12) + '-' +
+               h.substring(12, 16) + '-' +
+               h.substring(16, 20) + '-' +
+               h.substring(20);
+    }
+
+    /**
+     * @description Extract error message from SaveResult
+     * @param result Database.SaveResult
+     * @return Error message string
+     */
+    private static String getErrorMessage(Database.SaveResult result) {
+        List<String> messages = new List<String>();
+        for (Database.Error err : result.getErrors()) {
+            messages.add(err.getStatusCode() + ': ' + err.getMessage());
+        }
+        return String.join(messages, '; ');
+    }
+
+    /**
+     * @description Result wrapper for bulk publish operations
+     */
+    public class PublishResult {
+        public String correlationId;
+        public Boolean success;
+        public String errorMessage;
+    }
+
+    /**
+     * @description Exception for event publish failures
+     */
+    public class EventPublishException extends Exception {}
+}

package/skills/building-sf-integrations/assets/platform-events/event-subscriber-action.cls

@@ -0,0 +1,295 @@
+/**
+ * @description Platform Event Handler/Action Class for {{EventName}}__e
+ *
+ * Use Case: Business logic for processing Platform Events
+ * - Separated from trigger for testability
+ * - TAF-compatible action pattern
+ * - Bulkified processing
+ *
+ * This class is called by the {{EventName}}Subscriber trigger
+ * and contains all business logic for event processing.
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+public with sharing class {{EventName}}Handler {
+
+    /**
+     * @description Handle CREATE operation events
+     * @param event The platform event
+     */
+    public static void handleCreate({{EventName}}__e event) {
+        Map<String, Object> payload = parsePayload(event.Payload__c);
+
+        // Example: Create a record based on event data
+        /*
+        {{TargetObject}}__c newRecord = new {{TargetObject}}__c();
+        newRecord.Name = (String) payload.get('name');
+        newRecord.External_Id__c = event.Record_Id__c;
+        newRecord.Source_System__c = 'Platform Event';
+        insert newRecord;
+        */
+
+        System.debug(LoggingLevel.DEBUG,
+            'Processed CREATE event: ' + event.Correlation_Id__c);
+    }
+
+    /**
+     * @description Handle UPDATE operation events
+     * @param event The platform event
+     */
+    public static void handleUpdate({{EventName}}__e event) {
+        Map<String, Object> payload = parsePayload(event.Payload__c);
+        String recordId = event.Record_Id__c;
+
+        // Example: Update existing record
+        /*
+        List<{{TargetObject}}__c> records = [
+            SELECT Id, Name
+            FROM {{TargetObject}}__c
+            WHERE External_Id__c = :recordId
+            WITH USER_MODE
+            LIMIT 1
+        ];
+
+        if (!records.isEmpty()) {
+            {{TargetObject}}__c record = records[0];
+            record.Name = (String) payload.get('name');
+            record.Last_Sync__c = Datetime.now();
+            update record;
+        }
+        */
+
+        System.debug(LoggingLevel.DEBUG,
+            'Processed UPDATE event: ' + event.Correlation_Id__c);
+    }
+
+    /**
+     * @description Handle DELETE operation events
+     * @param event The platform event
+     */
+    public static void handleDelete({{EventName}}__e event) {
+        String recordId = event.Record_Id__c;
+
+        // Example: Delete or archive record
+        /*
+        List<{{TargetObject}}__c> records = [
+            SELECT Id
+            FROM {{TargetObject}}__c
+            WHERE External_Id__c = :recordId
+            WITH USER_MODE
+            LIMIT 1
+        ];
+
+        if (!records.isEmpty()) {
+            delete records;
+        }
+        */
+
+        System.debug(LoggingLevel.DEBUG,
+            'Processed DELETE event: ' + event.Correlation_Id__c);
+    }
+
+    /**
+     * @description Handle bulk events (for optimized processing)
+     *              Call this from trigger instead of individual handlers
+     *              when processing high volumes
+     * @param events List of events to process
+     */
+    public static void handleBulk(List<{{EventName}}__e> events) {
+        // Separate events by operation
+        List<{{EventName}}__e> createEvents = new List<{{EventName}}__e>();
+        List<{{EventName}}__e> updateEvents = new List<{{EventName}}__e>();
+        List<{{EventName}}__e> deleteEvents = new List<{{EventName}}__e>();
+
+        for ({{EventName}}__e event : events) {
+            switch on event.Operation__c {
+                when 'CREATE' {
+                    createEvents.add(event);
+                }
+                when 'UPDATE' {
+                    updateEvents.add(event);
+                }
+                when 'DELETE' {
+                    deleteEvents.add(event);
+                }
+            }
+        }
+
+        // Process each operation type in bulk
+        if (!createEvents.isEmpty()) {
+            handleBulkCreate(createEvents);
+        }
+        if (!updateEvents.isEmpty()) {
+            handleBulkUpdate(updateEvents);
+        }
+        if (!deleteEvents.isEmpty()) {
+            handleBulkDelete(deleteEvents);
+        }
+    }
+
+    /**
+     * @description Bulk create handler
+     * @param events CREATE events
+     */
+    private static void handleBulkCreate(List<{{EventName}}__e> events) {
+        List<{{TargetObject}}__c> newRecords = new List<{{TargetObject}}__c>();
+
+        for ({{EventName}}__e event : events) {
+            Map<String, Object> payload = parsePayload(event.Payload__c);
+
+            {{TargetObject}}__c record = new {{TargetObject}}__c();
+            // Map fields from payload
+            // record.Name = (String) payload.get('name');
+            // record.External_Id__c = event.Record_Id__c;
+
+            newRecords.add(record);
+        }
+
+        if (!newRecords.isEmpty()) {
+            // Use Database.insert for partial success handling
+            Database.SaveResult[] results = Database.insert(newRecords, false);
+            logDmlResults(results, 'CREATE');
+        }
+    }
+
+    /**
+     * @description Bulk update handler
+     * @param events UPDATE events
+     */
+    private static void handleBulkUpdate(List<{{EventName}}__e> events) {
+        // Collect external IDs to query
+        Set<String> externalIds = new Set<String>();
+        Map<String, {{EventName}}__e> eventsByExternalId = new Map<String, {{EventName}}__e>();
+
+        for ({{EventName}}__e event : events) {
+            externalIds.add(event.Record_Id__c);
+            eventsByExternalId.put(event.Record_Id__c, event);
+        }
+
+        // Query existing records
+        /*
+        Map<String, {{TargetObject}}__c> recordsByExternalId = new Map<String, {{TargetObject}}__c>();
+        for ({{TargetObject}}__c record : [
+            SELECT Id, External_Id__c, Name
+            FROM {{TargetObject}}__c
+            WHERE External_Id__c IN :externalIds
+            WITH USER_MODE
+        ]) {
+            recordsByExternalId.put(record.External_Id__c, record);
+        }
+
+        // Update records
+        List<{{TargetObject}}__c> toUpdate = new List<{{TargetObject}}__c>();
+        for (String extId : externalIds) {
+            if (recordsByExternalId.containsKey(extId)) {
+                {{TargetObject}}__c record = recordsByExternalId.get(extId);
+                {{EventName}}__e event = eventsByExternalId.get(extId);
+                Map<String, Object> payload = parsePayload(event.Payload__c);
+
+                // Update fields
+                // record.Name = (String) payload.get('name');
+                toUpdate.add(record);
+            }
+        }
+
+        if (!toUpdate.isEmpty()) {
+            Database.SaveResult[] results = Database.update(toUpdate, false);
+            logDmlResults(results, 'UPDATE');
+        }
+        */
+    }
+
+    /**
+     * @description Bulk delete handler
+     * @param events DELETE events
+     */
+    private static void handleBulkDelete(List<{{EventName}}__e> events) {
+        Set<String> externalIds = new Set<String>();
+        for ({{EventName}}__e event : events) {
+            externalIds.add(event.Record_Id__c);
+        }
+
+        /*
+        List<{{TargetObject}}__c> toDelete = [
+            SELECT Id
+            FROM {{TargetObject}}__c
+            WHERE External_Id__c IN :externalIds
+            WITH USER_MODE
+        ];
+
+        if (!toDelete.isEmpty()) {
+            Database.DeleteResult[] results = Database.delete(toDelete, false);
+            logDeleteResults(results, 'DELETE');
+        }
+        */
+    }
+
+    /**
+     * @description Parse JSON payload to Map
+     * @param payloadJson JSON string
+     * @return Parsed Map
+     */
+    private static Map<String, Object> parsePayload(String payloadJson) {
+        if (String.isBlank(payloadJson)) {
+            return new Map<String, Object>();
+        }
+
+        try {
+            return (Map<String, Object>) JSON.deserializeUntyped(payloadJson);
+        } catch (JSONException e) {
+            System.debug(LoggingLevel.ERROR, 'Failed to parse payload: ' + e.getMessage());
+            return new Map<String, Object>();
+        }
+    }
+
+    /**
+     * @description Log DML results for monitoring
+     * @param results Database.SaveResult array
+     * @param operation Operation name
+     */
+    private static void logDmlResults(Database.SaveResult[] results, String operation) {
+        Integer successCount = 0;
+        Integer failCount = 0;
+
+        for (Database.SaveResult sr : results) {
+            if (sr.isSuccess()) {
+                successCount++;
+            } else {
+                failCount++;
+                for (Database.Error err : sr.getErrors()) {
+                    System.debug(LoggingLevel.ERROR,
+                        operation + ' failed: ' + err.getStatusCode() + ' - ' + err.getMessage());
+                }
+            }
+        }
+
+        System.debug(LoggingLevel.INFO,
+            operation + ' results - Success: ' + successCount + ', Failed: ' + failCount);
+    }
+
+    /**
+     * @description Log delete results for monitoring
+     * @param results Database.DeleteResult array
+     * @param operation Operation name
+     */
+    private static void logDeleteResults(Database.DeleteResult[] results, String operation) {
+        Integer successCount = 0;
+        Integer failCount = 0;
+
+        for (Database.DeleteResult dr : results) {
+            if (dr.isSuccess()) {
+                successCount++;
+            } else {
+                failCount++;
+                for (Database.Error err : dr.getErrors()) {
+                    System.debug(LoggingLevel.ERROR,
+                        operation + ' failed: ' + err.getStatusCode() + ' - ' + err.getMessage());
+                }
+            }
+        }
+
+        System.debug(LoggingLevel.INFO,
+            operation + ' results - Success: ' + successCount + ', Failed: ' + failCount);
+    }
+}