Skip to main content

Mapping Tool

Evgenii Vladimirov
Evgenii Vladimirov

The Mapping Tool is a flexible, metadata-driven module that enables bidirectional data transformation between Salesforce SObjects and JSON. It provides a declarative approach to mapping Salesforce objects and fields to external system formats, supporting hierarchical data structures with parent-child relationships.

Key Features​

  • Bidirectional Mapping: Convert SObjects to JSON and JSON to SObjects
  • Metadata-Driven Configuration: Configure mappings using Custom Metadata Types
  • Hierarchical Support: Handle parent-child relationships at multiple levels
  • External ID Support: Use external IDs for record matching and upsert operations
  • Type Conversion: Automatic type conversion between JSON and Salesforce field types

Architecture​

The module consists of several key components:

Core Services​

Configuration Classes​

Supporting Classes​

Quick Start​

Converting SObjects to JSON​

List<Id> accountIds = [SELECT Id FROM Account LIMIT 10];
String jsonResult = AqMappingToolService.mapObjectsToJSON(accountIds, 'AccountMapping');
System.debug(jsonResult);

Upserting Records from JSON​

String jsonString = '[{"LastName" : "USER LAST NAME", "FirstName" : "NEW VALUE FOR NAME"}]';
AqResult result = AqMappingToolService.upsertRecordsFromJson(
jsonString,
'UserMapping',
true // Require external IDs
);

if (result.Severity == AqResult.SEVERITY_SUCCESS) {
for (AqRecordWithChildren rec : (List<AqRecordWithChildren>)result.ReturnValue) {
System.debug('Record Id: ' + rec.record.Id);
}
} else {
System.debug('Error message: ' + result.Message);
}

Field Name Mapping Utilities​

The mapping tool provides methods to convert between Salesforce field names and external field names. This is useful when you need to programmatically access field mappings or transform data outside of the main conversion methods.

Getting Object Mapping​

First, you need to get the AqObjectMapping instance for your object:

AqMappingConfigurationWrapper config = new AqMappingConfigurationWrapper(
new AqFieldDefinitionMappingData(),
new AqObjectDefinitionMappingData()
);

AqObjectMapping objectMapping = config.getObjectMapping('AccountMapping');

Getting External Field Name from Salesforce Field Name​

To get the external field name for a Salesforce field:

AqMappingConfigurationWrapper config = new AqMappingConfigurationWrapper(
new AqFieldDefinitionMappingData(),
new AqObjectDefinitionMappingData()
);

AqObjectMapping objectMapping = config.getObjectMapping('AccountMapping');

// Get field definition by SF field name
FieldDefinitionMapping__mdt fieldDef = objectMapping.getFieldDefinition('Name');

if (fieldDef != null) {
String externalFieldName = fieldDef.ExternalFieldName__c;
System.debug('External field name: ' + externalFieldName);
// Output: External field name: AccountName
}

Getting Salesforce Field Name from External Field Name​

To get the Salesforce field name for an external field name:

AqMappingConfigurationWrapper config = new AqMappingConfigurationWrapper(
new AqFieldDefinitionMappingData(),
new AqObjectDefinitionMappingData()
);

AqObjectMapping objectMapping = config.getObjectMapping('AccountMapping');

// Get all field definitions by external name
Map<String, FieldDefinitionMapping__mdt> externalFieldMap =
objectMapping.getFieldDefinitionByExternalName();

// Get field definition by external name
FieldDefinitionMapping__mdt fieldDef = externalFieldMap.get('AccountName');

if (fieldDef != null) {
String sfFieldName = fieldDef.SFField__c;
System.debug('Salesforce field name: ' + sfFieldName);
// Output: Salesforce field name: Name
}

Getting External ID Field Information​

To get information about the external ID field:

AqMappingConfigurationWrapper config = new AqMappingConfigurationWrapper(
new AqFieldDefinitionMappingData(),
new AqObjectDefinitionMappingData()
);

AqObjectMapping objectMapping = config.getObjectMapping('AccountMapping');

// Get external ID field definition
FieldDefinitionMapping__mdt externalIdField = objectMapping.getExternalIdFieldDefinition();

if (externalIdField != null) {
String sfFieldName = externalIdField.SFField__c;
String externalFieldName = externalIdField.ExternalFieldName__c;
System.debug('External ID SF Field: ' + sfFieldName);
System.debug('External ID External Name: ' + externalFieldName);
}

See AqObjectMapping for complete API documentation.

Configuration: Custom Metadata Types​

