CleanDataService Metadata Type Architecture

Architectural Overview#

Maintaining accurate firmographic, demographic, and geolocation data on Account, Contact, and Lead records requires continuous background enrichment. The CleanDataService metadata type represents a Data Integration Service (such as built-in Address Geocoding or an installed Lightning Data provider package) along with its embedded cleanRules (CleanRule), field mappings (fieldMappings), and trigger/workflow bypass switches.

For Salesforce Technical Architects, CleanDataService is especially important because of its execution side effects: each nested CleanRule specifies whether background data enrichment bypasses Apex triggers (bypassTriggers) and workflow/Flow rules (bypassWorkflow). Misconfiguring these flags can either cause unexpected governor limit spikes during bulk enrichment or silently skip critical integration triggers.

Directory Location and File Suffix#

In Salesforce DX projects, CleanDataService files are located in the cleanDataServices directory.

Key Metadata Fields#

The following table details the core XML elements of CleanDataService and its nested cleanRules in API version 68.0 (Winter ’27):

Declarative Metadata Example#

The following CleanDataService example illustrates the structure of a geocoding data integration service with an active CleanRule on Account Billing Address that bypasses triggers and workflows during background geocoding updates:

<?xml version="1.0" encoding="UTF-8"?>
<CleanDataService xmlns="http://soap.sforce.com/2006/04/metadata">
    <cleanRules>
        <bulkEnabled>true</bulkEnabled>
        <bypassTriggers>true</bypassTriggers>
        <bypassWorkflow>true</bypassWorkflow>
        <description>Automatically adds latitude, longitude, and geocode accuracy to Account Billing Addresses.</description>
        <developerName>GeoService_AccountBillingAddress_Rule</developerName>
        <enableContinuousClean>false</enableContinuousClean>
        <masterLabel>Geocodes for Account Billing Address</masterLabel>
        <matchRule>GeoLookupMatchRule</matchRule>
        <sourceSobjectType>DataCloudAddress</sourceSobjectType>
        <status>Active</status>
        <targetEntity>Account</targetEntity>
    </cleanRules>
    <description>Platform geocoding data integration service for standard address fields.</description>
    <masterLabel>Data.com GeoLocation Service</masterLabel>
    <matchEngine>GeoLookupEngine</matchEngine>
</CleanDataService>

Package Manifest (package.xml)#

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

SOQL Queries and SFDX CLI Commands#

You can query CleanRule via SOQL to audit which Data Integration Rules are currently active and whether they bypass triggers in your org:

SELECT Id, DeveloperName, MasterLabel, SobjectType, Status,
       DoesBypassTriggers, DoesBypassWorkflow, IsBulkEnabled
FROM CleanRule
ORDER BY SobjectType ASC, DeveloperName ASC

Retrieve and deploy CleanDataService components using the sf CLI:

# Retrieve all CleanDataService configurations from the org
sf project retrieve start --metadata CleanDataService

# Deploy a specific CleanDataService configuration
sf project deploy start --metadata CleanDataService:DataCloudGeoLocation

Architect Best Practices and Gotchas#

• Evaluate bypassTriggers Carefully: Keep <bypassTriggers>true</bypassTriggers> enabled during initial bulk data loads to avoid CPU timeout limits, and only set <bypassTriggers>false</bypassTriggers> if downstream logic explicitly checks for geocode or firmographic field changes and is properly bulkified.
• Mapping Custom Fields: When mapping third-party Lightning Data attributes to custom fields on Account, Contact, or Lead, ensure the target CustomField definitions are deployed in the same package.

Frequently asked questions

What is the role of CleanDataService in Salesforce Data Integration?

CleanDataService represents a data cleansing and enrichment service provider configuration along with itsCleanRule field mappings, which power Data Integration Rules on Account, Contact, and Lead objects.

How does CleanDataService interact with triggers and validation rules when enriching records?

Depending on the bypassTriggers and bypassWorkflow flags configured on the nested CleanRule, data enrichment updates can update records silently without firing standard record-triggered automations.

Where are CleanDataService files stored in SFDX source format?

They are stored in force-app/main/default/cleanDataServices/ with the file extension .cleanDataService-meta.xml.

Can I deploy arbitrary custom CleanDataService files without an installed Lightning Data package?

No, CleanDataService records are typically provisioned by platform Data Integration services (such as Geocoding) or installed AppExchange Lightning Data packages.