ExternalDataConnector in Salesforce Metadata API

Architectural Overview#

ExternalDataConnector metadata represents the infrastructure boundary connecting Salesforce Data Cloud, CRM Analytics, and Salesforce Connect to external storage repositories and relational databases. In modern enterprise lakehouse architectures, ingesting massive datasets or executing zero-copy federated queries requires robust, auditable connectivity definitions.

Rather than storing hardcoded credentials inside batch jobs or custom code, ExternalDataConnector decouples connectivity metadata from pipeline logic. It standardises how Salesforce establishes TLS handshakes, authenticates via cloud IAM policies (such as AWS IAM role assumption or Azure Managed Identities), and governs data read throughput.

From an architectural governance perspective, ExternalDataConnector assets must be version-controlled and deployed across sandbox tiers before data transformation pipelines (ExternalDataTranObject) and data streams can be scheduled.

Directory and File Conventions#

ExternalDataConnector files follow standard SFDX directory conventions in the externalDataConnectors folder:

Key Metadata Fields#

The ExternalDataConnector schema specifies connection protocols, authentication types, and endpoint properties:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition of an ExternalDataConnector linking Salesforce Data Cloud to an enterprise AWS S3 bucket:

<?xml version="1.0" encoding="UTF-8"?>
<ExternalDataConnector xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Enterprise_DataLake_S3</developerName>
    <masterLabel>Enterprise DataLake S3</masterLabel>
    <connectorType>S3</connectorType>
    <authType>AwsIamRole</authType>
    <description>Federated S3 connector for enterprise customer event lakehouse</description>
    <connectionProperties>
        <propertyName>BucketName</propertyName>
        <propertyValue>prod-enterprise-customer-lakehouse</propertyValue>
    </connectionProperties>
    <connectionProperties>
        <propertyName>AwsRegion</propertyName>
        <propertyValue>us-east-1</propertyValue>
    </connectionProperties>
    <connectionProperties>
        <propertyName>RoleArn</propertyName>
        <propertyValue>arn:aws:iam::123456789012:role/SalesforceDataCloudIngestionRole</propertyValue>
    </connectionProperties>
</ExternalDataConnector>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Enterprise_DataLake_S3</members>
        <name>ExternalDataConnector</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Retrieve and deploy ExternalDataConnector metadata using the Salesforce CLI:

# Retrieve a specific external data connector
sf project retrieve start --metadata ExternalDataConnector:Enterprise_DataLake_S3

# Deploy all external data connectors to target environment
sf project deploy start --metadata ExternalDataConnector

# Validate connector metadata without committing changes
sf project deploy start --metadata ExternalDataConnector --dry-run

Architect Best Practices and Gotchas#

• Cross-Account Trust Policies: When configuring AWS IAM Role authentication (AwsIamRole), Salesforce generates a dynamic external ID and tenant role ARN during initial connector verification in the UI. Ensure trust policies on the external cloud provider permit access from Salesforce Data Cloud IP ranges.
• Environment Parity and Endpoint Drift: Avoid hardcoding production bucket names or staging databases in version-controlled connector metadata. Use SFDX environment variables or token replacement scripts in CI/CD pipelines to swap bucket ARNs across dev, staging, and production orgs.
• Dependency Hierarchy: Downstream transformation objects (ExternalDataTranObject) and Data Model Objects (DMOs) directly reference ExternalDataConnector. If you attempt to delete or rename a connector without migrating downstream objects, deployments will be rejected.

Frequently asked questions

What role does ExternalDataConnector play in Salesforce architecture?

ExternalDataConnector defines secure connection configurations and credentials between Salesforce Data Cloud or CRM Analytics and third-party data repositories like AWS S3 or Snowflake.

How does ExternalDataConnector authenticate with remote data platforms?

It supports multiple authentication schemes including AWS IAM Role ARNs, OAuth tokens, and Named Credentials to establish secure zero-copy or scheduled data ingestion pipelines.

Where is ExternalDataConnector metadata stored in an SFDX project?

It is stored in the externalDataConnectors directory with the externalDataConnector-meta.xml file extension.

What happens if an ExternalDataConnector credential expires in production?

Scheduled data ingestion streams and federated zero-copy queries fail until updated credentials or IAM role permissions are refreshed in the connector definition.