Skip to content
MSO CloudDocumentation

Import mapping template

On this page

A mapping template tells the platform how to read one file shape: which columns it has, which canonical field each column fills, and how to parse dates, numbers and currency in it. A template is data, not code: a new file shape from the same source is a new template, never a new build.

File header rowMã trả hàngstringtrimmed textexternal_return_idMã đơn hàngstringtrimmed textexternal_order_idNgày trảdateformat DD/MM/YYYYreturn_dateTiền hoàn (₫)int'.' thousands, whole VNDrefund_vnd(no column)paramsupplied at uploadplatformCanonical fields (returns)targetStream: returns · dedupeKey: [platform, external_return_id] · amounts are whole VND, never decimals
Example: one returns template. Each column carries exactly one transform; the dedupe key makes a re-upload an update.

Template fields#

Field Meaning
formatVersion Version of the template schema itself (1 or 2; 2 adds header aliases)
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 Leading rows to skip before the header (title rows, metadata), up to 50
parser.encoding 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
parser.headerAliases Alternative spellings per canonical header; the canonical header wins when both are present
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 plus its options
required Canonical fields that must all resolve for a row to be accepted
dedupeKey Canonical fields that identify one row, so re-uploading the same file updates instead of duplicating
parameters Values the uploader supplies at run time, read by a param transform
secondFile A companion file joined 1:1 by row position; the only join supported

Transform kinds#

A transform converts one source column into one canonical field. The set is closed: a new kind changes the transform library, not a template. Amounts are whole VND; decimal is never used for money.

Kind What it does
pass Keeps the raw string unchanged
string Trims, case-folds and collapses whitespace, with a fallback for empty values
int, decimal Strips thousands separators and currency symbols; options for multiplier and parentheses-as-negative
date Parses against a declared format and emits a calendar date or a timestamp
bool Reads a truthy or falsy flag; an empty cell stays unknown, never false
enum Maps a source value to a canonical one; unmatched values default, reject or pass
concat, constant, product Joins several columns; emits a fixed value; multiplies two numeric columns (price times quantity)
param Reads a value the uploader supplied for this run, named in parameters
code_map, split_list Maps a code through a declared table; splits a delimited cell into a list
sentiment_map, taxonomy_single, taxonomy_multi, taxonomy_entity Content-intelligence labels: sentiment score, one label, a closed list, an open entity vocabulary
confidence_ladder, evidence_span, relevance_gate Content-intelligence quality: a rung in basis points, a quoted span, a pre-filtered-file detector
eligibility_flag, derived_cardinality, link_normalize Content-intelligence structure: a base-gating flag, a recounted label count, a stable link

Which streams need a template#

Data family Streams Mapping
Core commerce (marketplace plane) Orders, creators, inventory Built-in Vietnamese and English aliases; a template is optional
Extended commerce and marketing file imports Ad spend, budget plan, payouts, returns, shipments, warehouse movements, promotions A template must exist before the first upload
Organization datasets (HR, finance, warehouse) One dataset per bound spreadsheet tab Generated from the tab's proposed field schema; one template per tab