Field Mapping

Field mapping defines how data flows between your connected systems. This guide covers the different mapping types, transformations, and best practices.

Mapping Basics

When you create a sync between two systems, you need to tell Sync or Swim which fields in System A correspond to which fields in System B.

Mapping Types

Direct Mapping

The simplest type - one field maps directly to another:

Source Field	Target Field	Notes
first_name	FirstName	Direct 1:1 mapping
email	Email	Same data, different names

Computed Fields

Combine or transform fields during sync:

Concatenation

Combine multiple source fields into one target field:

Source: first_name + " " + last_name
Target: Full_Name__c

Result: "John" + " " + "Doe" → "John Doe"

Extraction

Extract part of a field value:

Source: email (extract domain)
Target: Email_Domain__c

Result: "john@acme.com" → "acme.com"

Default Values

Set a value when the source field is empty:

Source: priority (nullable)
Target: Priority__c
Default: "Normal"

Result: NULL → "Normal"

Lookup/Reference Fields

Map relationships between records:

Note

Lookup fields require the referenced record to be synced first. Sync or Swim automatically handles dependency ordering.

Type Conversions

Sync or Swim automatically handles common type conversions:

Source Type	Target Type	Conversion
string	string	Direct
integer	number	Direct
timestamp	datetime	Timezone-aware
boolean	checkbox	true/false → checked/unchecked
decimal	currency	Precision preserved
text[]	multipicklist	Array to semicolon-separated

Date/Time Handling

Date and time fields require special attention:

• Timestamps are converted to the target system’s timezone
• Date-only fields strip time components
• Time-only fields strip date components

Caution

Ensure your database stores timestamps in UTC for consistent sync behavior across timezones.

Filtering

Control which records sync based on conditions:

Include Filters

Only sync records that match:

WHERE status = 'active'
AND created_at > '2024-01-01'

Exclude Filters

Skip records that match:

WHERE type != 'internal'
AND is_test != true

Bi-directional Filters

Filters apply in both directions. A record excluded from sync:

• Won’t be created in the target system
• Won’t be updated if it changes
• Won’t be deleted if removed from source

Best Practices

1. Map Required Fields First

Ensure all required fields in the target system have mappings before enabling sync.

2. Handle Nulls Explicitly

Decide how null/empty values should behave:

• Skip - Don’t update target if source is null
• Clear - Set target to null/empty
• Default - Use a default value

3. Test with Sample Data

Before syncing production data:

1. Create a few test records
2. Verify mappings work as expected
3. Check computed fields calculate correctly
4. Validate lookup relationships resolve

4. Document Custom Logic

If you use complex transformations, document:

• What the transformation does
• Why it’s needed
• Example input/output values

Common Patterns

Syncing Names

PostgreSQL → Salesforce:

first_name → FirstName
last_name → LastName

Or combined:

first_name + ' ' + last_name → Name

Syncing Addresses

Map structured address fields:

street_address → BillingStreet
city → BillingCity
state → BillingState
postal_code → BillingPostalCode
country → BillingCountry

Syncing Status Fields

Map enums/picklists with value translation:

Source: 'new', 'in_progress', 'done'
Target: 'New', 'In Progress', 'Completed'

Troubleshooting

Field Not Syncing

1. Check the field is included in your mapping
2. Verify the source field has data
3. Check for type conversion errors in logs
4. Ensure the target field is writable

Wrong Values

1. Check for type mismatches
2. Review any transformations applied
3. Verify timezone handling for dates
4. Check for encoding issues with special characters

Lookup Failures

1. Ensure the referenced record exists
2. Verify the external ID field is mapped
3. Check the lookup field configuration
4. Review dependency ordering

Next Steps

• Sync Modes - Configure how records are matched
• Architecture Overview - Understand the sync process