@salesforce/afv-skills 1.8.0 → 1.9.0

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

@@ -0,0 +1,108 @@
+/**
+ * @description Platform Event Subscriber Trigger for {{EventName}}__e
+ *
+ * Use Case: React to published Platform Events
+ * - Process incoming events from other systems
+ * - Sync data based on events
+ * - Trigger downstream processes
+ *
+ * Key Concepts:
+ * - Platform Event triggers run in their own execution context
+ * - Events are processed in batches (up to 2000 for High Volume)
+ * - ReplayId enables resuming from failures
+ * - SetResumeCheckpoint ensures durability
+ *
+ * IMPORTANT:
+ * - Triggers on Platform Events only fire on AFTER INSERT
+ * - Events are immutable (cannot be updated or deleted)
+ * - Triggers run as Automated Process user
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+trigger {{EventName}}Subscriber on {{EventName}}__e (after insert) {
+
+    // Track last processed replay ID for durability
+    String lastReplayId = '';
+
+    // Process each event
+    for ({{EventName}}__e event : Trigger.new) {
+        // Store replay ID for checkpoint
+        lastReplayId = event.ReplayId;
+
+        try {
+            // Log event receipt
+            System.debug(LoggingLevel.DEBUG,
+                'Processing event: ' + event.Correlation_Id__c +
+                ' Operation: ' + event.Operation__c +
+                ' ReplayId: ' + event.ReplayId);
+
+            // Route to handler based on operation
+            switch on event.Operation__c {
+                when 'CREATE' {
+                    {{EventName}}Handler.handleCreate(event);
+                }
+                when 'UPDATE' {
+                    {{EventName}}Handler.handleUpdate(event);
+                }
+                when 'DELETE' {
+                    {{EventName}}Handler.handleDelete(event);
+                }
+                when else {
+                    // Unknown operation - log and continue
+                    System.debug(LoggingLevel.WARN,
+                        'Unknown operation: ' + event.Operation__c +
+                        ' for event: ' + event.Correlation_Id__c);
+                }
+            }
+
+        } catch (Exception e) {
+            // Log error but continue processing other events
+            // Don't throw - that would cause retry of ALL events in batch
+            System.debug(LoggingLevel.ERROR,
+                'Error processing event ' + event.Correlation_Id__c + ': ' + e.getMessage());
+            System.debug(LoggingLevel.ERROR, 'Stack: ' + e.getStackTraceString());
+
+            // Consider: Create error log record for monitoring
+            // {{EventName}}ErrorLogger.logError(event, e);
+        }
+    }
+
+    // Set resume checkpoint for durability
+    // If trigger fails after this point, processing resumes from this ReplayId
+    if (String.isNotBlank(lastReplayId)) {
+        EventBus.TriggerContext.currentContext().setResumeCheckpoint(lastReplayId);
+    }
+}
+
+/*
+ * ============================================================================
+ * PLATFORM EVENT TRIGGER BEST PRACTICES
+ * ============================================================================
+ *
+ * 1. ALWAYS set resume checkpoint
+ *    - Call setResumeCheckpoint() with the last processed ReplayId
+ *    - Ensures events aren't lost if trigger fails mid-batch
+ *
+ * 2. DON'T throw exceptions
+ *    - Unhandled exceptions cause entire batch to retry
+ *    - Catch errors per-event and log them
+ *    - Continue processing remaining events
+ *
+ * 3. Keep processing lightweight
+ *    - Avoid SOQL/DML in loops
+ *    - Collect data, then do bulk DML outside loop
+ *    - Consider queueing heavy work via Queueable
+ *
+ * 4. Handle duplicates
+ *    - At-least-once delivery means duplicates possible
+ *    - Use Correlation_Id__c to detect/dedupe
+ *    - Design handlers to be idempotent
+ *
+ * 5. Monitor failures
+ *    - Log errors to custom object for visibility
+ *    - Set up alerts for processing failures
+ *    - Review Event Delivery Failures in Setup
+ *
+ * ============================================================================
+ */

package/skills/building-sf-integrations/assets/platform-events/platform-event-definition.object-meta.xml

