Field Mapping: Translating Your Data

What is Field Mapping?

Your vendor calls it "PartNumber". SureDone calls it "guid". Your distributor's file has a column named "Avail Qty" but SureDone's stock field is just "stock". Every external system has its own names for things, and field mapping is how you bridge the gap.

The field_map object inside each file_configs entry defines the translation between the two systems. It is the single most important part of your automation configuration -- without it, the engine would not know which vendor column maps to which SureDone field.

The rule is simple: the key is always the SureDone field, and the value is always the vendor field.

"field_map": {
    "suredone_field": "vendor_field"
}

This applies whether you are importing or exporting. For imports, it means "take the vendor's value and put it in this SureDone field." For exports, it means "take this SureDone field and label it with this name in the output."

Import Field Mapping

When importing data into SureDone, field_map tells the engine which columns from the vendor's file correspond to which SureDone fields.

Source (vendor CSV headers)

Item Number, Brand Name, Item Description, ECOM Price Each, UPC Number, Total Qty

Config

"field_map": {
    "guid": "Item Number",
    "brand": "Brand Name",
    "title": "Item Description",
    "cost": "ECOM Price Each",
    "upc": "UPC Number",
    "stock": "Total Qty"
}

Result (SureDone fields populated)

Each row in the vendor's file gets translated: the value under "Item Number" goes into the guid field, "Brand Name" goes into brand, and so on.

Column-Based Mapping

For fixed-width or column-separated files that do not have named headers, you can map by column position using an array: [start_column, end_column]. The start is inclusive and the end is exclusive.

"field_map": {
    "guid": [0, 10],
    "title": [10, 60],
    "price": [60, 70],
    "stock": [70, 75]
}

This reads characters 0-9 as guid, 10-59 as title, and so on.

XPath Mapping (XML Files)

When importing XML files, set "xpath": true in your file config and use XPath expressions as the vendor field values:

Source (XML)

<products>
  <product sd_sku="ABC-123" upc="012345678901">
    <description title="Widget Pro"/>
    <inventory quantity="150"/>
    <price map="29.99" mrp="34.99"/>
  </product>
</products>

Config

"xpath": true,
"field_map": {
    "guid": "/products/product/@sd_sku",
    "upc": "/products/product/@upc",
    "title": "/products/product/description/@title",
    "stock": "/products/product/inventory/@quantity",
    "price": "/products/product/price/@map"
}

Result

JSONPath Mapping (JSON API Responses)

When importing from a JSON API, set "jsonpath": true and use JSONPath expressions:

Source (JSON response)

{
    "data": [
        {
            "id": 5001,
            "attributes": {
                "sku": "ABC-123",
                "sell_price": 29.99,
                "available_qty": 150
            }
        }
    ]
}

Config

"jsonpath": true,
"field_map": {
    "vendorid": "$.data[*].id",
    "guid": "$.data[*].attributes.sku",
    "price": "$.data[*].attributes.sell_price",
    "stock": "$.data[*].attributes.available_qty"
}

Result

Export Field Mapping

For exports, the same field_map structure applies, but the meaning shifts slightly. The key is still the SureDone field (the data source), and the value becomes the column header or field name in the output file.

Config

"field_map": {
    "guid": "SKU",
    "price": "Sell Price",
    "stock": "Available Quantity",
    "brand": "Brand Name"
}

Result (exported CSV)

SKU, Sell Price, Available Quantity, Brand Name
ABC-123, 29.99, 150, Acme

The headers field controls whether the header row is included in the output. It defaults to true.

"headers": false

field_map_default: Fallback Mapping

The field_map_default provides a secondary mapping for when the primary field does not exist in the vendor's data. This is most useful with non-flat files like XML, where different items may have data in different locations.

Source (XML with inconsistent price attributes)

<product sd_sku="ABC-123">
    <price map="29.99"/>           <!-- has 'map' price -->
</product>
<product sd_sku="DEF-456">
    <price mrp="34.99"/>           <!-- only has 'mrp' price, no 'map' -->
</product>

Config

"xpath": true,
"field_map": {
    "guid": "/products/product/@sd_sku",
    "price": "/products/product/price/@map"
},
"field_map_default": {
    "price": "/products/product/price/@mrp"
}

Result

