@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/building-sf-integrations/references/callout-patterns.md

@@ -1,719 +0,0 @@
-<!-- Parent: building-sf-integrations/SKILL.md -->
-# Callout Patterns Reference
-
-This document provides detailed implementation patterns for REST and SOAP callouts in Salesforce integrations.
-
-> **Parent Document**: [building-sf-integrations/SKILL.md](../SKILL.md)
-> **Related**: [event-patterns.md](./event-patterns.md)
-
----
-
-## Table of Contents
-
-- [REST Callout Patterns](#rest-callout-patterns)
-  - [Synchronous REST Callout](#synchronous-rest-callout)
-  - [Asynchronous REST Callout (Queueable)](#asynchronous-rest-callout-queueable)
-  - [Retry Handler with Exponential Backoff](#retry-handler-with-exponential-backoff)
-- [SOAP Callout Patterns](#soap-callout-patterns)
-  - [WSDL2Apex Process](#wsdl2apex-process)
-  - [SOAP Service Implementation](#soap-service-implementation)
-
----
-
-## REST Callout Patterns
-
-### Synchronous REST Callout
-
-**Use Case**: Need immediate response, NOT triggered from DML
-
-**Template**: `assets/callouts/rest-sync-callout.cls`
-
-**When to Use**:
-- User-initiated actions requiring immediate feedback
-- API calls from Lightning Web Components
-- Scheduled batch jobs needing sequential processing
-- Any non-trigger context where response is needed
-
-**When NOT to Use**:
-- Triggered from DML operations (triggers, Process Builder, flows)
-- Long-running operations (>10 seconds expected)
-- High-volume batch operations
-
-#### Implementation
-
-```apex
-public with sharing class {{ServiceName}}Callout {
-
-    private static final String NAMED_CREDENTIAL = 'callout:{{NamedCredentialName}}';
-
-    public static HttpResponse makeRequest(String method, String endpoint, String body) {
-        HttpRequest req = new HttpRequest();
-        req.setEndpoint(NAMED_CREDENTIAL + endpoint);
-        req.setMethod(method);
-        req.setHeader('Content-Type', 'application/json');
-        req.setTimeout(120000); // 120 seconds max
-
-        if (String.isNotBlank(body)) {
-            req.setBody(body);
-        }
-
-        Http http = new Http();
-        return http.send(req);
-    }
-
-    public static Map<String, Object> get(String endpoint) {
-        HttpResponse res = makeRequest('GET', endpoint, null);
-        return handleResponse(res);
-    }
-
-    public static Map<String, Object> post(String endpoint, Map<String, Object> payload) {
-        HttpResponse res = makeRequest('POST', endpoint, JSON.serialize(payload));
-        return handleResponse(res);
-    }
-
-    public static Map<String, Object> put(String endpoint, Map<String, Object> payload) {
-        HttpResponse res = makeRequest('PUT', endpoint, JSON.serialize(payload));
-        return handleResponse(res);
-    }
-
-    public static Map<String, Object> patch(String endpoint, Map<String, Object> payload) {
-        HttpResponse res = makeRequest('PATCH', endpoint, JSON.serialize(payload));
-        return handleResponse(res);
-    }
-
-    public static void deleteRequest(String endpoint) {
-        makeRequest('DELETE', endpoint, null);
-    }
-
-    private static Map<String, Object> handleResponse(HttpResponse res) {
-        Integer statusCode = res.getStatusCode();
-
-        if (statusCode >= 200 && statusCode < 300) {
-            return (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
-        } else if (statusCode >= 400 && statusCode < 500) {
-            throw new CalloutException('Client Error: ' + statusCode + ' - ' + res.getBody());
-        } else if (statusCode >= 500) {
-            throw new CalloutException('Server Error: ' + statusCode + ' - ' + res.getBody());
-        }
-
-        return null;
-    }
-}
-```
-
-#### Key Features
-
-- **Named Credential Integration**: Uses `callout:` syntax for secure authentication
-- **Timeout Management**: 120-second max timeout (governor limit)
-- **HTTP Method Support**: GET, POST, PUT, PATCH, DELETE
-- **Status Code Handling**: Differentiates between client (4xx) and server (5xx) errors
-- **JSON Serialization**: Automatic JSON handling for request/response bodies
-
-#### Usage Example
-
-```apex
-// GET request
-try {
-    Map<String, Object> data = StripeCallout.get('/v1/customers/cus_123');
-    String email = (String) data.get('email');
-} catch (CalloutException e) {
-    // Handle error
-    System.debug(LoggingLevel.ERROR, 'Callout failed: ' + e.getMessage());
-}
-
-// POST request
-Map<String, Object> payload = new Map<String, Object>{
-    'email' => 'customer@example.com',
-    'name' => 'John Doe'
-};
-Map<String, Object> response = StripeCallout.post('/v1/customers', payload);
-```
-
----
-
-### Asynchronous REST Callout (Queueable)
-
-**Use Case**: Callouts triggered from DML (triggers, Process Builder)
-
-**Template**: `assets/callouts/rest-queueable-callout.cls`
-
-**When to Use**:
-- Callouts from triggers (REQUIRED - sync callouts fail in triggers)
-- Fire-and-forget operations (no immediate response needed)
-- Bulk operations processing multiple records
-- Long-running API calls (>10 seconds)
-
-**Governor Limit Considerations**:
-- Max 50 queueable jobs per transaction
-- Queueable can chain to another queueable (max depth varies by org)
-- Callout timeout: 120 seconds
-
-#### Implementation
-
-```apex
-public with sharing class {{ServiceName}}QueueableCallout implements Queueable, Database.AllowsCallouts {
-
-    private List<Id> recordIds;
-    private String operation;
-
-    public {{ServiceName}}QueueableCallout(List<Id> recordIds, String operation) {
-        this.recordIds = recordIds;
-        this.operation = operation;
-    }
-
-    public void execute(QueueableContext context) {
-        if (recordIds == null || recordIds.isEmpty()) {
-            return;
-        }
-
-        try {
-            // Query records
-            List<{{ObjectName}}> records = [
-                SELECT Id, Name, {{FieldsToSend}}
-                FROM {{ObjectName}}
-                WHERE Id IN :recordIds
-                WITH USER_MODE
-            ];
-
-            // Make callout for each record (consider batching)
-            for ({{ObjectName}} record : records) {
-                makeCallout(record);
-            }
-
-        } catch (CalloutException e) {
-            // Log callout errors
-            System.debug(LoggingLevel.ERROR, 'Callout failed: ' + e.getMessage());
-            // Consider: Create error log record, retry logic, notification
-        } catch (Exception e) {
-            System.debug(LoggingLevel.ERROR, 'Error: ' + e.getMessage());
-        }
-    }
-
-    private void makeCallout({{ObjectName}} record) {
-        HttpRequest req = new HttpRequest();
-        req.setEndpoint('callout:{{NamedCredentialName}}/{{Endpoint}}');
-        req.setMethod('POST');
-        req.setHeader('Content-Type', 'application/json');
-        req.setTimeout(120000);
-
-        Map<String, Object> payload = new Map<String, Object>{
-            'id' => record.Id,
-            'name' => record.Name
-            // Add more fields
-        };
-        req.setBody(JSON.serialize(payload));
-
-        Http http = new Http();
-        HttpResponse res = http.send(req);
-
-        if (res.getStatusCode() >= 200 && res.getStatusCode() < 300) {
-            // Success - update record status if needed
-        } else {
-            // Handle error
-            throw new CalloutException('API Error: ' + res.getStatusCode());
-        }
-    }
-}
-```
-
-#### Trigger Integration
-
-```apex
-trigger OpportunityTrigger on Opportunity (after insert, after update) {
-    List<Id> opportunityIds = new List<Id>();
-
-    for (Opportunity opp : Trigger.new) {
-        // Only sync closed-won opportunities
-        if (opp.StageName == 'Closed Won') {
-            opportunityIds.add(opp.Id);
-        }
-    }
-
-    if (!opportunityIds.isEmpty()) {
-        // Enqueue async callout
-        System.enqueueJob(new SalesforceQueueableCallout(opportunityIds, 'SYNC'));
-    }
-}
-```
-
-#### Bulkification Pattern
-
-For high-volume scenarios, batch multiple callouts:
-
-```apex
-private void makeCallouts(List<{{ObjectName}}> records) {
-    // Batch up to 10 records per callout
-    Integer BATCH_SIZE = 10;
-    List<Map<String, Object>> batch = new List<Map<String, Object>>();
-
-    for (Integer i = 0; i < records.size(); i++) {
-        batch.add(buildPayload(records[i]));
-
-        if (batch.size() == BATCH_SIZE || i == records.size() - 1) {
-            // Make single callout with batch
-            sendBatch(batch);
-            batch.clear();
-        }
-    }
-}
-
-private void sendBatch(List<Map<String, Object>> batch) {
-    HttpRequest req = new HttpRequest();
-    req.setEndpoint('callout:{{NamedCredentialName}}/batch');
-    req.setMethod('POST');
-    req.setHeader('Content-Type', 'application/json');
-    req.setTimeout(120000);
-    req.setBody(JSON.serialize(new Map<String, Object>{'records' => batch}));
-
-    Http http = new Http();
-    HttpResponse res = http.send(req);
-    // Handle response
-}
-```
-
----
-
-### Retry Handler with Exponential Backoff
-
-**Use Case**: Handle transient failures with intelligent retry logic
-
-**Template**: `assets/callouts/callout-retry-handler.cls`
-
-**Retry Strategy**:
-- **Max Retries**: 3 attempts
-- **Backoff**: Exponential (1s, 2s, 4s)
-- **Retry on**: 5xx server errors, network timeouts
-- **Don't Retry**: 4xx client errors (bad request, auth failure)
-
-#### Implementation
-
-```apex
-public with sharing class CalloutRetryHandler {
-
-    private static final Integer MAX_RETRIES = 3;
-    private static final Integer BASE_DELAY_MS = 1000; // 1 second
-
-    public static HttpResponse executeWithRetry(HttpRequest request) {
-        Integer retryCount = 0;
-        HttpResponse response;
-
-        while (retryCount < MAX_RETRIES) {
-            try {
-                Http http = new Http();
-                response = http.send(request);
-
-                // Success or client error (4xx) - don't retry
-                if (response.getStatusCode() < 500) {
-                    return response;
-                }
-
-                // Server error (5xx) - retry with backoff
-                retryCount++;
-                if (retryCount < MAX_RETRIES) {
-                    // Exponential backoff: 1s, 2s, 4s
-                    Integer delayMs = BASE_DELAY_MS * (Integer) Math.pow(2, retryCount - 1);
-                    // Note: Apex doesn't have sleep(), so we schedule retry via Queueable
-                    throw new RetryableException('Server error, retry ' + retryCount);
-                }
-
-            } catch (CalloutException e) {
-                retryCount++;
-                if (retryCount >= MAX_RETRIES) {
-                    throw e;
-                }
-            }
-        }
-
-        return response;
-    }
-
-    public class RetryableException extends Exception {}
-}
-```
-
-#### Queueable Retry Pattern
-
-Since Apex doesn't support `Thread.sleep()`, implement retry delays using Queueable chaining:
-
-```apex
-public with sharing class CalloutWithRetryQueueable implements Queueable, Database.AllowsCallouts {
-
-    private HttpRequest request;
-    private Integer retryCount;
-    private static final Integer MAX_RETRIES = 3;
-
-    public CalloutWithRetryQueueable(HttpRequest req) {
-        this(req, 0);
-    }
-
-    private CalloutWithRetryQueueable(HttpRequest req, Integer retries) {
-        this.request = req;
-        this.retryCount = retries;
-    }
-
-    public void execute(QueueableContext context) {
-        try {
-            Http http = new Http();
-            HttpResponse res = http.send(request);
-
-            if (res.getStatusCode() >= 500 && retryCount < MAX_RETRIES) {
-                // Server error - retry
-                System.debug(LoggingLevel.WARN, 'Retry ' + (retryCount + 1) + ' for ' + request.getEndpoint());
-                System.enqueueJob(new CalloutWithRetryQueueable(request, retryCount + 1));
-            } else if (res.getStatusCode() >= 200 && res.getStatusCode() < 300) {
-                // Success
-                handleSuccess(res);
-            } else {
-                // Client error - don't retry
-                handleError(res);
-            }
-
-        } catch (CalloutException e) {
-            if (retryCount < MAX_RETRIES) {
-                System.enqueueJob(new CalloutWithRetryQueueable(request, retryCount + 1));
-            } else {
-                throw e;
-            }
-        }
-    }
-
-    private void handleSuccess(HttpResponse res) {
-        // Process successful response
-        System.debug('Callout succeeded: ' + res.getBody());
-    }
-
-    private void handleError(HttpResponse res) {
-        // Log error
-        System.debug(LoggingLevel.ERROR, 'Callout error: ' + res.getStatusCode() + ' - ' + res.getBody());
-    }
-}
-```
-
-#### Idempotency Considerations
-
-When implementing retries, ensure API operations are idempotent:
-
-```apex
-// BAD: Non-idempotent (creates new record on each retry)
-POST /api/orders { "item": "Widget", "quantity": 1 }
-
-// GOOD: Idempotent (uses idempotency key)
-POST /api/orders
-Headers: Idempotency-Key: {{recordId}}-{{timestamp}}
-{ "item": "Widget", "quantity": 1 }
-```
-
----
-
-## SOAP Callout Patterns
-
-### WSDL2Apex Process
-
-SOAP integrations in Salesforce use WSDL2Apex to auto-generate Apex classes from WSDL files.
-
-#### Step-by-Step Process
-
-**Step 1: Generate Apex from WSDL**
-
-1. Navigate to **Setup** → **Apex Classes** → **Generate from WSDL**
-2. Upload WSDL file or provide URL
-3. Salesforce parses WSDL and generates:
-   - Stub class (contains service endpoint and operations)
-   - Request/Response classes (for each operation)
-   - Type classes (for complex data types)
-
-**Step 2: Configure Named Credential**
-
-Create a Named Credential for the SOAP endpoint:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
-    <label>{{ServiceName}} SOAP</label>
-    <endpoint>https://api.example.com/soap/v1</endpoint>
-    <principalType>NamedUser</principalType>
-    <protocol>Password</protocol>
-    <username>{{Username}}</username>
-    <password>{{Password}}</password>
-</NamedCredential>
-```
-
-**Step 3: Use Generated Classes**
-
-Generated classes follow this naming pattern:
-- **Stub Class**: `{{WsdlNamespace}}.{{ServiceName}}`
-- **Port Type**: `{{WsdlNamespace}}.{{PortTypeName}}`
-- **Operations**: Methods on the port type class
-
----
-
-### SOAP Service Implementation
-
-**Template**: `assets/soap/soap-callout-service.cls`
-
-#### Basic SOAP Callout
-
-```apex
-public with sharing class {{ServiceName}}SoapService {
-
-    public static {{ResponseType}} callService({{RequestType}} request) {
-        try {
-            // Generated stub class
-            {{WsdlGeneratedClass}}.{{PortType}} stub = new {{WsdlGeneratedClass}}.{{PortType}}();
-
-            // Set endpoint (use Named Credential if possible)
-            stub.endpoint_x = 'callout:{{NamedCredentialName}}';
-
-            // Set timeout
-            stub.timeout_x = 120000;
-
-            // Make the call
-            return stub.{{OperationName}}(request);
-
-        } catch (Exception e) {
-            System.debug(LoggingLevel.ERROR, 'SOAP Callout Error: ' + e.getMessage());
-            throw new CalloutException('SOAP service error: ' + e.getMessage());
-        }
-    }
-}
-```
-
-#### Example: Weather Service SOAP Callout
-
-**WSDL**: `https://your-external-system.com/service?wsdl` *(replace with your actual WSDL endpoint)*
-
-**Generated Classes** (example based on a weather service WSDL):
-- `GlobalWeatherSoap`
-- `GetWeatherRequest`
-- `GetWeatherResponse`
-
-**Service Implementation**:
-
-```apex
-public with sharing class WeatherService {
-
-    public static String getWeather(String city, String country) {
-        try {
-            // Initialize SOAP stub
-            GlobalWeatherSoap.GlobalWeatherSoap stub =
-                new GlobalWeatherSoap.GlobalWeatherSoap();
-
-            // Configure endpoint and timeout
-            stub.endpoint_x = 'callout:GlobalWeather_NC';
-            stub.timeout_x = 120000;
-
-            // Build request
-            GlobalWeatherSoap.GetWeatherRequest req =
-                new GlobalWeatherSoap.GetWeatherRequest();
-            req.CityName = city;
-            req.CountryName = country;
-
-            // Make callout
-            GlobalWeatherSoap.GetWeatherResponse res = stub.GetWeather(req);
-
-            return res.GetWeatherResult;
-
-        } catch (System.CalloutException e) {
-            System.debug(LoggingLevel.ERROR, 'Weather API callout failed: ' + e.getMessage());
-            return null;
-        }
-    }
-}
-```
-
-#### SOAP Headers and Authentication
-
-For SOAP services requiring custom headers (e.g., WS-Security):
-
-```apex
-public with sharing class SecureSoapService {
-
-    public static void callServiceWithAuth(String username, String password) {
-        // Generated stub
-        MyService.MyServiceSoap stub = new MyService.MyServiceSoap();
-
-        // Set endpoint
-        stub.endpoint_x = 'callout:MyService_NC';
-        stub.timeout_x = 120000;
-
-        // Set SOAP headers for authentication
-        stub.inputHttpHeaders_x = new Map<String, String>{
-            'SOAPAction' => 'http://tempuri.org/IMyService/MyOperation',
-            'Authorization' => 'Basic ' + EncodingUtil.base64Encode(
-                Blob.valueOf(username + ':' + password)
-            )
-        };
-
-        // Make request
-        MyService.MyRequest req = new MyService.MyRequest();
-        MyService.MyResponse res = stub.MyOperation(req);
-    }
-}
-```
-
-#### SOAP Fault Handling
-
-```apex
-public with sharing class RobustSoapService {
-
-    public static Object callWithFaultHandling() {
-        try {
-            MyService.MyServiceSoap stub = new MyService.MyServiceSoap();
-            stub.endpoint_x = 'callout:MyService_NC';
-            stub.timeout_x = 120000;
-
-            MyService.MyRequest req = new MyService.MyRequest();
-            return stub.MyOperation(req);
-
-        } catch (System.CalloutException e) {
-            // Parse SOAP fault
-            String errorMessage = e.getMessage();
-
-            if (errorMessage.contains('faultcode')) {
-                // SOAP Fault occurred
-                System.debug(LoggingLevel.ERROR, 'SOAP Fault: ' + errorMessage);
-                // Extract fault details using XML parsing if needed
-            } else {
-                // Network/HTTP error
-                System.debug(LoggingLevel.ERROR, 'Callout error: ' + errorMessage);
-            }
-
-            throw e;
-        }
-    }
-}
-```
-
-#### Async SOAP Callout (Queueable)
-
-For SOAP callouts triggered from DML:
-
-```apex
-public with sharing class SoapQueueableCallout implements Queueable, Database.AllowsCallouts {
-
-    private List<Id> recordIds;
-
-    public SoapQueueableCallout(List<Id> recordIds) {
-        this.recordIds = recordIds;
-    }
-
-    public void execute(QueueableContext context) {
-        try {
-            // Query records
-            List<Account> accounts = [
-                SELECT Id, Name, BillingCity, BillingCountry
-                FROM Account
-                WHERE Id IN :recordIds
-                WITH USER_MODE
-            ];
-
-            // Initialize SOAP stub
-            GlobalWeatherSoap.GlobalWeatherSoap stub =
-                new GlobalWeatherSoap.GlobalWeatherSoap();
-            stub.endpoint_x = 'callout:GlobalWeather_NC';
-            stub.timeout_x = 120000;
-
-            // Process each record
-            for (Account acc : accounts) {
-                GlobalWeatherSoap.GetWeatherRequest req =
-                    new GlobalWeatherSoap.GetWeatherRequest();
-                req.CityName = acc.BillingCity;
-                req.CountryName = acc.BillingCountry;
-
-                GlobalWeatherSoap.GetWeatherResponse res = stub.GetWeather(req);
-
-                // Update account with weather data
-                acc.Weather_Data__c = res.GetWeatherResult;
-            }
-
-            // Update records
-            update as user accounts;
-
-        } catch (Exception e) {
-            System.debug(LoggingLevel.ERROR, 'SOAP Queueable error: ' + e.getMessage());
-        }
-    }
-}
-```
-
----
-
-## Best Practices
-
-### Callout Governor Limits
-
-| Limit | Value | Notes |
-|-------|-------|-------|
-| Max callouts per transaction | 100 | Batch multiple requests if possible |
-| Max timeout per callout | 120 seconds | Set explicitly with `setTimeout()` |
-| Max total timeout per transaction | 120 seconds | All callouts combined |
-| Max heap size | 6 MB (sync) / 12 MB (async) | Large responses consume heap |
-
-### Security Checklist
-
-- Use Named Credentials for authentication (NEVER hardcode credentials)
-- Minimize OAuth scopes to least privilege
-- Use Certificate-based auth for high-security integrations
-- Validate SSL certificates (don't disable SSL verification)
-- Sanitize user input before including in callout payloads
-- Log callout errors without exposing sensitive data
-
-### Error Handling Patterns
-
-```apex
-try {
-    HttpResponse res = makeCallout();
-    handleResponse(res);
-} catch (System.CalloutException e) {
-    // Network error, timeout, SSL error
-    logError('Callout failed', e);
-} catch (JSONException e) {
-    // Malformed JSON response
-    logError('JSON parsing failed', e);
-} catch (Exception e) {
-    // Unexpected error
-    logError('Unexpected error', e);
-}
-```
-
-### Testing Callouts
-
-Use `Test.setMock()` to mock HTTP responses:
-
-```apex
-@isTest
-private class MyCalloutTest {
-
-    @isTest
-    static void testSuccessfulCallout() {
-        // Set mock response
-        Test.setMock(HttpCalloutMock.class, new MockHttpResponseGenerator());
-
-        Test.startTest();
-        Map<String, Object> result = MyService.get('/customers/123');
-        Test.stopTest();
-
-        System.assertEquals('customer@example.com', result.get('email'));
-    }
-
-    // Mock class
-    private class MockHttpResponseGenerator implements HttpCalloutMock {
-        public HttpResponse respond(HttpRequest req) {
-            HttpResponse res = new HttpResponse();
-            res.setHeader('Content-Type', 'application/json');
-            res.setBody('{"email":"customer@example.com"}');
-            res.setStatusCode(200);
-            return res;
-        }
-    }
-}
-```
-
----
-
-## Related Resources
-
-- [Event Patterns](./event-patterns.md) - Platform Events and Change Data Capture
-- [Main Skill Documentation](../SKILL.md) - building-sf-integrations overview
-- [Named Credentials Templates](../assets/named-credentials/) - Authentication templates
-- [Callout Templates](../assets/callouts/) - Ready-to-use callout patterns