Sf Integration

Salesforce Integration Configuration & Architecture

You are a Salesforce integration architect. Configure integration infrastructure -- Named Credentials, Connected Apps, External Services, Platform Events, CDC, and auth flows. Focus on metadata setup, security configuration, and architecture decisions.

Scope boundary: This skill covers integration configuration and metadata. For Apex callout code patterns (HttpRequest, @RestResource, SOAP, mocks), see sf-apex integration patterns.

1. Named Credentials

Named Credentials abstract endpoint URLs and authentication from code. Two architectures exist.

Legacy Named Credentials

Single metadata file combining endpoint + auth. Still supported but limited.

<!-- MyService.namedCredential-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>MyService</fullName>
    <label>My Service</label>
    <endpoint>https://api.example.com</endpoint>
    <principalType>NamedUser</principalType>
    <protocol>Password</protocol>
    <username>api_user</username>
    <!-- Password stored in org, not in metadata file -->
</NamedCredential>

Legacy protocol values: Password, Oauth, Jwt, JwtExchange, AwsSv4, NoAuthentication.

Enhanced Named Credentials (Preferred)

Separates concerns into two metadata types:

Enhanced Named Credential referencing an External Credential:

<!-- MyService.namedCredential-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>MyService</fullName>
    <label>My Service</label>
    <endpoint>https://api.example.com</endpoint>
    <externalCredential>MyService_Auth</externalCredential>
    <generateAuthorizationHeader>true</generateAuthorizationHeader>
    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
</NamedCredential>

External Credential with OAuth Client Credentials:

<!-- MyService_Auth.externalCredential-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>MyService_Auth</fullName>
    <label>My Service Auth</label>
    <authenticationProtocol>Oauth</authenticationProtocol>
    <externalCredentialParameters>
        <parameterName>ClientId</parameterName>
        <parameterType>AuthProviderUrl</parameterType>
        <parameterValue>YOUR_CLIENT_ID</parameterValue>
    </externalCredentialParameters>
    <externalCredentialParameters>
        <parameterName>Scope</parameterName>
        <parameterType>AuthParameter</parameterType>
        <parameterValue>api read</parameterValue>
    </externalCredentialParameters>
    <principals>
        <principalName>MyServicePrincipal</principalName>
        <principalType>NamedPrincipal</principalType>
        <sequenceNumber>1</sequenceNumber>
    </principals>
</ExternalCredential>

Permission Set Mapping for External Credentials

Users access External Credentials through Permission Set mappings. Without this, callouts fail with NAMED_CREDENTIAL_NOT_FOUND.

<!-- In a Permission Set -->
<externalCredentialPrincipalAccesses>
    <enabled>true</enabled>
    <externalCredentialPrincipal>MyService_Auth - MyServicePrincipal</externalCredentialPrincipal>
</externalCredentialPrincipalAccesses>

When to Use Each

---

2. Connected Apps

Connected Apps define OAuth client configuration for external applications accessing Salesforce, or for Salesforce-to-Salesforce auth.

Connected App Metadata

<!-- MyConnectedApp.connectedApp-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>MyConnectedApp</fullName>
    <label>My Connected App</label>
    <contactEmail>admin@example.com</contactEmail>
    <oauthConfig>
        <callbackUrl>https://myapp.example.com/callback</callbackUrl>
        <certificate>MyCertificateName</certificate>
        <consumerKey>WILL_BE_GENERATED</consumerKey>
        <isAdminApproved>true</isAdminApproved>
        <isConsumerSecretOptional>false</isConsumerSecretOptional>
        <scopes>Api</scopes>
        <scopes>RefreshToken</scopes>
        <scopes>OfflineAccess</scopes>
    </oauthConfig>
    <oauthPolicy>
        <ipRelaxation>ENFORCE</ipRelaxation>
        <refreshTokenPolicy>SPECIFIC_LIFETIME</refreshTokenPolicy>
        <refreshTokenValidityPeriod>720</refreshTokenValidityPeriod>
        <refreshTokenValidityUnits>HOURS</refreshTokenValidityUnits>
    </oauthPolicy>
</ConnectedApp>

OAuth Scopes Reference

JWT Bearer Flow Setup

For server-to-server with no interactive login:

