FieldMappingConfig in Salesforce Metadata API

Architectural Overview#

FieldMappingConfig represents declarative field transformation and schema alignment rules within the Salesforce Metadata API. In complex multi-cloud architectures—such as synchronizing staging objects with Data Cloud Data Model Objects (DMOs), executing automated Lead Conversion mappings, or integrating Health Cloud and Financial Services Cloud objects—writing custom Apex translation logic introduces maintenance overhead and performance bottlenecks.

FieldMappingConfig externalizes field transformation logic into version-controlled metadata. It defines deterministic mappings between source entity fields and target entity fields, specifying type conversions, default values, and data normalization rules that are executed natively within the Salesforce platform core runtime.

By maintaining FieldMappingConfig in your CI/CD repository, schema alterations can be tested in scratch orgs, peer-reviewed via pull requests, and deployed systematically without risk of runtime script failures.

Directory and File Conventions#

FieldMappingConfig metadata files are located in the fieldMappingConfigs directory:

Key Metadata Fields#

The FieldMappingConfig XML schema defines schema mapping parameters:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition of FieldMappingConfig mapping inbound prospect staging records into standard Contact records:

<?xml version="1.0" encoding="UTF-8"?>
<FieldMappingConfig xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Maps staged inbound marketing prospect records into standard Contact objects</description>
    <developerName>Prospect_To_Contact_Mapping</developerName>
    <masterLabel>Prospect To Contact Mapping</masterLabel>
    <sourceEntity>Inbound_Prospect__c</sourceEntity>
    <targetEntity>Contact</targetEntity>
</FieldMappingConfig>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy FieldMappingConfig metadata using the Salesforce CLI:

# Retrieve a specific field mapping configuration
sf project retrieve start --metadata FieldMappingConfig:Prospect_To_Contact_Mapping

# Deploy all field mapping configs to target org
sf project deploy start --metadata FieldMappingConfig

# Validate deployment dependencies prior to execution
sf project deploy start --metadata FieldMappingConfig --dry-run

Architect Best Practices and Gotchas#

• Dependency Sequencing: FieldMappingConfig has hard dependencies on the existence of both sourceEntity and targetEntity, along with all mapped custom fields. Deploy custom objects and fields in Wave 1 before deploying mapping configs in Wave 2.
• Type Compatibility Enforcement: Mapped source and target fields must possess compatible data types. Mapping a source text field of length 255 to a target text field of length 50 will cause truncation exceptions during batch pipeline execution.
• Companion Relationship Definitions: Pair FieldMappingConfig with FieldSrcTrgtRelationship metadata to establish deterministic relational linkage and foreign key resolutions across transformed record sets.

Frequently asked questions

What is the purpose of FieldMappingConfig in Salesforce?

FieldMappingConfig defines schema mapping rules and transformation relationships between source and target object fields across integration pipelines.

Where is FieldMappingConfig typically utilized across Salesforce Clouds?

It is heavily utilized in Data Cloud ingestion, Lead Conversion mapping, and Industry Cloud data pipelines to normalize external schemas.

Can FieldMappingConfig metadata be packaged in managed 2GP solutions?

Yes. Field mapping configurations can be packaged in second-generation packages to deliver out-of-the-box data model synchronizations to subscribers.

What CLI command retrieves FieldMappingConfig metadata?

Execute sf project retrieve start with metadata set to FieldMappingConfig to extract the XML mapping definitions into your SFDX project.