LeadConvertSettings Metadata Type in SFDX

Architectural Overview#

The LeadConvertSettings metadata type represents declarative Lead conversion configurations and custom field mapping definitions in Salesforce Sales Cloud. When sales representatives qualify a prospect and click Convert, the platform converts the uncommitted Lead record into persistent relational entities: Account, Contact, and optionally Opportunity.

Architecturally, LeadConvertSettings decouples lead field mapping from brittle Apex triggers or Flow workarounds. By defining declarative mapping pairs between source Lead custom fields and target custom fields on Account, Contact, or Opportunity, architects ensure atomic, transactional data migration during conversion while enforcing data type compatibility and referential integrity.

Directory and File Conventions#

In Salesforce DX source format, LeadConvertSettings is stored in individual XML files within the leadConvertSettings directory:

Key Metadata Fields#

The XML schema for LeadConvertSettings declares individual mapping definitions linking source and target fields:

Declarative XML and Package Manifest Examples#

Source XML (LeadConvertSetting.leadConvertSetting-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<LeadConvertSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Standard Enterprise Lead Convert Mapping</masterLabel>
    <description>Maps prospect industry tags and budget fields to Account and Opportunity.</description>
    <objectMapping>
        <inputObject>Lead</inputObject>
        <outputObject>Account</outputObject>
        <mappingFields>
            <inputField>Industry_Segment__c</inputField>
            <outputField>Industry_Segment__c</outputField>
        </mappingFields>
    </objectMapping>
    <objectMapping>
        <inputObject>Lead</inputObject>
        <outputObject>Opportunity</outputObject>
        <mappingFields>
            <inputField>Estimated_Budget__c</inputField>
            <outputField>Amount</outputField>
        </mappingFields>
    </objectMapping>
</LeadConvertSettings>

Package Manifest (package.xml)#

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

Retrieval and Deployment#

To retrieve lead conversion settings from an organization:

# Retrieve all lead conversion settings
sf project retrieve start --metadata LeadConvertSettings

# Retrieve using manifest
sf project retrieve start --manifest manifest/package.xml

To deploy LeadConvertSettings to a target environment:

# Deploy to designated org
sf project deploy start \
  --metadata LeadConvertSettings \
  --target-org uat \
  --wait 10

Senior Architect Deployment Best Practices and Gotchas#

Strict Field Dependency Sequencing#

LeadConvertSettings has a bidirectional schema dependency on custom fields across four objects: Lead, Account, Contact, and Opportunity. If any referenced custom field is missing in the target org or not included in the deployment manifest, the deployment will fail:

1. Step 1: Deploy all custom fields (CustomField) on Lead, Account, Contact, and Opportunity.
2. Step 2: Deploy LeadConvertSettings referencing those fields.

Managing Conversion Trigger Logic#

Remember that lead conversion executes standard and custom triggers on all affected objects. When writing Apex triggers or Flows on Account or Contact, check isLeadConvert or inspect execution context to avoid executing redundant creation logic during conversion.

Frequently asked questions

What does LeadConvertSettings define in Salesforce?

It defines declarative custom field mappings and conversion policies between Lead fields and Account, Contact, or Opportunity fields.

Where is LeadConvertSettings stored in an SFDX project?

It is stored under force-app/main/default/leadConvertSettings with the file suffix leadConvertSetting-meta.xml.

What happens if a mapped field is deleted or has a mismatched data type?

Deployment will fail with a metadata validation error stating that target fields must match the data type and length of source fields.

Can LeadConvertSettings be retrieved using the Salesforce CLI?

Yes, using sf project retrieve start with metadata LeadConvertSettings or referencing it in a package.xml manifest.