AccountingFieldMapping Metadata Type in SFDX

Architectural Overview#

The AccountingFieldMapping metadata type represents a custom field mapping between source operational objects (such as Opportunities, Payments, Refunds, or Order Summaries) and target accounting subledger records (TransactionJournal or LedgerEntry). In industries using Salesforce Accounting Subledger—including Nonprofit Cloud, Education Cloud, and Revenue Lifecycle Management—finance teams require operational attributes like department codes, fund allocations, and cost centers to flow automatically into generated ledger entries.

From an architectural perspective, AccountingFieldMapping eliminates custom Apex triggers that copy fields onto subledger records after batch generation. By defining these mappings declaratively in SFDX source control, architects ensure that when the Accounting Subledger nightly job runs, custom dimensions are stamped atomically during ledger creation.

Directory and File Conventions#

In SFDX source format (apiVersion 68.0), AccountingFieldMapping components are stored in the accountingFieldMappings directory.

Key Metadata Fields#

The AccountingFieldMapping XML schema exposes the following core elements:

Declarative XML and Package Manifest Examples#

Below is a production-ready AccountingFieldMapping source file that maps a custom Cost_Center_Code__c field from a source payment record onto the generated subledger entry:

<?xml version="1.0" encoding="UTF-8"?>
<AccountingFieldMapping xmlns="http://soap.sforce.com/2006/04/metadata">
    <accountingModelConfig>Enterprise_Accrual_Model</accountingModelConfig>
    <isForAllocationType>false</isForAllocationType>
    <isForPaymentType>true</isForPaymentType>
    <isForTransactionType>false</isForTransactionType>
    <mappingBehavior>PointToPoint</mappingBehavior>
    <masterLabel>Payment Cost Center Mapping</masterLabel>
    <sourceField>Cost_Center_Code__c</sourceField>
    <targetField>Ledger_Cost_Center__c</targetField>
</AccountingFieldMapping>

Package Manifest (package.xml)#

Include both the custom fields and the AccountingFieldMapping metadata type when promoting subledger mappings through your CI/CD pipeline:

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

SOQL Queries and CLI Automation#

You can inspect active field mappings via SOQL or retrieve and deploy them using Salesforce CLI (sf).

SELECT Id, DeveloperName, MasterLabel, SourceField, TargetField,
       MappingBehavior, IsForPaymentType, IsForAllocationType
FROM AccountingFieldMapping
ORDER BY DeveloperName ASC

# Retrieve all AccountingFieldMapping components from the target org
sf project retrieve start --metadata "AccountingFieldMapping:*"

# Deploy a specific field mapping definition
sf project deploy start --metadata AccountingFieldMapping:Payment_Cost_Center_Map

Architect Best Practices and Gotchas#

• Immutable Historical Ledger Entries: Modifying or adding an AccountingFieldMapping only affects newly generated subledger records. Existing LedgerEntry or TransactionJournal records are financially immutable and will not be retroactively updated.
• Dependency Ordering: Always deploy the target CustomField and parent AccountingModelConfig in the same transaction or prior to deploying AccountingFieldMapping, otherwise the deployment fails with an unresolved reference error.
• Integration User FLS: The automated user running the Accounting Subledger batch job must have Read access to sourceField and Edit access to targetField via a PermissionSet, or mapped fields will silently evaluate to null.

Frequently asked questions

What does the AccountingFieldMapping metadata type configure in Salesforce?

It maps custom or standard fields from source CRM records such as Opportunity, Payment, or Order Summary to target fields on generated TransactionJournal or LedgerEntry records within Accounting Subledger.

Can I map fields with incompatible data types using AccountingFieldMapping?

No. Both the source field and the target field must have compatible data types, and for text or number fields the target field length or precision must be equal to or greater than the source field.

How are AccountingFieldMapping records tied to an AccountingModelConfig?

Each AccountingFieldMapping record includes an accountingModelConfig reference field that binds the field mapping to a specific active or inactive accounting model configuration in the org.

Does deploying AccountingFieldMapping automatically deploy the referenced custom fields?

No. You must include the source and target CustomField metadata components in your package manifest or deploy them prior to deploying the AccountingFieldMapping component.