1. Generate X.509 certificate and upload to Connected App 2. Pre-authorize the Connected App for the integration user's profile 3. Set isAdminApproved to true 4. Consumer sends JWT signed with private key to token endpoint 5. Token endpoint: https://login.salesforce.com/services/oauth2/token

Grant type: urn:ietf:params:oauth:grant-type:jwt-bearer

Web Server Flow Setup

For user-facing applications:

1. Configure callback URL (must be HTTPS, exact match) 2. Set appropriate scopes (avoid Full) 3. Set IP relaxation policy based on security requirements 4. Configure refresh token lifetime

IP Relaxation Options

---

3. External Services

External Services let you register an OpenAPI spec and auto-generate invocable actions usable in Flow, Einstein Bots, and Apex.

Registration Steps

1. Create a Named Credential for the external API endpoint 2. Navigate to Setup > External Services 3. Provide the OpenAPI (Swagger) spec -- URL or paste JSON/YAML 4. Salesforce parses operations and generates invocable actions

Requirements and Constraints

• OpenAPI 3.0 only (2.0/Swagger not supported for new registrations)
• Spec size limit: 100 KB
• Max 50 operations per registration
• All operations use the Named Credential for auth
• Generated actions appear as Flow External Service actions
• Supported HTTP methods: GET, POST, PUT, PATCH, DELETE

Using External Service in Flow

After registration, each operation becomes an invocable action:

1. In Flow Builder, add an Action element 2. Filter by category "External Services" 3. Select the operation (e.g., createOrder, getCustomer) 4. Map Flow variables to input/output parameters 5. The Named Credential handles authentication automatically

External Service Metadata

<!-- MyExternalService.externalServiceRegistration-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>MyExternalService</fullName>
    <label>My External Service</label>
    <namedCredential>MyService</namedCredential>
    <schema>--- OpenAPI JSON spec inlined or referenced ---</schema>
    <schemaType>OpenApi3</schemaType>
    <serviceBinding>
        <fieldName>operationName</fieldName>
        <value>createOrder</value>
    </serviceBinding>
    <status>Complete</status>
</ExternalServiceRegistration>

---

4. Platform Events

Custom event bus for decoupled, event-driven integration within Salesforce and with external systems.

Event Definition

<!-- Order_Event__e.object-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Order_Event__e</fullName>
    <label>Order Event</label>
    <pluralLabel>Order Events</pluralLabel>
    <publishBehavior>PublishAfterCommit</publishBehavior>
    <fields>
        <fullName>Order_Id__c</fullName>
        <label>Order Id</label>
        <type>Text</type>
        <length>18</length>
    </fields>
    <fields>
        <fullName>Action__c</fullName>
        <label>Action</label>
        <type>Text</type>
        <length>50</length>
    </fields>
    <fields>
        <fullName>Payload__c</fullName>
        <label>Payload</label>
        <type>LongTextArea</type>
        <length>131072</length>
        <visibleLines>5</visibleLines>
    </fields>
</CustomObject>

Publish Behavior

Key rule: PublishAfterCommit events do not fire if the transaction rolls back. PublishImmediately events fire regardless -- use cautiously.

Subscriber Patterns

• Apex Trigger: trigger OrderEventTrigger on Order_Event__e (after insert) -- runs in its own execution context
• Flow: Use a Platform Event-Triggered Flow (Record-Triggered flows cannot subscribe)
• External: CometD or Pub/Sub API (gRPC) for external system subscribers

Replay and Retention

• Standard Platform Events: retained 24 hours, replayable via Replay ID
• High-Volume Platform Events: retained 72 hours, higher throughput (150K/hour)
• Use ReplayId in CometD or Pub/Sub API to resume from a specific point after subscriber failure
• Subscribers can set replay position: -1 (tip), -2 (all retained events), or a specific Replay ID

---

5. Change Data Capture (CDC)

Streams record changes (create, update, delete, undelete) as events on the event bus.

Enabling CDC

1. Setup > Change Data Capture 2. Select objects to track (standard or custom) 3. Changes publish to channels: /data/<ObjectName>ChangeEvent (e.g., /data/AccountChangeEvent)

For custom objects: /data/<CustomObject__c>ChangeEvent becomes /data/Custom_Object__ChangeEvent

ChangeEventHeader Fields

Every CDC event includes a header with change metadata:

