DataSourceBundleDefinition in SFDX

Architectural Overview#

The DataSourceBundleDefinition metadata type represents a curated bundle of data stream blueprints and schema mappings within Salesforce Data Cloud. Configuring ingestion pipelines individually for complex enterprise domains (such as Service Cloud, B2C Commerce, or Financial Services Cloud) requires defining dozens of interrelated tables, primary keys, and data model mappings.

DataSourceBundleDefinition encapsulates these interdependent stream templates into a turnkey, single-click activation bundle. When an administrator or automated CI/CD pipeline deploys and selects a bundle, Data Cloud automatically generates the necessary Data Lake Objects (DLOs), applies standard field mapping transformations, and schedules batch or real-time sync jobs without requiring manual field-by-field configuration.

Directory and File Suffix Conventions#

In SFDX source format, DataSourceBundleDefinition metadata files reside in the dataSourceBundleDefinitions directory:

Key Metadata Fields#

Declarative XML and Manifest Examples#

Source Format XML (Service_Operations_Bundle.dataSourceBundleDefinition-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<DataSourceBundleDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Service_Operations_Bundle</developerName>
    <masterLabel>Service Operations Data Bundle</masterLabel>
    <bundleType>Service</bundleType>
    <isStandard>false</isStandard>
    <version>2.0</version>
</DataSourceBundleDefinition>

Manifest (package.xml)#

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

Retrieval and Deployment Commands#

Use the Salesforce CLI to retrieve and deploy DataSourceBundleDefinition metadata:

# Retrieve all Data Source Bundle definitions
sf project retrieve start --metadata DataSourceBundleDefinition

# Retrieve a specific bundle definition by developer name
sf project retrieve start --metadata DataSourceBundleDefinition:Service_Operations_Bundle

# Deploy bundle definition metadata to the target environment
sf project deploy start --metadata DataSourceBundleDefinition:Service_Operations_Bundle

Senior Architect Best Practices and Gotchas#

• Streamline Onboarding: Use custom bundle definitions when implementing horizontal template rollouts across multi-org architectures (e.g., regional operating companies) to guarantee uniform field mappings.
• Custom Field Inclusion: Verify that all referenced custom fields on standard CRM objects exist in the subscriber org prior to deploying bundles; missing source fields prevent successful stream initialization.
• Data Kit Composition: Integrate DataSourceBundleDefinition into your DataPackageKitDefinition packages to provide end users with pre-packaged data bundles during kit installation.

Frequently asked questions

What is the purpose of DataSourceBundleDefinition?

It bundles multiple pre-configured data streams and schema mappings into an automated one-click ingestion package for standard connectors.

Where are DataSourceBundleDefinition files stored in SFDX?

They are stored in force-app/main/default/dataSourceBundleDefinitions/ with the file suffix .dataSourceBundleDefinition-meta.xml.

What is an example of a Data Source Bundle?

Examples include standard CRM Service bundles that ingest Cases, Accounts, and Contacts with automated field mappings out of the box.

How do you retrieve DataSourceBundleDefinition metadata?

Execute sf project retrieve start with the metadata flag DataSourceBundleDefinition.