ObjectSourceTargetMap Metadata Type in SFDX

Architectural Overview#

ObjectSourceTargetMap is a declarative data transformation metadata type that defines schema mappings between a source object and a target object. It establishes field-level mappings, constant assignments, and conversion rules used by Salesforce Business Rules Engine (BRE), Data Processing Engine (DPE), and Industry Cloud record generation services.

In enterprise integration and document intake workflows, transitioning data across distinct operational schemas (e.g., transforming a Lead or Application record into an Account, Contact, or Policy) often requires custom Apex scripts. ObjectSourceTargetMap standardizes this transformation layer into version-controlled metadata, eliminating custom code and simplifying CI/CD deployment pipelines.

Directory and File Conventions#

ObjectSourceTargetMap records are stored in the objectSourceTargetMaps/ folder within SFDX source trees.

Key Metadata Fields#

The ObjectSourceTargetMap XML definition defines source, target, and field mapping collections:

Child Structure: fieldMappings#

Declarative XML and Package Manifest Examples#

An architectural mapping definition transforming an intake application into an active business account:

<?xml version="1.0" encoding="UTF-8"?>
<ObjectSourceTargetMap xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Application_To_Account_Map</developerName>
    <masterLabel>Application to Account Mapping</masterLabel>
    <sourceObjectName>Intake_Application__c</sourceObjectName>
    <targetObjectName>Account</targetObjectName>
    <mappingType>FieldMapping</mappingType>
    <fieldMappings>
        <sourceField>Legal_Entity_Name__c</sourceField>
        <targetField>Name</targetField>
    </fieldMappings>
    <fieldMappings>
        <sourceField>Tax_Identifier__c</sourceField>
        <targetField>AccountNumber</targetField>
    </fieldMappings>
    <fieldMappings>
        <sourceField>Corporate_Email__c</sourceField>
        <targetField>Company_Email__c</targetField>
    </fieldMappings>
</ObjectSourceTargetMap>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Use the Salesforce CLI to retrieve and deploy object maps:

# Retrieve all object source target maps
sf project retrieve start --metadata ObjectSourceTargetMap

# Deploy a specific mapping file
sf project deploy start --metadata ObjectSourceTargetMap:Application_To_Account_Map

Architect Best Practices and Gotchas#

• Schema Precedence: Ensure both the source and target CustomObject definitions and their respective fields are included in the deployment bundle. Any missing target field will cause deployment failure.
• Type Compatibility: Verify that source and target data types match (e.g., text to text, number to number). Mapping incompatible types (such as an arbitrary Text field into a Date or Picklist field) can result in runtime transformation exceptions.
• Null Handling Policies: Ensure downstream target field validation rules and triggers account for optional source fields that may map null values into required target fields.

Frequently asked questions

What is the core function of ObjectSourceTargetMap?

It maps fields from a source object to a target object, driving automated record generation and data transformation pipelines without custom code.

Which Salesforce cloud solutions utilize ObjectSourceTargetMap?

It is widely used in Industry Clouds such as Public Sector Solutions, Net Zero Cloud, Automotive Cloud, and Financial Services Cloud.

Where is ObjectSourceTargetMap stored in SFDX repositories?

It is stored in the force-app/main/default/objectSourceTargetMaps/ directory with the suffix .objectSourceTargetMap-meta.xml.