@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/assets/external-credentials/jwt-external-credential.externalCredential-meta.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    External Credential Template: JWT (API 61+)
+
+    Use Case: JWT Bearer authentication for server-to-server
+    - Machine-to-machine authentication
+    - Service account integrations
+    - High-security API access
+
+    API Version: 61.0+ (Spring '24+) REQUIRED
+
+    Prerequisites:
+    1. Create certificate in Setup → Certificate and Key Management
+    2. Register public key with external system
+    3. Configure JWT claims as required by external API
+
+    Setup Steps:
+    1. Replace all {{placeholder}} values
+    2. Upload certificate to Salesforce
+    3. Deploy to org
+    4. Create Named Credential referencing this External Credential
+
+    File Location: force-app/main/default/externalCredentials/{{CredentialName}}.externalCredential-meta.xml
+-->
+<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>{{CredentialLabel}}</label>
+
+    <!-- JWT Authentication Protocol -->
+    <authenticationProtocol>Jwt</authenticationProtocol>
+
+    <!--
+    JWT Configuration Parameters
+    -->
+
+    <!-- Issuer claim (iss) - typically your client ID or service identifier -->
+    <externalCredentialParameters>
+        <parameterName>issuer</parameterName>
+        <parameterType>SigningCertificate</parameterType>
+        <parameterValue>{{CertificateName}}</parameterValue>
+    </externalCredentialParameters>
+
+    <!-- Subject claim (sub) - the identity being asserted -->
+    <externalCredentialParameters>
+        <parameterName>subject</parameterName>
+        <parameterType>Custom</parameterType>
+        <parameterValue>{{SubjectIdentifier}}</parameterValue>
+    </externalCredentialParameters>
+
+    <!-- Audience claim (aud) - intended recipient of the JWT -->
+    <externalCredentialParameters>
+        <parameterName>audience</parameterName>
+        <parameterType>Custom</parameterType>
+        <parameterValue>{{AudienceUrl}}</parameterValue>
+    </externalCredentialParameters>
+
+    <!-- Token endpoint for JWT exchange -->
+    <externalCredentialParameters>
+        <parameterName>tokenEndpoint</parameterName>
+        <parameterType>AuthProviderTokenEndpoint</parameterType>
+        <parameterValue>{{TokenEndpoint}}</parameterValue>
+    </externalCredentialParameters>
+
+    <!-- JWT Expiration (in seconds) -->
+    <externalCredentialParameters>
+        <parameterName>expirationOffset</parameterName>
+        <parameterType>Custom</parameterType>
+        <parameterValue>3600</parameterValue>
+    </externalCredentialParameters>
+
+    <!-- Named Principal for JWT auth -->
+    <principals>
+        <principalName>{{PrincipalName}}</principalName>
+        <principalType>NamedPrincipal</principalType>
+        <sequenceNumber>1</sequenceNumber>
+    </principals>
+
+    <!--
+    JWT Token Flow:
+    1. Salesforce creates JWT with claims (iss, sub, aud, exp)
+    2. JWT signed with certificate private key
+    3. JWT sent to token endpoint
+    4. External system validates signature with public key
+    5. Access token returned
+    6. Access token used for API calls
+
+    Custom Claims:
+    Add additional externalCredentialParameters with parameterType="Custom"
+    to include custom claims required by your external system.
+    -->
+</ExternalCredential>

package/skills/building-sf-integrations/assets/external-credentials/oauth-external-credential.externalCredential-meta.xml

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    External Credential Template: OAuth 2.0 (API 61+)
+
+    Use Case: Modern OAuth 2.0 with Named Principal or Per-User authentication
+    - New integrations (recommended over legacy Named Credentials)
+    - APIs requiring per-user context
+    - Fine-grained permission control via Permission Sets
+
+    API Version: 61.0+ (Spring '24+) REQUIRED
+
+    Key Concepts:
+    - External Credential: Defines auth protocol and parameters
+    - Named Principal: Shared service account identity
+    - Per-User Principal: Individual user authentication
+    - Permission Set: Controls access to principals
+
+    Setup Steps:
+    1. Replace all {{placeholder}} values
+    2. Deploy to org
+    3. Create Named Credential referencing this External Credential
+    4. Assign Permission Set to users
+
+    File Location: force-app/main/default/externalCredentials/{{CredentialName}}.externalCredential-meta.xml
+-->
+<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>{{CredentialLabel}}</label>
+
+    <!-- Authentication Protocol: Oauth, Custom, NoAuth, JWT, JwtExchange -->
+    <authenticationProtocol>Oauth</authenticationProtocol>
+
+    <!--
+    OAuth Parameters
+    These define how Salesforce obtains and refreshes tokens
+    -->
+    <externalCredentialParameters>
+        <parameterName>clientId</parameterName>
+        <parameterType>AuthProviderClientId</parameterType>
+        <parameterValue>{{ClientId}}</parameterValue>
+    </externalCredentialParameters>
+
+    <externalCredentialParameters>
+        <parameterName>clientSecret</parameterName>
+        <parameterType>AuthProviderClientSecret</parameterType>
+        <!-- Value entered via UI for security -->
+    </externalCredentialParameters>
+
+    <externalCredentialParameters>
+        <parameterName>scope</parameterName>
+        <parameterType>AuthProviderScope</parameterType>
+        <parameterValue>{{Scopes}}</parameterValue>
+    </externalCredentialParameters>
+
+    <externalCredentialParameters>
+        <parameterName>tokenEndpoint</parameterName>
+        <parameterType>AuthProviderTokenEndpoint</parameterType>
+        <parameterValue>{{TokenEndpoint}}</parameterValue>
+    </externalCredentialParameters>
+
+    <!--
+    Named Principal Configuration
+    Shared service account for all users with permission
+    -->
+    <principals>
+        <principalName>{{PrincipalName}}</principalName>
+        <principalType>NamedPrincipal</principalType>
+        <sequenceNumber>1</sequenceNumber>
+    </principals>
+
+    <!--
+    Optional: Per-User Principal
+    Each user authenticates individually
+
+    <principals>
+        <principalName>PerUserPrincipal</principalName>
+        <principalType>PerUserPrincipal</principalType>
+        <sequenceNumber>2</sequenceNumber>
+    </principals>
+    -->
+
+    <!--
+    Permission Set Integration:
+    After deployment, create Permission Set with:
+    - External Credential Principal Access: {{PrincipalName}}
+    - Assign to users who need API access
+    -->
+</ExternalCredential>

package/skills/building-sf-integrations/assets/external-services/external-service-operations.md

@@ -0,0 +1,221 @@
+# External Service Operations Guide
+
+## Overview
+
+External Services in Salesforce auto-generate Apex classes from OpenAPI specifications, providing type-safe API integrations without manual HTTP code.
+
+## Generated Class Structure
+
+When you register an External Service named `MyAPI`, Salesforce generates:
+
+```
+ExternalService.MyAPI                          - Main service class
+ExternalService.MyAPI_operationName_Request    - Request wrapper for each operation
+ExternalService.MyAPI_operationName_Response   - Response wrapper for each operation
+ExternalService.MyAPI_SchemaName               - DTO for each schema in OpenAPI
+```
+
+## Basic Usage
+
+### 1. Instantiate the Service
+
+```apex
+ExternalService.MyAPI api = new ExternalService.MyAPI();
+```
+
+### 2. Call GET Operation
+
+```apex
+// Simple GET with path parameter
+ExternalService.MyAPI_getCustomer_Response response = api.getCustomer('cust_123');
+
+// Access response data
+String customerId = response.id;
+String customerName = response.name;
+```
+
+### 3. Call POST Operation
+
+```apex
+// Create request object
+ExternalService.MyAPI_createCustomer_Request request =
+    new ExternalService.MyAPI_createCustomer_Request();
+request.name = 'Acme Corp';
+request.email = 'contact@acme.com';
+
+// Make the call
+ExternalService.MyAPI_createCustomer_Response response = api.createCustomer(request);
+
+// Access created resource
+String newCustomerId = response.id;
+```
+
+### 4. Call PUT/PATCH Operations
+
+```apex
+// Update request
+ExternalService.MyAPI_updateCustomer_Request request =
+    new ExternalService.MyAPI_updateCustomer_Request();
+request.customerId = 'cust_123';  // Path parameter
+request.name = 'Acme Corporation';  // Body field
+
+ExternalService.MyAPI_updateCustomer_Response response = api.updateCustomer(request);
+```
+
+### 5. Call DELETE Operation
+
+```apex
+// DELETE usually returns void or simple confirmation
+api.deleteCustomer('cust_123');
+```
+
+## Error Handling
+
+```apex
+try {
+    ExternalService.MyAPI api = new ExternalService.MyAPI();
+    ExternalService.MyAPI_getCustomer_Response response = api.getCustomer('invalid_id');
+
+} catch (ExternalService.ExternalServiceException e) {
+    // API returned error status code
+    System.debug('API Error: ' + e.getMessage());
+    System.debug('Status Code: ' + e.getStatusCode());
+    System.debug('Response Body: ' + e.getBody());
+
+} catch (CalloutException e) {
+    // Network/connection error
+    System.debug('Callout failed: ' + e.getMessage());
+}
+```
+
+## Async Usage (Queueable)
+
+External Service calls are still callouts, so use Queueable for trigger contexts:
+
+```apex
+public class CustomerSyncQueueable implements Queueable, Database.AllowsCallouts {
+
+    private List<Account> accounts;
+
+    public CustomerSyncQueueable(List<Account> accounts) {
+        this.accounts = accounts;
+    }
+
+    public void execute(QueueableContext context) {
+        ExternalService.MyAPI api = new ExternalService.MyAPI();
+
+        for (Account acc : accounts) {
+            try {
+                ExternalService.MyAPI_createCustomer_Request req =
+                    new ExternalService.MyAPI_createCustomer_Request();
+                req.name = acc.Name;
+                req.email = acc.Email__c;
+
+                ExternalService.MyAPI_createCustomer_Response resp =
+                    api.createCustomer(req);
+
+                // Store external ID on Account
+                acc.External_Customer_Id__c = resp.id;
+
+            } catch (Exception e) {
+                System.debug('Sync failed for ' + acc.Name + ': ' + e.getMessage());
+            }
+        }
+
+        update accounts;
+    }
+}
+```
+
+## OpenAPI Schema Tips
+
+### Required Properties
+
+```json
+{
+  "components": {
+    "schemas": {
+      "Customer": {
+        "type": "object",
+        "required": ["name", "email"],
+        "properties": {
+          "name": { "type": "string" },
+          "email": { "type": "string", "format": "email" }
+        }
+      }
+    }
+  }
+}
+```
+
+### Nested Objects
+
+```json
+{
+  "Customer": {
+    "type": "object",
+    "properties": {
+      "address": {
+        "$ref": "#/components/schemas/Address"
+      }
+    }
+  },
+  "Address": {
+    "type": "object",
+    "properties": {
+      "street": { "type": "string" },
+      "city": { "type": "string" }
+    }
+  }
+}
+```
+
+### Arrays
+
+```json
+{
+  "CustomerList": {
+    "type": "object",
+    "properties": {
+      "customers": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/Customer"
+        }
+      }
+    }
+  }
+}
+```
+
+## Limitations
+
+| Limitation | Workaround |
+|------------|------------|
+| 100 callouts per transaction | Use async (Queueable) with chaining |
+| 120s max timeout | Use shorter timeout, implement retry |
+| 6MB response size | Paginate responses, compress data |
+| Some OpenAPI features not supported | Simplify schema, avoid oneOf/anyOf |
+
+## Refreshing External Service
+
+When the API schema changes:
+
+1. Download updated OpenAPI spec
+2. Go to Setup → External Services
+3. Edit the service
+4. Upload new schema
+5. Review generated operations
+6. Save and validate
+
+Or via metadata deployment:
+1. Update the `<schema>` content in the `.externalServiceRegistration-meta.xml`
+2. Deploy with `sf project deploy start`
+
+## Best Practices
+
+1. **Version Your APIs**: Include version in Named Credential endpoint
+2. **Handle All Errors**: Catch both `ExternalServiceException` and `CalloutException`
+3. **Log Requests/Responses**: For debugging production issues
+4. **Use Async**: Always use Queueable when called from DML contexts
+5. **Test Thoroughly**: Mock External Service calls in test classes

package/skills/building-sf-integrations/assets/external-services/openapi-registration.externalServiceRegistration-meta.xml

@@ -0,0 +1,193 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    External Service Registration Template: OpenAPI/Swagger
+
+    Use Case: Auto-generate Apex from OpenAPI specification
+    - REST API integrations
+    - Type-safe API calls
+    - Automatic request/response serialization
+
+    Supported Schema Types:
+    - OpenApi3 (OpenAPI 3.0.x) - RECOMMENDED
+    - OpenApi (OpenAPI 2.0 / Swagger)
+
+    Prerequisites:
+    1. Named Credential configured for authentication
+    2. Valid OpenAPI specification (JSON or YAML)
+
+    Setup Steps:
+    1. Replace {{placeholder}} values
+    2. Embed OpenAPI schema OR reference URL
+    3. Deploy to org
+    4. Use generated Apex classes: ExternalService.{{ServiceName}}
+
+    File Location: force-app/main/default/externalServiceRegistrations/{{ServiceName}}.externalServiceRegistration-meta.xml
+-->
+<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Display name in Setup -->
+    <label>{{ServiceLabel}}</label>
+
+    <!-- Description of the service -->
+    <description>{{ServiceDescription}}</description>
+
+    <!--
+    Named Credential for authentication
+    Must be deployed BEFORE this External Service
+    -->
+    <namedCredential>{{NamedCredentialName}}</namedCredential>
+
+    <!--
+    Schema Type: OpenApi3 or OpenApi (2.0)
+    OpenAPI 3.0 is recommended for new integrations
+    -->
+    <schemaType>OpenApi3</schemaType>
+
+    <!--
+    Status: Complete, Draft, or Invalid
+    Set to Complete for production use
+    -->
+    <status>Complete</status>
+
+    <!--
+    OpenAPI Schema Content
+    Embed the full OpenAPI JSON schema here
+    OR use schemaUrl to reference external URL
+
+    Example minimal OpenAPI 3.0 schema:
+    -->
+    <schema>
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "{{ServiceTitle}}",
+    "version": "1.0.0",
+    "description": "{{ServiceDescription}}"
+  },
+  "servers": [
+    {
+      "url": "{{BaseUrl}}"
+    }
+  ],
+  "paths": {
+    "/{{resourcePath}}": {
+      "get": {
+        "operationId": "get{{ResourceName}}",
+        "summary": "Get {{ResourceName}}",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/{{ResourceName}}"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "create{{ResourceName}}",
+        "summary": "Create {{ResourceName}}",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/{{ResourceName}}Input"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/{{ResourceName}}"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "{{ResourceName}}": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "{{ResourceName}}Input": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}
+    </schema>
+
+    <!--
+    Alternative: Reference schema from URL
+    <schemaUrl>https://api.example.com/openapi.json</schemaUrl>
+    -->
+
+    <!--
+    Operations configuration
+    Define which operations to include/exclude
+    -->
+    <operations>
+        <active>true</active>
+        <name>get{{ResourceName}}</name>
+    </operations>
+    <operations>
+        <active>true</active>
+        <name>create{{ResourceName}}</name>
+    </operations>
+
+    <!--
+    Generated Apex Usage:
+
+    // Get instance of the service
+    ExternalService.{{ServiceName}} service = new ExternalService.{{ServiceName}}();
+
+    // Call GET operation
+    ExternalService.{{ServiceName}}_get{{ResourceName}}_Response resp =
+        service.get{{ResourceName}}('record-id-123');
+
+    // Call POST operation
+    ExternalService.{{ServiceName}}_create{{ResourceName}}_Request req =
+        new ExternalService.{{ServiceName}}_create{{ResourceName}}_Request();
+    req.name = 'New Item';
+    ExternalService.{{ServiceName}}_create{{ResourceName}}_Response resp =
+        service.create{{ResourceName}}(req);
+    -->
+</ExternalServiceRegistration>

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

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Named Credential Template: Certificate-Based Authentication (Mutual TLS)
+
+    Use Case: High-security integrations requiring client certificate
+    - Financial services APIs
+    - Government integrations
+    - Healthcare systems (HIPAA compliance)
+    - Any API requiring mutual TLS (mTLS)
+
+    Prerequisites:
+    1. Obtain client certificate from external system or CA
+    2. Import certificate to Setup → Certificate and Key Management
+    3. Ensure external system trusts Salesforce's certificate
+
+    Setup Steps:
+    1. Replace all {{placeholder}} values
+    2. Upload certificate to Salesforce
+    3. Deploy to org
+    4. Test connection
+
+    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 (must be HTTPS) -->
+    <endpoint>{{BaseEndpoint}}</endpoint>
+
+    <!-- Authentication Configuration -->
+    <principalType>Anonymous</principalType>
+    <protocol>NoAuthentication</protocol>
+
+    <!--
+    Client Certificate for Mutual TLS
+    Certificate must be imported in Setup → Certificate and Key Management
+    The certificate's private key is used to authenticate the client
+    -->
+    <certificate>{{CertificateName}}</certificate>
+
+    <!-- Request Options -->
+    <generateAuthorizationHeader>false</generateAuthorizationHeader>
+    <allowMergeFieldsInBody>true</allowMergeFieldsInBody>
+    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
+
+    <!--
+    Mutual TLS Flow:
+    1. Salesforce initiates HTTPS connection
+    2. External server presents its certificate
+    3. Salesforce validates server certificate
+    4. Salesforce presents client certificate
+    5. External server validates Salesforce's certificate
+    6. Encrypted channel established
+    7. API requests proceed
+
+    IMPORTANT:
+    - Certificate must have valid chain to trusted CA
+    - Certificate must not be expired
+    - External system must have Salesforce's public cert in truststore
+    -->
+</NamedCredential>