#14. Field Mapping & Expressions (Detailed)

iSyncSF Field Mapping allows you to map source Salesforce fields to differently named target fields, and write formula expressions to transform values during sync. The expression builder supports IF, CASE, TEXT, and VALUE functions — plus picklist value translation for cross-org data normalization.

Purpose: The field mapping and expression system is the intelligence layer of the sync engine. It determines: (1) How to MATCH source records to existing target records (insert vs. update decision), (2) How to MAP source fields to target fields (including cross-field mapping when field names differ), (3) How to TRANSFORM values using expressions/formulas, and (4) How to TRANSLATE picklist values between orgs. This enables syncing between orgs with different schemas, different field names, and different picklist definitions. Where It Fits: Field mapping is configured in the Object Settings -> Field Mapping tab (during setup, Step 5). The settings are consumed at sync runtime by the sync engine to prepare each record before sending it to the target org. Record matching happens first (to decide insert vs. update), then field mapping and expressions are applied, then picklist values are translated, then masking runs, and finally the prepared record is sent.

#14.1 How Record Matching Works

When syncing data, the system needs to determine whether each source record should be inserted as new or updated over an existing record in the target org.

Matching Process (from user perspective): 1. The system uses the Mapping Fields configured on the Object Setting as a unique key 2. It queries the target org for records matching those key field values 3. If a match is found: - If "Update Existing Records" is enabled: the record is updated - If "Update Existing Records" is disabled: the record is skipped (marked as "existing") 4. If no match is found: - If "Don't Insert New Records" is not checked: the record is inserted - If "Don't Insert New Records" is checked: the record is skipped

Strict Update Check: - When "Update Check" fields are configured, the system compares those specific fields between source and target - If ALL checked fields have identical values, the record is skipped (no unnecessary update) - This prevents unnecessary DML on the target org

#14.2 Expression System

iSyncSF Expression Builder showing IF and CASE formulas, field picker, function list, and syntax validation — Expression Builder with formula editor, field picker, function list, and syntax check

The expression system lets you define formulas that compute or transform field values during sync. Under the hood, it uses Salesforce's native Formula Evaluator API - the same engine that powers formula fields throughout the Salesforce platform. This means any formula syntax that Salesforce supports is also supported here, including all standard functions, operators, and field references.

Tip: If you already have a working formula in a Salesforce formula field, you can simply copy it and paste it directly into the Expression Builder. It will work the same way. Alternatively, you can use the formula editor on any Salesforce formula field to build and test your formula first, then copy the validated formula text into iSyncSF.

How It Works:

Expressions are configured per field in the Field Mapping tab using the Expression Builder (see Expression Builder)
When a sync runs, the engine evaluates each expression against the source record data and writes the computed value to the target field
You can reference any source field in your formula, combine multiple fields, apply conditional logic, and use built-in functions

Commonly Used Functions:

Logical: IF, AND, OR, NOT, CASE
Null handling: ISBLANK, BLANKVALUE
Text: TEXT, LEN, LEFT, RIGHT, MID, SUBSTITUTE, TRIM, UPPER, LOWER, CONTAINS, BEGINS
Numeric: VALUE
Date: TODAY, NOW
Picklist: ISPICKVAL
Operators: =, <>, >, >=, <, <=, &, +, -, *, /

This is not an exhaustive list - since the system uses Salesforce's native formula engine, any function available in Salesforce formula fields is supported. For a complete reference, see Salesforce Formula Operators and Functions.

Examples:

IF(Type = "Customer", "Active", "Inactive") - Set a value based on a condition
UPPER(LastName) & ", " & FirstName - Combine and format text fields
IF(ISBLANK(Email), "no-email@example.com", Email) - Provide a default when a field is empty
CASE(Rating, "Hot", "1-High", "Warm", "2-Medium", "3-Low") - Map values using CASE

Validation: Always use the Check Syntax button in the Expression Builder before applying a formula. The system validates the syntax, verifies field references, and reports any errors so you can fix them before running a sync.

#14.3 Picklist Value Mapping

Maps source picklist values to target picklist values
Supports multi-select picklist fields (each value mapped individually)
Applied both during record matching (query building) and during data sync (payload building)

#Cross-Name Field Mapping

When source and target Salesforce orgs use different field API names for the same data, use the mapping syntax SourceField__c=TargetField__c in the Mapping Fields configuration on Object Settings. This tells iSyncSF to read from the source field and write to the differently named target field. Multiple mappings can be defined, separated by commas.

#Update Check Field

The Update Check Field controls whether an existing target record is re-updated during a sync. When a target record is found (matched by External ID), iSyncSF compares the Update Check Field value between source and target. If they match, the record is skipped — it has not changed since the last sync. This is the mechanism behind incremental/delta behavior at the field level.

#Record Matching Priority

iSyncSF matches source records to existing target records using the following priority:

Custom External ID (if configured in Object Settings) — highest priority. iSyncSF uses the configured external ID field to match source records to existing target records via upsert.
Mapping Fields match — if Mapping Fields are configured on the Object Setting, iSyncSF uses those field mappings to identify existing target records.
Insert as new — if no match is found using the above methods, the record is inserted as a new record in the target org.

#Object Processing Order

For templates with multiple objects, iSyncSF determines processing order based on parent-child relationships detected during the pre-scan. Parent objects are always processed before their children to ensure lookup fields can be populated with valid target IDs.

Self-referential objects (objects with a lookup to themselves, such as Account hierarchy) are handled by a two-pass approach: records are inserted first with a null self-reference, then updated once the full source-to-target ID mapping is available.