What Are Value Maps?
Field mapping (covered in the previous article) handles translating field names -- your vendor says "PartNumber", SureDone says "guid". But what about the values inside those fields? Your vendor might report stock status as "In Stock" or "Backordered", while SureDone expects a number. A supplier might send condition codes like "1" and "2" when you need "New" and "Used".
Value maps let you define a lookup table that automatically converts values as data flows through the automation. They work during imports, transforming vendor values into the format SureDone expects.
value_map: Translating Values
The value_map object supports two forms, and you can use both in the same configuration.
Form 1: Global Value Map (Applies to All Fields)
A global value map converts a value wherever it appears, regardless of which field it is in:
"value_map": {
"source_value": "suredone_value"
}
Source (vendor CSV)
SKU, Condition, Shipping
ABC-123, New, USPS
DEF-456, Used, USPS
Config
"field_map": {
"guid": "SKU",
"condition": "Condition",
"shipping": "Shipping"
},
"value_map": {
"USPS": "United States Postal Service"
}
Result
| guid | condition | shipping |
|---|---|---|
| ABC-123 | New | United States Postal Service |
| DEF-456 | Used | United States Postal Service |
Every occurrence of "USPS" in any field gets replaced with "United States Postal Service".
Form 2: Field-Specific Value Map
A field-specific value map only applies to one particular SureDone field:
"value_map": {
"suredone_field": {
"source_value": "suredone_value"
}
}
Source (vendor CSV)
SKU, VendorStock, VendorStatus
ABC-123, In Stock, 5
DEF-456, Low Stock, 4
GHI-789, Out of Stock, 1
Config
"field_map": {
"guid": "SKU",
"stock": "VendorStock",
"status": "VendorStatus"
},
"value_map": {
"stock": {
"In Stock": 5,
"Low Stock": 1,
"Out of Stock": 0,
"Call For Availability": 0
},
"status": {
"1": "Do Not Reorder",
"2": "Do Not Stock",
"3": "Special Order",
"4": "Discontinued",
"5": "Active",
"6": "Inactive"
}
}
Result
| guid | stock | status |
|---|---|---|
| ABC-123 | 5 | Active |
| DEF-456 | 1 | Discontinued |
| GHI-789 | 0 | Do Not Reorder |
The stock field converts text statuses to numeric quantities, while the status field converts numeric codes to descriptive labels. Each mapping only applies to its own field.
Combining Both Forms
You can mix global and field-specific value maps in the same value_map object:
"value_map": {
"USPS": "United States Postal Service",
"stock": {
"In Stock": 5,
"Out of Stock": 0
},
"condition": {
"N": "New",
"U": "Used",
"R": "Refurbished"
}
}
The global mapping for "USPS" applies to any field. The mappings inside stock and condition only apply to those specific fields.
value_map_default: Handling Missing Data
The value_map_default object sets a default value for a SureDone field when the source data is empty or missing.
"value_map_default": {
"suredone_field": "default_value"
}
Source (vendor CSV with missing data)
SKU, Condition, Stock
ABC-123, New, 10
DEF-456, , 5
GHI-789, Refurbished,
Config
"field_map": {
"guid": "SKU",
"condition": "Condition",
"stock": "Stock"
},
"value_map_default": {
"condition": "New",
"stock": "0"
}
Result
| guid | condition | stock |
|---|---|---|
| ABC-123 | New | 10 |
| DEF-456 | New (default applied) | 5 |
| GHI-789 | Refurbished | 0 (default applied) |
DEF-456 had an empty condition, so the default "New" was applied. GHI-789 had an empty stock value, so the default "0" was applied.
value_map_default only applies when a field's value is empty or missing. If a value exists but does not match any value_map entry, it passes through unchanged -- the default is not used as a fallback for unmatched values.value_map_default can set values for fields that are not even in your field_map. This is useful for always setting a constant value during import -- for example, marking shipping status as "COMPLETE" even though it is not in the vendor's data:
"value_map_default": {
"shippingstatus": "COMPLETE",
"shipdate": "{{NOW}}"
}
The {{NOW}} variable inserts the current UTC date and time.
Combining value_map and value_map_default
The two features work together for empty values. The value_map handles known conversions for non-empty values, and value_map_default fills in when a value is empty or missing.
Source (vendor CSV)
SKU, VendorCondition, VendorStatus
ABC-123, N, active
DEF-456, U, discontinued
GHI-789, , unknown_status
Config
"field_map": {
"guid": "SKU",
"condition": "VendorCondition",
"status": "VendorStatus"
},
"value_map": {
"condition": {
"N": "New",
"U": "Used",
"R": "Refurbished"
},
"status": {
"active": "active",
"discontinued": "inactive",
"clearance": "active"
}
},
"value_map_default": {
"condition": "New",
"status": "draft"
}
Result
| guid | condition | status |
|---|---|---|
| ABC-123 | New (mapped from "N") | active (mapped from "active") |
| DEF-456 | Used (mapped from "U") | inactive (mapped from "discontinued") |
| GHI-789 | New (default -- empty source) | unknown_status (no match in value_map, but not empty -- passes through unchanged) |
For GHI-789, the empty condition falls through to the default "New". The status "unknown_status" does not match any value_map entry, but because it is not empty, the default is not applied -- the original value passes through unchanged.
Common Patterns
Mapping Boolean Strings
Vendors often send boolean-like values as strings. Use a value map to normalize them:
"value_map": {
"taxable": {
"yes": "1",
"Yes": "1",
"YES": "1",
"true": "1",
"True": "1",
"no": "0",
"No": "0",
"NO": "0",
"false": "0",
"False": "0"
}
}
Status Mapping
Convert vendor-specific status codes to your SureDone workflow statuses:
"value_map": {
"status": {
"A": "active",
"D": "inactive",
"P": "draft",
"X": "inactive"
}
},
"value_map_default": {
"status": "draft"
}
Shipping Service Normalization
Standardize shipping carrier names from order tracking imports:
"value_map": {
"shipservice": {
"FDX GND": "FedEx Ground",
"FDX 2DAY": "FedEx 2Day",
"FDX OVRN": "FedEx Overnight",
"UPS GRD": "UPS Ground"
}
},
"value_map_default": {
"shipcarrier": "FedEx"
}