For the first product, the @map attribute exists so it is used. For the second, @map does not exist, so the engine falls back to @mrp from field_map_default.

field_run: Fields for Processing Only

Sometimes you need a vendor field available during automation processing -- for actions, calculations, or matching -- but you do not want it written to SureDone as an import field or included in an export file. That is what field_run is for.

Fields in field_run follow the same mapping syntax as field_map, but they are excluded from the final bulk file.

Source (vendor CSV)

PartNumber, MFG, Available
ABC-123, Acme Corp, 42

Config

"field_map": {
    "stock": "Available"
},
"field_run": {
    "MFG": "MFG",
    "PartNumber": "PartNumber"
},
"field_format": {
    "title": {
        "combine": {
            "fields": ["MFG", "PartNumber"],
            "delimiter": " - "
        }
    }
}

Result

The MFG and PartNumber fields are used to build the title via the combine format function, but they are not imported as separate fields into SureDone. Only stock (from field_map) and the computed title are written.

response_field_map: Mapping Export Responses

Some export automations send data to an API and receive a response. The response_field_map lets you map fields from that response back into SureDone. This is commonly used to capture confirmation IDs, status codes, or tracking numbers that the vendor returns after receiving your data.

"response_field_map": {
    "vendororderid": "$.order.confirmation_number",
    "vendorstatus": "$.order.status"
}

Like field_map, it supports string, JSONPath, and XPath mapping.

response_field_run: Response Fields for Processing Only

Just as field_run is the processing-only counterpart of field_map, response_field_run is the processing-only counterpart of response_field_map. Fields mapped here are available for actions and logic but are not saved back to SureDone.

"response_field_run": {
    "vendor_error_code": "$.error.code"
}

Identifiers: How Records Are Matched

When importing data, the engine needs to know how to match an incoming record to an existing product or order in SureDone. The identifier field controls which SureDone field is used for this matching.

Defaults:

• For products, the identifier defaults to guid
• For orders, the identifier defaults to oid

Why Change the Identifier?

The most common reason is that your vendor uses their own part number, and multiple SureDone products might share the same vendor SKU. By setting the identifier to a custom field (like vendorsku), the engine matches on that field instead.

Source (vendor CSV)

SKU, Available
VEND-001, 42

Config

"field_map": {
    "vendorstock": "Available"
},
"field_run": {
    "vendorsku": "SKU"
},
"identifier": "vendorsku"

Result

The engine looks up existing SureDone products where vendorsku equals "VEND-001" and updates their vendorstock field. If multiple products share that vendor SKU, all of them get updated.

Multi-Identifier Matching

For advanced scenarios, use the identifiers array to try multiple fields in priority order. The first non-empty match wins:

"identifiers": ["brandA_sku", "brandB_sku", "brandC_sku"]

The engine checks brandA_sku first. If empty or no match, it tries brandB_sku, then brandC_sku.

Putting It All Together

Here is a complete file config for a realistic product import from a distributor's CSV file. It uses field_map for the fields to import, identifier set to guid (the default) for matching, and value_map_default for setting a default condition:

"file_configs": [
    {
        "name": "ECOM_Catalog.csv",
        "create": "start",
        "update": "edit",
        "identifier": "guid",
        "field_map": {
            "guid": "Item Number",
            "brand": "Brand Name",
            "title": "Item Description",
            "cost": "ECOM Price Each",
            "msrp": "MSRP",
            "upc": "UPC Number",
            "weight": "Item Weight",
            "longdescription": "Glamour Copy",
            "bulletpoint1": "Feature 1",
            "bulletpoint2": "Feature 2",
            "bulletpoint3": "Feature 3",
            "media1": "Item Image 1",
            "media2": "Item Image 2",
            "media3": "Item Image 3",
            "mpn": "Item Number",
            "manufacturer": "Brand Name"
        },
        "import_media": true,
        "value_map_default": {
            "condition": "New"
        }
    }
]

This automation:

1. Downloads ECOM_Catalog.csv from the connection
2. Maps vendor columns to SureDone fields using field_map
3. Creates new products ("create": "start") or updates existing ones ("update": "edit")
4. Downloads and attaches images from the URLs in the media columns ("import_media": true)
5. Sets condition to "New" for any item that does not have an explicit condition value (value_map_default)