CDC Subscriber Trigger

trigger AccountChangeEventTrigger on AccountChangeEvent (after insert) {
    for (AccountChangeEvent event : Trigger.new) {
        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
        String changeType = header.getChangeType();
        List<String> changedFields = header.getChangedFields();

        if (changeType == 'UPDATE' && changedFields.contains('Rating')) {
            // React to Rating field changes
            for (String recordId : header.getRecordIds()) {
                // Queue processing for each changed record
            }
        }
    }
}

CDC vs Platform Events

---

6. Outbound Messaging (Legacy)

SOAP-based outbound notifications triggered by Workflow Rules. Legacy pattern -- prefer Platform Events for new work.

• Fires from Workflow Rules only (not Process Builder or Flow)
• SOAP format, automatic retry with exponential backoff for 24 hours
• Endpoint must respond with Ack ID; retries until acknowledged or 24h timeout
• Max 100 fields per message
• Migrate to: Platform Events (decoupled pub/sub), Flow + HTTP Callout (declarative), or Apex Callout (complex request/response)

---

7. Remote Site Settings vs Named Credentials

Migration Path

Remote Site Settings only whitelist an endpoint URL. Named Credentials add auth management on top.

Migration steps: 1. Create Named Credential with the Remote Site URL as endpoint 2. Configure auth protocol (OAuth, Password, JWT, etc.) 3. Update Apex code: replace hardcoded endpoint with callout:NamedCredentialName 4. Remove auth header construction from code 5. Delete the Remote Site Setting 6. Test in sandbox before production

---

8. Auth Flow Decision Guide

Decision Rules

1. No user context needed? Use Client Credentials (if available) or JWT Bearer 2. Backend service? JWT Bearer with X.509 certificate 3. User-facing web app? Web Server flow 4. Public client (SPA/mobile)? Auth Code + PKCE (mandatory) 5. No browser? Device Flow 6. Long-lived access? Add RefreshToken / OfflineAccess scope

---

9. Gotchas

Named Credentials

• Max 100 callouts per synchronous transaction (shared with all HTTP requests)
• Enhanced Named Credentials require Permission Set mapping or callout silently fails
• External Credential parameter names are case-sensitive
• generateAuthorizationHeader must be true for automatic OAuth header injection

Platform Events

• 150,000 events/hour publish limit (high-volume); 50,000 for standard
• PublishAfterCommit events lost if transaction rolls back -- no retry
• At-least-once delivery: subscribers must be idempotent
• Subscriber trigger failures cause automatic retry (up to 8 retries with backoff)
• EventBus.publish() does not throw exceptions -- check SaveResult for errors

Change Data Capture

• 72-hour replay window -- events older than 72h are lost
• CDC events do not fire for bulk API operations by default (must enable)
• Large transaction changes may be split across multiple events (check sequenceNumber)
• Not available for all standard objects -- check Salesforce documentation

External Services

• OpenAPI 3.0 only -- Swagger 2.0 specs must be converted
• 100 KB spec size limit
• Max 50 operations per registration
• Complex nested schemas may not parse correctly -- flatten where possible

Connected Apps

• Consumer key/secret generated on creation -- cannot be set via metadata
• Admin approval required for JWT Bearer and Client Credentials flows
• Certificate expiry causes silent auth failures -- monitor and rotate
• IP relaxation policy applies to the Connected App, not the user's IP restrictions
• Changes to Connected App take up to 10 minutes to propagate

General

• Cannot mix synchronous callouts and DML in the same transaction without careful ordering (callout before DML, or use @future/Queueable)
• Callout timeout max: 120 seconds per request, 120 seconds total per transaction

---

Workflow

1. Identify the integration pattern using the decision guides above 2. Use Glob and Grep to find existing integration metadata in the project 3. Generate or update Named Credential / External Credential / Connected App metadata 4. Configure Platform Events or CDC if event-driven 5. Set up External Services if spec-driven 6. Verify Permission Set mappings for External Credentials 7. Suggest deployment: sf project deploy start -d force-app/main/default/namedCredentials/

References

• Integration Reference -- metadata XML templates, auth flow details, architecture decision guides
• Apex Integration Patterns -- callout code, @RestResource, SOAP, mocks (separate skill)
• Governor Limits -- per-transaction limits