The mapping tool uses two Custom Metadata Types for configuration:

ObjectDefinitionMapping__mdt​

Defines how a Salesforce object maps to external JSON structure.

Fields:

Field NameTypeRequiredDescription
DeveloperNameTextYesUnique identifier for the mapping (used in code)
Object__cTextYesAPI name of the Salesforce object (e.g., "Account", "Contact")
ParentObject__cTextNoDeveloperName of parent ObjectDefinitionMapping (for child objects)
ParentIdFieldName__cTextConditionalField API name that links to parent (required for child objects)
PluralName__cTextConditionalPlural name used in JSON for child collections (required for child objects)

Configuration Rules:

  • Root objects should not have ParentObject__c or ParentIdFieldName__c
  • For embedded hierarchical objects: Child objects must have both ParentObject__c and ParentIdFieldName__c
  • PluralName__c is used as the key in JSON for embedded child object arrays (required for hierarchical objects)
  • The field specified in ParentIdFieldName__c cannot have a FieldDefinitionMapping (it's managed automatically)
  • Each object definition must have at least one FieldDefinitionMapping record

Example Configuration:

  • Root Object (Account):

    • DeveloperName: AccountMapping
    • Object__c: Account
    • ParentObject__c: (empty)
    • ParentIdFieldName__c: (empty)
    • PluralName__c: (empty)
  • Child Object (Contact):

    • DeveloperName: ContactMapping
    • Object__c: Contact
    • ParentObject__c: AccountMapping
    • ParentIdFieldName__c: AccountId
    • PluralName__c: Contacts

FieldDefinitionMapping__mdt​

Defines how individual Salesforce fields map to JSON properties.

Fields:

Field NameTypeRequiredDescription
DeveloperNameTextYesUnique identifier for the field mapping
ObjectDefinition__cLookupYesReference to ObjectDefinitionMapping__mdt
SFField__cTextYesAPI name of the Salesforce field
ExternalFieldName__cTextYesName used in JSON (external system field name)
IsExternalId__cCheckboxNoIf true, this field is used for record matching/upsert
FieldTypeOverride__cTextNoOverride field type conversion (e.g., "String")
ParentObject__cLookupNoLookup relationship to ObjectDefinitionMapping__mdt (required for lookup fields, not for embedded objects)
ParentExternalIdFieldName__cTextConditionalExternal ID field name on parent object (required if ParentObject__c is set)
UpdateBehaviour__cPicklistYesControls update behavior (default: "Allow updates")

UpdateBehaviour__c Values:

  • "Allow updates": Field can be updated on existing records (default)
  • "Ignore updates": Field is never updated on existing records
  • "Ignore updates to null values": Field is only updated if new value is not null

Configuration Rules:

  • Each object definition should have at most one field marked as IsExternalId__c = true (required when requireExternalIds = true in upsertRecordsFromJson)
  • For lookup references (not embedded objects): Lookup fields require ParentObject__c (lookup relationship to ObjectDefinitionMapping__mdt) and ParentExternalIdFieldName__c
  • The field specified in ParentIdFieldName__c of ObjectDefinitionMapping cannot have a FieldDefinitionMapping (it's managed automatically for embedded objects)
  • ExternalFieldName__c must be unique within an object definition
  • SFField__c must be unique within an object definition
  • When using lookup references, the parent object must have an external ID field configured

Example Configuration:

  • Standard Field:

    • ObjectDefinition__c: AccountMapping
    • SFField__c: Name
    • ExternalFieldName__c: AccountName
    • IsExternalId__c: false
    • UpdateBehaviour__c: Allow updates
  • External ID Field:

    • ObjectDefinition__c: AccountMapping
    • SFField__c: ExternalId__c
    • ExternalFieldName__c: ExtId
    • IsExternalId__c: true
    • UpdateBehaviour__c: Allow updates
  • Lookup Field:

    • ObjectDefinition__c: ContactMapping
    • SFField__c: AccountId
    • ExternalFieldName__c: AccountExtId
    • ParentObject__c: AccountMapping (lookup to ObjectDefinitionMapping__mdt)
    • ParentExternalIdFieldName__c: ExtId
    • IsExternalId__c: false
    • UpdateBehaviour__c: Allow updates

Record Hierarchy Support​

The mapping tool supports two different approaches for handling parent-child relationships:

1. Embedded Objects (Hierarchical Structure)​

This approach creates nested object structures in JSON where child objects are embedded within parent objects as arrays.

Configuration:

  • Link ObjectDefinitionMapping records via ParentObject__c field
  • Child ObjectDefinitionMapping must specify:
    • ParentObject__c: DeveloperName of parent ObjectDefinitionMapping
    • ParentIdFieldName__c: Field API name that links to parent (e.g., AccountId)
    • PluralName__c: Key name used in JSON for the child array

JSON Structure:

[
{
"ExtId": "ACC-001",
"AccountName": "Acme Corp",
"Contacts": [
{
"ExtId": "CON-001",
"FirstName": "John",
"LastName": "Doe"
},
{
"ExtId": "CON-002",
"FirstName": "Jane",
"LastName": "Smith"
}
]
}
]

When to Use:

  • When you need to represent parent-child relationships as nested structures
  • When child records are always created/updated together with parent records
  • When the JSON structure should reflect the hierarchical nature of the data

2. Lookup References (via External ID)​

This approach uses lookup fields that reference parent records by their external ID values.

Configuration:

  • Create a FieldDefinitionMapping on the child object for the lookup field
  • Set ParentObject__c (lookup relationship to ObjectDefinitionMapping__mdt) to reference the parent object definition
  • Set ParentExternalIdFieldName__c to the external field name of the parent's external ID field

JSON Structure:

[
{
"ExtId": "CON-001",
"FirstName": "John",
"LastName": "Doe",
"AccountExtId": "ACC-001"
}
]

When to Use:

  • When parent and child records are created/updated independently
  • When you need a flat JSON structure with references
  • When parent records may already exist and you're only creating/updating child records
  • When the relationship is optional or can be set later

Key Differences​

AspectEmbedded ObjectsLookup References
ConfigurationObjectDefinitionMapping with ParentObject__cFieldDefinitionMapping with ParentObject__c
JSON StructureNested arraysFlat structure with reference values
Parent RequiredParent must be in same JSON payloadParent can exist independently
Use CaseHierarchical data, parent-child togetherIndependent records, optional relationships

Important Notes​

  • Cannot mix approaches for the same relationship: If you configure a child ObjectDefinitionMapping with ParentObject__c, you should NOT also create a FieldDefinitionMapping for the ParentIdFieldName__c field. The field specified in ParentIdFieldName__c cannot have a FieldDefinitionMapping.
  • Lookup fields require parent external ID: When using lookup references, the parent object must have an external ID field configured, and that field must exist in the system before the child record can reference it.
  • Both approaches can coexist: You can use embedded objects for some relationships and lookup references for others within the same mapping configuration.

Usage Examples​

Example 1: Converting SObjects to JSON​

// Get account IDs
List<Id> accountIds = new List<Id>();
for (Account acc : [SELECT Id FROM Account LIMIT 10]) {
accountIds.add(acc.Id);
}

// Convert to JSON using mapping configuration
String jsonOutput = AqMappingToolService.mapObjectsToJSON(
accountIds,
'AccountMapping'
);

// Use the JSON (e.g., send to external system)
System.debug('JSON Output: ' + jsonOutput);

Example 2: Upserting Records from JSON (Embedded Objects)​

This example demonstrates the embedded objects approach where child records are nested within parent records.

// JSON payload from external system with embedded child objects
String jsonPayload = '[' +
'{' +
'"ExtId": "ACC-001",' +
'"AccountName": "Acme Corporation",' +
'"Industry": "Technology",' +
'"Contacts": [' +
'{' +
'"ExtId": "CON-001",' +
'"FirstName": "John",' +
'"LastName": "Doe",' +
'"Email": "john.doe@acme.com"' +
'}' +
']' +
'}' +
']';

// Upsert records (uses embedded objects configuration)
AqResult result = AqMappingToolService.upsertRecordsFromJson(
jsonPayload,
'AccountMapping',
true // Require external IDs
);

// Handle result
if (result.Severity == AqResult.SEVERITY_SUCCESS) {
List<AqRecordWithChildren> records =
(List<AqRecordWithChildren>)result.ReturnValue;

for (AqRecordWithChildren record : records) {
System.debug('Upserted Account ID: ' + record.record.Id);

// Process child records (embedded objects)
if (record.children != null) {
for (AqRecordWithChildren child : record.children) {
System.debug('Upserted Contact ID: ' + child.record.Id);
}
}
}
} else {
System.debug('Error: ' + result.Message);
// Handle error
}

Example 3: Upserting Records from JSON (Lookup References)​

This example demonstrates the lookup reference approach where child records reference parent records via external ID.

// JSON payload with lookup references (flat structure)
// Note: Parent Account must already exist with ExtId = "ACC-001"
String jsonPayload = '[' +
'{' +
'"ExtId": "CON-001",' +
'"FirstName": "John",' +
'"LastName": "Doe",' +
'"Email": "john.doe@acme.com",' +
'"AccountExtId": "ACC-001"' + // Reference to parent via external ID
'}' +
']';

// Upsert records (uses lookup reference configuration)
AqResult result = AqMappingToolService.upsertRecordsFromJson(
jsonPayload,
'ContactMapping', // Child object mapping
true // Require external IDs
);

// Handle result
if (result.Severity == AqResult.SEVERITY_SUCCESS) {
List<AqRecordWithChildren> records =
(List<AqRecordWithChildren>)result.ReturnValue;

for (AqRecordWithChildren record : records) {
System.debug('Upserted Contact ID: ' + record.record.Id);
// Lookup field (AccountId) is automatically set based on AccountExtId
}
} else {
System.debug('Error: ' + result.Message);
// Handle error - may indicate parent record not found
}

Example 4: Using Custom Data Providers​

// Create custom data providers (useful for testing or custom logic)
AqFieldDefinitionMappingData customFieldData = new CustomFieldDefinitionData();
AqObjectDefinitionMappingData customObjectData = new CustomObjectDefinitionData();

// Use custom providers
AqResult result = AqMappingToolService.upsertRecordsFromJson(
jsonString,
'AccountMapping',
true,
customFieldData,
customObjectData
);

Field Type Conversion​

The mapping tool automatically handles type conversion between JSON values and Salesforce field types. See AqTypeConverter for complete details.

Supported Conversions​

  • String → Text/Email/Phone/URL: Direct assignment
  • String → Number/Currency/Percent: Parsed as Decimal
  • String → Date: Parsed from ISO format (YYYY-MM-DD)
  • String → DateTime: Parsed from ISO format
  • String → Boolean: "true"/"false" converted to Boolean
  • String → Picklist: Direct assignment (must match valid picklist value)
  • String → Multi-Select Picklist: Semicolon-separated values
  • Number → Number/Currency/Percent: Direct assignment
  • Boolean → Boolean: Direct assignment

Field Type Override​

Use FieldTypeOverride__c to force a specific type conversion:

// Force conversion to String regardless of actual field type
FieldDefinitionMapping__mdt fieldDef = new FieldDefinitionMapping__mdt();
fieldDef.FieldTypeOverride__c = 'String';

Update Behavior​

Control how fields are updated during upsert operations:

Allow Updates (Default)​

UpdateBehaviour__c = 'Allow updates'
  • Field is always updated if present in JSON
  • Null values will overwrite existing values

Ignore Updates​

UpdateBehaviour__c = 'Ignore updates'
  • Field is never updated on existing records
  • Useful for read-only fields or fields managed by other processes

Ignore Updates to Null Values​

UpdateBehaviour__c = 'Ignore updates to null values'
  • Field is only updated if the new value is not null
  • Prevents null values from overwriting existing data
  • Useful for optional fields that should preserve existing values

Error Handling​

The mapping tool provides comprehensive error handling:

Common Errors​

  1. Missing External ID:

    • Error: "Required ExternalId Field is missing for 0 object from 1 object definition."
    • Solution: Ensure external ID field is present in JSON when requireExternalIds = true
  2. Duplicate External IDs:

    • Error: "More than one External Id defined for 0"
    • Solution: Ensure only one field per object has IsExternalId__c = true
  3. Parent Record Not Found:

    • Error: "There is no 0 parent record with 1 value in 2 field. Make sure such a record exists in the system."
    • Solution: Ensure parent records exist before creating child records
  4. Invalid Field Type:

    • Error: "Error converting value for field 0: 1"
    • Solution: Ensure JSON values match expected field types
  5. Empty JSON:

    • Error: "Provided JSON is empty"
    • Solution: Ensure JSON string is not empty or null

Error Handling Pattern​

try {
AqResult result = AqMappingToolService.upsertRecordsFromJson(
jsonString,
'AccountMapping',
true
);

if (result.Severity == AqResult.SEVERITY_SUCCESS) {
// Process success
} else {
// Handle error
System.debug('Error: ' + result.Message);
// Log error, notify users, etc.
}
} catch (Exception e) {
// Handle unexpected exceptions
System.debug('Exception: ' + e.getMessage());
System.debug('Stack trace: ' + e.getStackTraceString());
}

Dependencies​