@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Platform Event Definition Template
+
+    Use Case: Asynchronous, event-driven communication
+    - Real-time notifications
+    - Decoupled system integrations
+    - High-volume data streaming
+    - Trigger external processes
+
+    Event Types:
+    - StandardVolume: ~2,000 events/hour, standard delivery
+    - HighVolume: Millions/day, at-least-once delivery, 24-hour retention
+
+    Publish Behaviors:
+    - PublishAfterCommit: Event published after transaction commits (default)
+    - PublishImmediately: Event published immediately (use for rollback scenarios)
+
+    Setup Steps:
+    1. Replace all {{placeholder}} values
+    2. Add fields as needed
+    3. Deploy to org
+    4. Create publisher (Apex, Flow, Process Builder)
+    5. Create subscriber (Trigger, Flow, External via CometD)
+
+    File Location: force-app/main/default/objects/{{EventName}}__e/{{EventName}}__e.object-meta.xml
+-->
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Deployment status -->
+    <deploymentStatus>Deployed</deploymentStatus>
+
+    <!--
+    Event Type:
+    - StandardVolume: Up to 2,000 events per hour (included in licenses)
+    - HighVolume: Up to millions per day (may require additional entitlement)
+
+    Use HighVolume for:
+    - Large-scale integrations
+    - IoT data streaming
+    - High-throughput scenarios
+    -->
+    <eventType>HighVolume</eventType>
+
+    <!-- Display labels -->
+    <label>{{EventLabel}}</label>
+    <pluralLabel>{{EventPluralLabel}}</pluralLabel>
+
+    <!--
+    Publish Behavior:
+    - PublishAfterCommit: Publish when transaction commits (RECOMMENDED)
+      Ensures event only fires if data save succeeds
+    - PublishImmediately: Publish right away
+      Use when you need event even if transaction rolls back
+    -->
+    <publishBehavior>PublishAfterCommit</publishBehavior>
+
+    <!-- Event Fields -->
+
+    <!-- Record ID field - link to triggering record -->
+    <fields>
+        <fullName>Record_Id__c</fullName>
+        <label>Record ID</label>
+        <description>ID of the Salesforce record that triggered this event</description>
+        <type>Text</type>
+        <length>18</length>
+        <externalId>false</externalId>
+    </fields>
+
+    <!-- Operation type field -->
+    <fields>
+        <fullName>Operation__c</fullName>
+        <label>Operation</label>
+        <description>The operation that occurred: CREATE, UPDATE, DELETE</description>
+        <type>Text</type>
+        <length>20</length>
+        <externalId>false</externalId>
+    </fields>
+
+    <!-- Payload field - JSON data -->
+    <fields>
+        <fullName>Payload__c</fullName>
+        <label>Payload</label>
+        <description>JSON payload containing event data</description>
+        <type>LongTextArea</type>
+        <length>131072</length>
+        <visibleLines>5</visibleLines>
+    </fields>
+
+    <!-- Correlation ID for tracking -->
+    <fields>
+        <fullName>Correlation_Id__c</fullName>
+        <label>Correlation ID</label>
+        <description>Unique ID for tracking related events across systems</description>
+        <type>Text</type>
+        <length>50</length>
+        <externalId>true</externalId>
+    </fields>
+
+    <!-- Timestamp field -->
+    <fields>
+        <fullName>Event_Timestamp__c</fullName>
+        <label>Event Timestamp</label>
+        <description>When the event occurred</description>
+        <type>DateTime</type>
+    </fields>
+
+    <!--
+    Add more fields as needed for your use case.
+
+    Field Types Supported:
+    - Text (up to 255 chars)
+    - LongTextArea (up to 131,072 chars)
+    - Number
+    - Checkbox
+    - DateTime
+    - Date
+
+    NOT Supported:
+    - Lookup/Master-Detail (no relationships)
+    - Formula
+    - Roll-up Summary
+    - Picklist (use Text instead)
+    -->
+</CustomObject>

package/skills/building-sf-integrations/assets/soap/soap-callout-service.cls