Integration Configuration Reference

Metadata XML templates, auth flow details, and architecture decision guides for Salesforce integration setup.

Scope: This file covers configuration and metadata. For Apex callout code patterns, see integration-patterns.md.

---

1. Named Credential XML Templates

Legacy Named Credential -- Password Auth

<?xml version="1.0" encoding="UTF-8"?>
<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Legacy_Service</fullName>
    <label>Legacy Service</label>
    <endpoint>https://api.example.com/v1</endpoint>
    <principalType>NamedUser</principalType>
    <protocol>Password</protocol>
    <username>service_account</username>
</NamedCredential>

Legacy protocol values: Password, Oauth, Jwt, JwtExchange, AwsSv4, NoAuthentication. For no-auth (URL whitelisting only), set principalType to Anonymous and protocol to NoAuthentication.

Enhanced Named Credential

<?xml version="1.0" encoding="UTF-8"?>
<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Enhanced_Service</fullName>
    <label>Enhanced Service</label>
    <endpoint>https://api.example.com/v2</endpoint>
    <externalCredential>Enhanced_Service_Auth</externalCredential>
    <generateAuthorizationHeader>true</generateAuthorizationHeader>
    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
</NamedCredential>

---

2. External Credential XML with Permission Set Mapping

OAuth External Credential

<?xml version="1.0" encoding="UTF-8"?>
<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Service_OAuth</fullName>
    <label>Service OAuth</label>
    <authenticationProtocol>Oauth</authenticationProtocol>
    <externalCredentialParameters>
        <parameterName>ClientId</parameterName>
        <parameterType>AuthProviderUrl</parameterType>
        <parameterValue>your_client_id</parameterValue>
    </externalCredentialParameters>
    <externalCredentialParameters>
        <parameterName>TokenUrl</parameterName>
        <parameterType>AuthProviderUrl</parameterType>
        <parameterValue>https://auth.example.com/oauth2/token</parameterValue>
    </externalCredentialParameters>
    <externalCredentialParameters>
        <parameterName>Scope</parameterName>
        <parameterType>AuthParameter</parameterType>
        <parameterValue>api read</parameterValue>
    </externalCredentialParameters>
    <principals>
        <principalName>ServicePrincipal</principalName>
        <principalType>NamedPrincipal</principalType>
        <sequenceNumber>1</sequenceNumber>
    </principals>
</ExternalCredential>

For custom header auth (e.g., API key), use authenticationProtocol Custom with parameterType AuthHeader.

Permission Set Mapping (Required)

<!-- In a Permission Set -->
<externalCredentialPrincipalAccesses>
    <enabled>true</enabled>
    <externalCredentialPrincipal>Service_OAuth - ServicePrincipal</externalCredentialPrincipal>
</externalCredentialPrincipalAccesses>

Format: <ExternalCredentialName> - <PrincipalName>. Missing this mapping causes NAMED_CREDENTIAL_NOT_FOUND at runtime.

---

3. Connected App Metadata XML

Standard OAuth Connected App

<?xml version="1.0" encoding="UTF-8"?>
<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>MyWebApp</fullName>
    <label>My Web App</label>
    <contactEmail>admin@example.com</contactEmail>
    <oauthConfig>
        <callbackUrl>https://myapp.example.com/oauth/callback</callbackUrl>
        <consumerKey>AUTO_GENERATED</consumerKey>
        <isAdminApproved>false</isAdminApproved>
        <isConsumerSecretOptional>false</isConsumerSecretOptional>
        <scopes>Api</scopes>
        <scopes>RefreshToken</scopes>
    </oauthConfig>
    <oauthPolicy>
        <ipRelaxation>ENFORCE</ipRelaxation>
        <refreshTokenPolicy>SPECIFIC_LIFETIME</refreshTokenPolicy>
        <refreshTokenValidityPeriod>720</refreshTokenValidityPeriod>
        <refreshTokenValidityUnits>HOURS</refreshTokenValidityUnits>
    </oauthPolicy>
</ConnectedApp>

JWT Bearer Differences

Add <certificate>JWTSigningCert</certificate> in oauthConfig. Set isAdminApproved to true and isConsumerSecretOptional to true.

Client Credentials Differences

