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.
Move from an old system: tickets, history and portal accounts. Three targets take over the support data of a predecessor system:
- Old tickets — one row per ticket. Old system, ticket ID in the old system and subject
are required; the ID anchors the history and detects duplicates. The status follows your old → new mapping in the file: a known status key applies, an unknown one becomes "closed", an empty one the default status. Every ticket gets a new case number of the brand; the old number is kept as a legacy reference, the time of receipt comes from the file.
- Old ticket history — one row per message, matched via old system and ticket ID. The direction
is in (from the customer), out (reply) or note (internal note, invisible in the customer portal). Import the tickets first, then the history.
- Portal accounts — one row per account with email and customer (customer number or ID), optionally
name, language and portal permissions (empty = view tickets only; grant more via the column or later by hand). Taken-over accounts are set to Invited and have no password — passwords from other systems cannot be transferred. The import sends no email, not even the dry run. Invitations only go out when you trigger Send invitations under Portal accounts; taking up the invitation activates the account. An email that already belongs to another customer is rejected.
The data arrives quietly: no notification, no automation, no service-commitment clock — a taken-over ticket is history, not a new request. Undo (reverse) removes what a run created.
Take over the suppression list (marketing). The target Suppression list (marketing: unsubscribes, bounces) takes one email or hash per row (only 64-character values from Octibiz itself — foreign MD5 or SHA values never match), plus reason (unsubscribe, bounce, complaint, manual; German values such as "Abmeldung" or "unzustellbar" are recognised, empty means manual), suppressed since and channel (empty = all channels). Without a brand the suppression is global, with a brand only there. An existing suppression is skipped (overwrite only adds address and channel), the dry run writes nothing, and there is no revert. Unsubscribe and complaint withdraw the confirmed consent — see Consents & suppression.
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. The target Legacy documents fills the read-only archive of invoices (header data without accounting effect, customer via the customer number); an existing legacy document is not changed even with overwrite, see Invoices. The targets Old tickets, Old ticket history and Portal accounts take over the support data of a predecessor system (see above); a taken-over message stays unchanged even with overwrite. The target Vacation accounts (opening balance as of a cut-off date) takes on entitlement, carryover, and days already taken as of the cut-off date per employee and year from the legacy tool; the imported entitlement then counts as manually set, see Availability. The target Product also takes on properties (properties, "group:value", several separated by ; — group and value by code or name) and media (media, file ULIDs or file names of files uploaded to the file storage beforehand; the first is the main image, further ones the gallery); both replace the existing assignment, anything unknown is a row error, see Products. The target Stock (standard warehouse) takes on the opening stock: the figure is the counted stock (new goods), the difference is booked as an adjustment with the run as its source, optionally with a unit cost for valuation; repeating the run books nothing, revert books the takeover back. With the multi-warehouse module, Stock per warehouse and bin applies instead. The target Customer prices (negotiated price lists per customer) takes terms per customer (customer via the customer number, item via the item number); terms above the approval threshold wait for approval, see Prices & units. The targets Customer groups and Customer group assignments take over groups (by their key) and the assignment customer → group (group key and customer number). The target Packagings per article takes pack sizes per item (item via the item number, match via item and pack-size code, parent pack size via its code); it is preselected from the Packaging tab of the item, and revert deletes the created pack sizes again, see Prices & units. |
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.