@@ -0,0 +1,186 @@
+/**
+ * @description SOAP Web Service Callout Service
+ *
+ * Use Case: Integrations with SOAP/XML-based web services
+ * - Legacy enterprise systems
+ * - Government APIs
+ * - Financial services (often SOAP-based)
+ *
+ * Prerequisites:
+ * 1. Generate Apex from WSDL (Setup → Apex Classes → Generate from WSDL)
+ * 2. Configure Named Credential or Remote Site Setting for endpoint
+ *
+ * This template wraps WSDL-generated stub classes with:
+ * - Error handling
+ * - Timeout configuration
+ * - Logging
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+public with sharing class {{ServiceName}}SoapService {
+
+    // Named Credential for SOAP endpoint (recommended over Remote Site Setting)
+    private static final String NAMED_CREDENTIAL = 'callout:{{NamedCredentialName}}';
+
+    // Timeout in milliseconds (max 120000)
+    private static final Integer TIMEOUT_MS = 120000;
+
+    /**
+     * @description Call SOAP operation with request object
+     *
+     * Replace {{WsdlStubClass}} with your WSDL-generated class name
+     * Replace {{PortType}} with the port/binding type from WSDL
+     * Replace {{OperationName}} with the SOAP operation to call
+     *
+     * @param request Request object (WSDL-generated type)
+     * @return Response object (WSDL-generated type)
+     * @throws SoapCalloutException on errors
+     */
+    public static {{ResponseType}} callService({{RequestType}} request) {
+        try {
+            // Instantiate the WSDL-generated stub
+            {{WsdlStubClass}}.{{PortType}} stub = new {{WsdlStubClass}}.{{PortType}}();
+
+            // Configure endpoint
+            // Option 1: Use Named Credential (recommended)
+            stub.endpoint_x = NAMED_CREDENTIAL;
+
+            // Option 2: Direct endpoint (requires Remote Site Setting)
+            // stub.endpoint_x = '{{SoapEndpoint}}';
+
+            // Set timeout
+            stub.timeout_x = TIMEOUT_MS;
+
+            // Set custom SOAP headers if needed
+            // stub.inputHttpHeaders_x = new Map<String, String>{
+            //     'X-Custom-Header' => 'value'
+            // };
+
+            // Make the SOAP call
+            {{ResponseType}} response = stub.{{OperationName}}(request);
+
+            // Log success
+            System.debug(LoggingLevel.DEBUG, 'SOAP call successful: {{OperationName}}');
+
+            return response;
+
+        } catch (CalloutException e) {
+            // Network/timeout error
+            System.debug(LoggingLevel.ERROR, 'SOAP CalloutException: ' + e.getMessage());
+            throw new SoapCalloutException('Connection error: ' + e.getMessage(), e);
+
+        } catch (Exception e) {
+            // SOAP fault or other error
+            System.debug(LoggingLevel.ERROR, 'SOAP Error: ' + e.getMessage());
+            System.debug(LoggingLevel.ERROR, 'Stack: ' + e.getStackTraceString());
+            throw new SoapCalloutException('SOAP service error: ' + e.getMessage(), e);
+        }
+    }
+
+    /**
+     * @description Async SOAP call via Queueable
+     *              Use this when calling from DML context (triggers)
+     * @param request Request object
+     * @param callbackId Optional ID for tracking the async job
+     */
+    public static void callServiceAsync({{RequestType}} request, Id callbackId) {
+        System.enqueueJob(new SoapCalloutQueueable(request, callbackId));
+    }
+
+    /**
+     * @description Queueable implementation for async SOAP calls
+     */
+    public class SoapCalloutQueueable implements Queueable, Database.AllowsCallouts {
+        private {{RequestType}} request;
+        private Id callbackId;
+
+        public SoapCalloutQueueable({{RequestType}} request, Id callbackId) {
+            this.request = request;
+            this.callbackId = callbackId;
+        }
+
+        public void execute(QueueableContext context) {
+            try {
+                {{ResponseType}} response = callService(request);
+
+                // Process response and update Salesforce record if needed
+                if (callbackId != null) {
+                    processCallback(response, callbackId);
+                }
+
+            } catch (Exception e) {
+                System.debug(LoggingLevel.ERROR, 'Async SOAP call failed: ' + e.getMessage());
+                // Consider: create error log, send notification
+            }
+        }
+    }
+
+    /**
+     * @description Process async callback result
+     * @param response SOAP response
+     * @param callbackId Record ID to update with result
+     */
+    private static void processCallback({{ResponseType}} response, Id callbackId) {
+        // TODO: Implement callback processing
+        // Example: Update a record with the response data
+        /*
+        SObject record = callbackId.getSObjectType().newSObject(callbackId);
+        record.put('Integration_Status__c', 'Complete');
+        record.put('Integration_Response__c', JSON.serialize(response));
+        update record;
+        */
+    }
+
+    /**
+     * @description Custom exception for SOAP callout errors
+     */
+    public class SoapCalloutException extends Exception {}
+}
+
+/*
+ * ============================================================================
+ * WSDL2APEX GENERATION GUIDE
+ * ============================================================================
+ *
+ * Step 1: Obtain WSDL
+ * -------------------
+ * Get the WSDL file from the external system. It should be an XML file
+ * defining the service, operations, and data types.
+ *
+ * Step 2: Generate Apex Classes
+ * -----------------------------
+ * 1. Go to Setup → Apex Classes
+ * 2. Click "Generate from WSDL"
+ * 3. Upload the WSDL file
+ * 4. Choose a namespace (or accept default)
+ * 5. Click "Generate Apex code"
+ *
+ * Step 3: Review Generated Classes
+ * --------------------------------
+ * Salesforce generates:
+ * - Stub class ({{WsdlStubClass}}) with methods for each operation
+ * - Request/Response wrapper classes
+ * - Data type classes matching WSDL schema
+ *
+ * Step 4: Configure Access
+ * ------------------------
+ * Option A: Named Credential (Recommended)
+ * - Create Named Credential with SOAP endpoint
+ * - Set stub.endpoint_x = 'callout:NamedCredentialName'
+ *
+ * Option B: Remote Site Setting
+ * - Create Remote Site Setting with SOAP endpoint domain
+ * - Set stub.endpoint_x to full URL
+ *
+ * Step 5: Test the Integration
+ * ----------------------------
+ * Execute anonymous Apex:
+ *
+ * {{RequestType}} req = new {{RequestType}}();
+ * req.field1 = 'value';
+ * {{ResponseType}} resp = {{ServiceName}}SoapService.callService(req);
+ * System.debug(resp);
+ *
+ * ============================================================================
+ */