Add <isClientCredentialFlowEnabled>true</isClientCredentialFlowEnabled> in oauthConfig. Set isAdminApproved to true. Set refreshTokenPolicy to IMMEDIATE_EXPIRATION. Requires assigning a run-as user in Setup.

---

4. External Service Registration

Steps

1. Prepare OpenAPI 3.0 spec (JSON or YAML, max 100 KB) 2. Create Named Credential for the API base URL 3. Setup > External Services > New External Service 4. Provide spec (paste, upload, or URL) and review parsed operations 5. Save -- invocable actions are generated for use in Flows

Metadata

<?xml version="1.0" encoding="UTF-8"?>
<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>OrderService</fullName>
    <label>Order Service</label>
    <namedCredential>Order_API</namedCredential>
    <schema>{... OpenAPI 3.0 JSON ...}</schema>
    <schemaType>OpenApi3</schemaType>
    <status>Complete</status>
</ExternalServiceRegistration>

OpenAPI Spec Tips

• Keep schemas flat -- deeply nested objects may fail parsing
• Define operationId for each endpoint (used as the Flow action name)
• Auth defined in spec is ignored -- Salesforce uses the Named Credential
• Polymorphic schemas (oneOf, anyOf) may not parse correctly

---

5. Platform Event Definition XML

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Integration_Event__e</fullName>
    <label>Integration Event</label>
    <pluralLabel>Integration Events</pluralLabel>
    <publishBehavior>PublishAfterCommit</publishBehavior>
    <fields>
        <fullName>Event_Type__c</fullName>
        <label>Event Type</label>
        <type>Text</type>
        <length>50</length>
    </fields>
    <fields>
        <fullName>Payload__c</fullName>
        <label>Payload</label>
        <type>LongTextArea</type>
        <length>131072</length>
        <visibleLines>5</visibleLines>
    </fields>
</CustomObject>

Subscriber Error Handling

trigger IntegrationEventTrigger on Integration_Event__e (after insert) {
    for (Integration_Event__e event : Trigger.new) {
        try {
            IntegrationEventHandler.process(event);
        } catch (Exception e) {
            // Set checkpoint to prevent infinite retry loop
            EventBus.TriggerContext.currentContext().setResumeCheckpoint(event.ReplayId);
        }
    }
}

Publishing from Flow: use a "Create Records" element targeting the Platform Event object.

---

6. CDC Enablement and Subscriber Trigger

Enabling via Metadata

<ChangeDataCaptureSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableChangeDataCapture>true</enableChangeDataCapture>
    <selectedEntities>Account</selectedEntities>
    <selectedEntities>Contact</selectedEntities>
</ChangeDataCaptureSettings>

Subscriber Pattern

trigger AccountCDCTrigger on AccountChangeEvent (after insert) {
    for (AccountChangeEvent event : Trigger.new) {
        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
        switch on header.getChangeType() {
            when 'CREATE' {
                // Handle new records -- header.getRecordIds() has the IDs
            }
            when 'UPDATE' {
                if (header.getChangedFields().contains('OwnerId')) {
                    // React to ownership changes
                }
            }
            when 'DELETE' {
                // Audit deletion
            }
        }
    }
}

CDC Channels

---

7. Auth Flow Comparison (Detailed)

Token Endpoint URLs

---

8. Callout Limits

For retry patterns using Queueable with backoff, see integration-patterns.md.

---

9. Middleware Patterns

When to Use Middleware

Common Platforms

Architecture Pattern

Outbound: Salesforce Platform Event --> Pub/Sub API --> Middleware --> External System
Inbound:  External System --> Middleware --> Salesforce REST API (via Connected App)

Keep business logic in Salesforce. Middleware handles routing, retry, circuit breaking, and transformation.

---

10. Event-Driven Architecture Decision Guide

Choosing the Right Mechanism

Need to react to record changes?
  --> Yes: Change Data Capture (CDC)
  --> No: Need decoupled pub/sub?
      --> Yes: Platform Events
      --> No: Direct callout or Flow HTTP action

Comparison

Combining Patterns

• CDC + Platform Events: CDC captures changes; Platform Events notify across boundaries
• Platform Events + Middleware: Events decouple Salesforce; middleware routes externally
• Named Credentials + External Services: auth + auto-generated Flow actions
• Connected App + Named Credential: OAuth client definition + outbound callout credential