Mapping Tool
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
- AqMappingToolService: Main entry point for mapping operations
- AqSObjectToJSONConverter: Converts SObjects to JSON based on mapping configuration
- AqJsonToSobjectParser: Parses JSON and creates/updates SObjects based on mapping configuration
- AqTypeConverter: Handles type conversion between JSON values and Salesforce field types
Configuration Classes
- AqMappingConfigurationWrapper: Wraps and provides access to mapping metadata
- AqObjectMapping: Represents a single object's mapping configuration
- AqObjectDefinitionMappingData: Data access layer for object definitions
- AqFieldDefinitionMappingData: Data access layer for field definitions
Supporting Classes
- AqRecordWithChildren: Represents a record with its child records in a hierarchical structure
- AqObjectQueryInfo: Manages queries for finding records by external IDs
- AqFieldQueryInfo: Handles field-level query operations
- AqSoqlObjectDefinitionQueryBuilder: Builds SOQL queries based on object definitions
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 Name | Type | Required | Description |
|---|---|---|---|
DeveloperName | Text | Yes | Unique identifier for the mapping (used in code) |
Object__c | Text | Yes | API name of the Salesforce object (e.g., "Account", "Contact") |
ParentObject__c | Text | No | DeveloperName of parent ObjectDefinitionMapping (for child objects) |
ParentIdFieldName__c | Text | Conditional | Field API name that links to parent (required for child objects) |
PluralName__c | Text | Conditional | Plural name used in JSON for child collections (required for child objects) |
Configuration Rules:
- Root objects should not have
ParentObject__corParentIdFieldName__c - For embedded hierarchical objects: Child objects must have both
ParentObject__candParentIdFieldName__c PluralName__cis used as the key in JSON for embedded child object arrays (required for hierarchical objects)- The field specified in
ParentIdFieldName__ccannot 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)
- DeveloperName:
-
Child Object (Contact):
- DeveloperName:
ContactMapping - Object__c:
Contact - ParentObject__c:
AccountMapping - ParentIdFieldName__c:
AccountId - PluralName__c:
Contacts
- DeveloperName:
FieldDefinitionMapping__mdt
Defines how individual Salesforce fields map to JSON properties.
Fields:
| Field Name | Type | Required | Description |
|---|---|---|---|
DeveloperName | Text | Yes | Unique identifier for the field mapping |
ObjectDefinition__c | Lookup | Yes | Reference to ObjectDefinitionMapping__mdt |
SFField__c | Text | Yes | API name of the Salesforce field |
ExternalFieldName__c | Text | Yes | Name used in JSON (external system field name) |
IsExternalId__c | Checkbox | No | If true, this field is used for record matching/upsert |
FieldTypeOverride__c | Text | No | Override field type conversion (e.g., "String") |
ParentObject__c | Lookup | No | Lookup relationship to ObjectDefinitionMapping__mdt (required for lookup fields, not for embedded objects) |
ParentExternalIdFieldName__c | Text | Conditional | External ID field name on parent object (required if ParentObject__c is set) |
UpdateBehaviour__c | Picklist | Yes | Controls 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 whenrequireExternalIds = trueinupsertRecordsFromJson) - For lookup references (not embedded objects): Lookup fields require
ParentObject__c(lookup relationship to ObjectDefinitionMapping__mdt) andParentExternalIdFieldName__c - The field specified in
ParentIdFieldName__cof ObjectDefinitionMapping cannot have a FieldDefinitionMapping (it's managed automatically for embedded objects) ExternalFieldName__cmust be unique within an object definitionSFField__cmust 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
- ObjectDefinition__c:
-
External ID Field:
- ObjectDefinition__c:
AccountMapping - SFField__c:
ExternalId__c - ExternalFieldName__c:
ExtId - IsExternalId__c:
true - UpdateBehaviour__c:
Allow updates
- ObjectDefinition__c:
-
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
- ObjectDefinition__c:
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__cfield - Child ObjectDefinitionMapping must specify:
ParentObject__c: DeveloperName of parent ObjectDefinitionMappingParentIdFieldName__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__cto 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
| Aspect | Embedded Objects | Lookup References |
|---|---|---|
| Configuration | ObjectDefinitionMapping with ParentObject__c | FieldDefinitionMapping with ParentObject__c |
| JSON Structure | Nested arrays | Flat structure with reference values |
| Parent Required | Parent must be in same JSON payload | Parent can exist independently |
| Use Case | Hierarchical data, parent-child together | Independent 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 theParentIdFieldName__cfield. The field specified inParentIdFieldName__ccannot 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
-
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
-
Duplicate External IDs:
- Error: "More than one External Id defined for 0"
- Solution: Ensure only one field per object has
IsExternalId__c = true
-
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
-
Invalid Field Type:
- Error: "Error converting value for field 0: 1"
- Solution: Ensure JSON values match expected field types
-
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());
}