On this page
A mapping template tells the platform how to read one file shape: which columns it has, which field each column fills, and how to parse dates, numbers and currency in it. Below: the template's fields, the closed set of transform kinds, and which data streams need a template versus which already read a file without one. Source of truth: the mapping schema and transform library behind CSV/Excel upload and Google Sheets binding.
A template is data, not code: a new file shape from the same source is a new template, never a new build.
Template fields#
| Field | Meaning |
|---|---|
formatVersion |
Version of the template schema itself. |
targetStream |
Which canonical stream the parsed rows land in (for example ad_spend, payouts). |
parser.delimiter |
Column separator: comma, semicolon, pipe or tab. |
parser.quote |
Quote character wrapping a field that contains the delimiter. |
parser.skipLines |
Number of leading rows to skip before the header (title rows, metadata). |
parser.encoding |
Character encoding of the file: utf8, utf16le, latin1, or win1258 for older Vietnamese exports. |
parser.trimHeaders |
Whether whitespace is trimmed from header names before matching. |
parser.headerCaseInsensitive |
Whether header matching ignores case. |
columns[].source |
The column header as it appears in the file. |
columns[].target |
The canonical field the column fills. |
columns[].required |
Whether a missing value in this column rejects the row. |
columns[].transform |
One transform kind (below) plus its options. |
required |
The set of canonical fields that must all resolve for a row to be accepted. |
dedupeKey |
The canonical fields whose combination identifies one row, so re-uploading the same file updates rather than duplicates it. |
Transform kinds (closed set)#
A transform kind converts one source column into one canonical field. The set is closed: adding a new kind changes the underlying transform library, not a template.
| Kind | What it does | Key options |
|---|---|---|
pass |
Keeps the raw string unchanged. | — |
string |
Trims, case-folds, and collapses whitespace, with a fallback for empty values. | fallback value |
int |
Strips thousands separators and currency symbols, drops any decimal portion, and can multiply the result. | thousandsSep, stripCurrency, multiplyBy, parenthesesAsNegative |
decimal |
Same as int but keeps a fractional value. Never used for VND, which is always an integer. |
same as int |
date |
Parses a date against a declared format and emits either a calendar date or a full timestamp. | format, output |
enum |
Maps a source value to one canonical value from an explicit list; an unmatched value can default, reject, or pass through. | value map, unmatched behavior |
concat |
Joins several source columns with a separator, most often to build a synthetic dedupe key. | separator |
constant |
Emits a fixed value regardless of the source column. | fixed value |
Supported data types per plane#
| Data family | Streams | Mapping | Notes |
|---|---|---|---|
| Core commerce (marketplace plane) | Orders, creators, inventory, creator costs, targets, products | Built-in Vietnamese and English column aliases | A template is optional; most marketplace exports load without creating one. |
| Extended commerce and marketing file imports | Ad spend, budget plan, payouts, returns, shipments, warehouse movements, promotions | Mapping template required | A template must exist before the first upload of that stream. |
| Organization datasets (HR, finance, warehouse) | One dataset per bound spreadsheet tab | Mapping template generated from the tab's proposed field schema | Each tab keeps its own template; two tabs never share one, and a tab may only feed a dataset whose rows are its own records. |