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>[email protected]</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