Mapping Configuration

A mapping configuration is a JSON document that tells EZY Integrations exactly how to extract data from a source system, how to interpret and validate each field, and how to write those fields into the target system. One mapping config covers one entity type for one source–target connector pair. You create and edit mapping configs in the mapping config editor inside the EZY Integrations UI.

Structure overview

flowchart LR
    A["extraction block\nHow to read data\nfrom the source"] --> B["normalization block\nHow to map source fields\nto the canonical entity"]
    B --> C["transformation block\nHow to map canonical fields\nto the target payload"]

A mapping config has three top-level blocks:

Block	Purpose
extraction	Defines which records to read from the source system and which columns to fetch. Includes the cursor column for incremental sync.
normalization	Maps raw source field names to the canonical entity properties used internally by the pipeline. Also applies type conversions and sets default values.
transformation	Maps canonical properties to the exact field paths the target system expects. Applies value transformers, static values, and conditional mappings.

Extraction block

The extraction block controls how the pipeline reads records from the source. The available mode depends on the source connector:

Mode	When to use
Config	Build a query from a table name and column list. Recommended for most SAP Business One extractions — column names are validated before the query runs.
Raw SQL	Write a free-form SQL query. Use this for complex joins or subqueries that the config mode cannot express.
Stored Procedure	Call a named stored procedure and pass parameters. Use this when extraction logic is already encapsulated in the database.
API	Specify a source API endpoint. Used for connectors like EZY Portal and Shopify that expose a REST or GraphQL API.

The cursor column in the extraction block tells the pipeline which column tracks the last-modified timestamp. On each run, the pipeline fetches only records where the cursor column value is greater than the cursor saved from the previous run. If no cursor column is specified, the extraction reads all records every time.

Normalization block

The normalization block maps raw source field names (the aliases you defined in the extraction block) to the canonical entity properties that the pipeline uses internally. You can also:

• Specify the expected data type (string, decimal, int, bool, datetime) so the pipeline converts the value before storing it.
• Mark a field as required so the normalization stage fails fast if the value is null or empty, rather than sending an incomplete record downstream.
• Set a defaultValue so missing optional fields receive a sensible fallback instead of null.
• Apply a transform (a value transformer) to convert the raw value — for example, converting a SAP Y/N flag to a true/false boolean.

Transformation block

The transformation block maps canonical property names to the field paths the target system expects. A field path uses dot notation and supports array indexing: for example, product.variants[0].price sets the price on the first variant of a Shopify product.

You can also add:

• Static fields — inject a hard-coded value into every record, regardless of source data (for example, always set product.vendor to a fixed brand name).
• Conditions — apply a mapping only when a canonical field meets a criterion (for example, only map discountedPrice when hasDiscount == true).
• Multi-source mappings — collect values from several canonical fields into a single array (for example, combine category, subcategory, and productType into product.tags).

See Value Transformers for the full list of transformation functions you can apply within a field mapping.

Example mapping config

The following example shows a minimal item mapping config. Source field names, table names, and target paths use placeholder values.

{
  "version": "1.0",
  "extraction": {
    "source": "sap-b1",
    "mode": "config",
    "sqlConfig": {
      "baseTable": "<SOURCE_TABLE>",
      "alias": "T0",
      "columns": [
        { "column": "<CODE_COLUMN>",   "alias": "itemCode", "required": true },
        { "column": "<NAME_COLUMN>",   "alias": "itemName" },
        { "column": "<PRICE_COLUMN>",  "alias": "price" },
        { "column": "<DATE_COLUMN>",   "alias": "updateDate" }
      ],
      "whereClause": "T0.validFor = 'Y'",
      "cursorColumn": "updateDate",
      "primaryKeyColumn": "itemCode"
    }
  },
  "normalization": {
    "fieldMappings": [
      { "source": "itemCode", "canonical": "sku",   "required": true, "type": "string" },
      { "source": "itemName", "canonical": "name" },
      { "source": "price",    "canonical": "price", "type": "decimal", "defaultValue": 0 }
    ],
    "requiredFields": ["sku"]
  },
  "transformation": {
    "target": "ezyportal",
    "fieldMappings": [
      { "canonical": "sku",   "target": "itemCode" },
      { "canonical": "name",  "target": "itemName" },
      {
        "canonical": "price",
        "target": "price",
        "transform": "formatDecimal",
        "options": { "decimals": 2 }
      }
    ],
    "staticFields": [
      { "target": "itemType", "value": "I" }
    ]
  }
}

AI Assist

The mapping config editor includes an AI assistant that can generate a first-draft mapping config from a plain-language description. To use it, open the editor for a new mapping config, type a description of what you want to map (for example, “Map SAP B1 items including price and weight to Shopify products”), and the assistant will produce a draft. You must review, test, and adjust the draft before saving it — the assistant does not have access to your live data.

Validating a mapping config

The editor displays a validation badge that checks the JSON structure as you type. A green badge means the document is valid JSON with the required top-level blocks. A red badge indicates a structural error such as a missing required property or an invalid JSON path. Validation does not test whether field names match your actual source or target system — you verify that during a test run.

Common tasks

1. Open the mapping config editor — Navigate to Mapping Configurations in the main menu, then select an existing config or click New.
2. Create a mapping from scratch — Choose the entity type, select the source and target connector pair, then fill in the three blocks.
3. Use the AI assistant — Click the AI Assist button in the editor toolbar, describe your mapping, and review the generated draft.
4. Preview field mappings — Use the Preview panel to test a mapping against a sample payload from your source system.
5. Save and validate — Click Save; the editor validates the JSON structure and shows any errors inline.

Related

• Value Transformers — Full reference of transformation functions available in field mappings.
• Entity Types — Which entity type name to use in your mapping config.
• Architecture Overview — How the mapping config fits into the pipeline stages.