package/skills/building-sf-integrations/assets/soap/wsdl2apex-guide.md

@@ -0,0 +1,213 @@
+# WSDL to Apex Generation Guide
+
+## Overview
+
+Salesforce can automatically generate Apex classes from WSDL (Web Services Description Language) files, enabling integration with SOAP-based web services.
+
+## Step-by-Step Process
+
+### 1. Obtain the WSDL File
+
+Get the WSDL from your external system. Common sources:
+- API documentation portal
+- Endpoint URL with `?wsdl` suffix (e.g., `https://api.example.com/service?wsdl`)
+- Direct download from vendor
+
+### 2. Review WSDL for Compatibility
+
+Salesforce WSDL2Apex has limitations. Check for:
+
+**Supported:**
+- Document/literal and RPC/encoded styles
+- Simple types (string, integer, boolean, date, etc.)
+- Complex types (objects with properties)
+- Arrays and lists
+- Basic SOAP headers
+
+**Not Supported / Problematic:**
+- Very large WSDLs (may hit Apex class size limits)
+- Certain complex inheritance patterns
+- Some advanced XSD features
+- WS-Security (requires manual implementation)
+
+### 3. Generate Apex Classes
+
+1. Navigate to **Setup → Apex Classes**
+2. Click **Generate from WSDL**
+3. Click **Choose File** and upload the WSDL
+4. Review the parse results
+5. Modify class names if needed (keep them short to avoid limits)
+6. Click **Generate Apex code**
+
+### 4. Generated Class Structure
+
+For a WSDL defining `CustomerService` with operation `getCustomer`:
+
+```
+AsyncCustomerService.cls         - Async version of service
+CustomerService.cls              - Main stub class with methods
+GetCustomerRequest.cls           - Request wrapper
+GetCustomerResponse.cls          - Response wrapper
+Customer.cls                     - Data type from schema
+Address.cls                      - Nested data type
+```
+
+### 5. Configure Endpoint Access
+
+**Option A: Named Credential (Recommended)**
+
+1. Create Named Credential in Setup
+2. Set endpoint to SOAP service URL
+3. Configure authentication (Basic, Certificate, OAuth)
+4. In Apex: `stub.endpoint_x = 'callout:MyNamedCredential';`
+
+**Option B: Remote Site Setting**
+
+1. Create Remote Site Setting with domain
+2. In Apex: `stub.endpoint_x = 'https://api.example.com/service';`
+
+### 6. Basic Usage Example
+
+```apex
+public class CustomerServiceCaller {
+
+    public static Customer getCustomer(String customerId) {
+        // Instantiate the generated stub
+        CustomerService.CustomerServicePort stub = new CustomerService.CustomerServicePort();
+
+        // Configure endpoint (Named Credential)
+        stub.endpoint_x = 'callout:CustomerServiceNC';
+
+        // Set timeout (max 120 seconds)
+        stub.timeout_x = 120000;
+
+        // Create request
+        GetCustomerRequest request = new GetCustomerRequest();
+        request.customerId = customerId;
+
+        // Make the call
+        GetCustomerResponse response = stub.getCustomer(request);
+
+        return response.customer;
+    }
+}
+```
+
+### 7. Error Handling
+
+```apex
+try {
+    GetCustomerResponse response = stub.getCustomer(request);
+    // Process response
+
+} catch (CalloutException e) {
+    // Network error, timeout, SSL issues
+    System.debug('Callout failed: ' + e.getMessage());
+
+} catch (Exception e) {
+    // SOAP fault (error from service)
+    // The exception message contains SOAP fault details
+    System.debug('SOAP error: ' + e.getMessage());
+}
+```
+
+### 8. Common Issues and Solutions
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `Web service callout failed` | Network/SSL issue | Check Remote Site Setting, verify endpoint |
+| `Read timed out` | Service slow to respond | Increase `timeout_x` (max 120000ms) |
+| `Apex class size limit` | WSDL too large | Split WSDL, use fewer operations |
+| `Unable to parse callout response` | Response doesn't match WSDL | Check service version, update WSDL |
+| `Methods defined as Webservice` | Conflict with reserved keywords | Rename operations in WSDL or generated class |
+
+### 9. Testing SOAP Callouts
+
+Use `Test.setMock()` with `WebServiceMock`:
+
+```apex
+@isTest
+public class CustomerServiceTest {
+
+    @isTest
+    static void testGetCustomer() {
+        // Set mock
+        Test.setMock(WebServiceMock.class, new CustomerServiceMock());
+
+        // Call service
+        Test.startTest();
+        Customer result = CustomerServiceCaller.getCustomer('CUST001');
+        Test.stopTest();
+
+        // Assert
+        System.assertEquals('Test Customer', result.name);
+    }
+
+    // Mock implementation
+    public class CustomerServiceMock implements WebServiceMock {
+        public void doInvoke(
+            Object stub,
+            Object request,
+            Map<String, Object> response,
+            String endpoint,
+            String soapAction,
+            String requestName,
+            String responseNS,
+            String responseName,
+            String responseType
+        ) {
+            // Create mock response
+            GetCustomerResponse mockResponse = new GetCustomerResponse();
+            mockResponse.customer = new Customer();
+            mockResponse.customer.name = 'Test Customer';
+
+            response.put('response_x', mockResponse);
+        }
+    }
+}
+```
+
+### 10. Async SOAP Calls
+
+For calls from triggers or after DML:
+
+```apex
+public class CustomerSyncQueueable implements Queueable, Database.AllowsCallouts {
+
+    private String customerId;
+
+    public CustomerSyncQueueable(String customerId) {
+        this.customerId = customerId;
+    }
+
+    public void execute(QueueableContext context) {
+        try {
+            Customer customer = CustomerServiceCaller.getCustomer(customerId);
+            // Process result
+        } catch (Exception e) {
+            // Log error
+        }
+    }
+}
+
+// Usage in trigger:
+System.enqueueJob(new CustomerSyncQueueable(accountId));
+```
+
+## Best Practices
+
+1. **Always use Named Credentials** for authentication instead of hardcoding credentials
+2. **Set appropriate timeouts** - default may be too short
+3. **Implement error handling** - SOAP services can fail in many ways
+4. **Log requests and responses** for debugging
+5. **Use async patterns** when calling from DML contexts
+6. **Test with mocks** - don't call real services in tests
+7. **Monitor governor limits** - especially for large responses
+
+## Limitations
+
+- Maximum 100 callouts per transaction
+- Maximum 120 second timeout per callout
+- Response body limit: 6MB
+- Apex code size limits may prevent large WSDL imports
+- Some WSDL features not supported (WS-Security, MTOM, etc.)