Sf Integration

# 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](../../sf-apex/references/integration-patterns.md).

---

## 1. Named Credential XML Templates

### Legacy Named Credential -- Password Auth

```xml
<?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
<?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
<?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)

```xml
<!-- 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
<?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>