Data import
Overview
The import brings master data into the system from a CSV file — guided in four steps, with a preview before anything is written.
Which areas of data are available depends on the installed modules and on your permissions. If no targets are released, the page says so explicitly rather than showing an empty selection.
Core tasks
The four steps, in the order the page walks you through them:
1 — Target. Choose what is to be imported. For each target, the number of fields it knows is shown.
2 — File. Choose a CSV file. The first row has to contain the column names — without a header row there is nothing to map in the next step.
3 — Mapping. Map each detected column to a target field. Required fields are marked with an asterisk. Columns you do not need simply stay unmapped — the file does not have to be trimmed beforehand.
4 — Preview & import. The preview shows what would be created. Only then does the import run.
The preview is the most important step: an import is the fastest way to acquire a great many wrong records at once. Two minutes of checking save an afternoon of cleaning up.
Fields in detail
The wizard carries one record: the import job (ImportJobResource). Steps 1 and 2 create it, step 3 changes it, step 4 starts it.
| Field | Required | Values / format | What it does |
|---|---|---|---|
Import target targetKey | yes | key of an enabled target, max. 40 characters | What is imported — customers, contacts, leads, articles and whatever else the active modules offer. The target determines the field catalogue of the next step; the tile states its size. An unknown target is rejected. The target Orders takes one row per line item and combines rows with the same external order number into one order — as a draft, see Orders. |
File content | yes | CSV, Base64-encoded; at most around 20 MB encoded and 50,000 rows | The source. The first row must contain the column names — without a header row nothing can be mapped in the next step. Delimiter (, or ;) and character set are detected by the server; a byte order mark does no harm. XLSX files are rejected. |
File name fileName | no | text, max. 255 characters | The name the source file is stored under and the run is recognised by. The mask takes it from the chosen file; empty becomes import.csv. |
Field mapping mapping | yes | column name → target field key | Which column goes into which field. This is the actual work and the point at which an import succeeds or goes wrong. Columns you do not need stay unmapped — the file does not have to be trimmed beforehand. An unmapped mandatory field is reported by the wizard, and the affected rows are skipped. |
Duplicate handling duplicateStrategy | no (defaults to skip) | skip (leave existing untouched) · update (overwrite fields) · create (always create new) | What happens to an existing record. How a match is recognised is decided by the target itself — there is no freely chosen matching key. create always creates and is therefore the fastest route to duplicates. |
Brand brandId | no | one of your brands | Which brand's data is written to, and where the source file is stored. Only a brand in which you actually hold the import permission. The mask does not offer the field; it is settable through the interface and automation. |
What the run reports back
The preview (step 4) is the same run in trial mode: it calculates everything without writing. Afterwards, as after the real run, the same figures are available.
| Element | Field | What it means |
|---|---|---|
| State | status | Where the run stands. |
| Detected columns | headers | The header row as the server read it. |
| Suggestion | suggestedMapping | The automatically detected mapping that pre-fills step 3. |
| Field catalogue | fields | The target fields with their mandatory marker — including your custom fields. |
| Rows / created / updated / skipped | total, created, updated, skipped | What the run did or would do. |
| Errors | errorCount, errorRows | Row number, field and message for each rejected row. |
| Run id | batchId | The bracket around all records of one run — the basis of the reversal. |
| Reversal | revertedCount | How many records undo (reverse) has reset. |
Check the preview. An import is the fastest way to acquire many wrong records at once. Two minutes of checking save an afternoon of cleaning up — and if it does go wrong, undo (reverse) is the route, not deleting by hand.
Settings & permissions
- Permission
platform.import.run. Without it the page reports that the permission is missing. - The targets come from the modules. A disabled module offers no import target.
- Custom fields can be imported. Whatever you created under
Custom fields is available in the mapping.
- The import is a writing action and appears in the audit log.
FAQ & troubleshooting
The file cannot be read. Check the format: a CSV with a header row. Save explicitly as CSV from your spreadsheet, not as a workbook.
No import targets are offered. Then no area of data is released for import — module disabled, or permission missing.
A column cannot be mapped to any field. Then the chosen target does not know that field. Columns you do not need stay unmapped — "– do not import –" is the right answer, not a workaround.
The import created wrong data. Undo (reverse) resets the last executed run — it knows its records through the run id. Next time, check the preview; it shows exactly this mistake beforehand.