Field Mapping & Transforms

After the change detection engine identifies changed rows, those rows pass through the Transform stage. This is where you define how source fields map to target dimensions and apply any data transformations needed to match your target system's schema.

Mapping Source to Target

A field mapping connects a source field name to a target dimension or column. You configure mappings in the pipeline settings for each connector pair.

{
  "mappings": [
    { "source": "ACCOUNT_NUMBER", "target": "GL_Account" },
    { "source": "POSTING_PERIOD",  "target": "Period" },
    { "source": "SUBSIDIARY_NAME", "target": "Entity" },
    { "source": "AMOUNT",          "target": "Amount" }
  ]
}

Every field in the target that is required must have a mapping. VersionForge validates your configuration and flags any unmapped required fields before the first sync runs.

Transform Rules

Beyond simple rename mappings, you can apply transform rules to reshape data as it flows through.

Available Transform Types

| Rule | Description | Example | |---|---|---| | rename | Map a source field to a differently-named target field | ACCT_NO becomes GL_Account | | concatenate | Combine two or more source fields into one | first_name + last_name becomes Full_Name | | split | Break a single field into multiple fields by delimiter | "6100-US" splits into Account and Region | | default | Assign a fallback value when the source field is null or empty | Empty department defaults to "Unassigned" | | lookup | Replace source values using a lookup table | "US01" maps to "United States - East" |

Example: NetSuite GL to Adaptive Dimensions

A common configuration maps NetSuite GL trial balance data to Adaptive Planning dimensions:

{
  "mappings": [
    {
      "source": "ACCOUNT_NUMBER",
      "target": "GL_Account",
      "transform": { "type": "lookup", "table": "gl_account_map" }
    },
    {
      "source": "POSTING_PERIOD",
      "target": "Period",
      "transform": { "type": "rename" }
    },
    {
      "source": "SUBSIDIARY",
      "target": "Entity",
      "transform": {
        "type": "split",
        "delimiter": " - ",
        "index": 0
      }
    },
    {
      "source": "DEBIT_AMOUNT",
      "target": "Amount",
      "transform": { "type": "default", "value": 0 }
    }
  ]
}

Custom Transform Expressions

For complex logic that cannot be covered by the built-in rules, you can write custom transform expressions. Expressions use a safe, sandboxed syntax:

concat(upper(source.DEPT_CODE), "-", source.LOCATION_CODE)

Supported functions include upper(), lower(), trim(), left(), right(), replace(), concat(), coalesce(), and round().

Type Conversions

VersionForge handles common type mismatches automatically during transform:

• String to number -- Strips currency symbols, commas, and whitespace before parsing. "$1,234.56" becomes 1234.56.
• Date formats -- Normalizes dates to ISO 8601 (YYYY-MM-DD). Recognizes MM/DD/YYYY, DD-MMM-YYYY, and epoch timestamps.
• Boolean coercion -- Converts "true", "yes", "1", "Y" to true (case-insensitive).

If a type conversion fails, the row is flagged as an error in the pipeline log and does not proceed to the Safety Gate.

Lookup Tables

Lookup tables are reusable across pipelines. You can manage them in Settings > Lookup Tables or upload them as CSV files. Each table is a simple key-value map:

| Source Value | Target Value | |---|---| | 6100 | Revenue - Product | | 6200 | Revenue - Services | | 7100 | COGS - Materials |

When the lookup finds no match, the behavior depends on your configuration: pass-through (keep the original value), default (use a fallback), or error (flag the row).