Import from Excel & CSV
On this page
Import loads a spreadsheet, a CSV file or a JSON file straight into the entity you are looking at. It is a four-step wizard: Upload → Column mapping → Preview → Result.
Supported file types: .xlsx, .xls, .csv and .json.
Watch the four steps done in 70 seconds — a CSV of six suppliers goes into an empty entity:
Step 1 — Upload
Drop a file on the upload area, or click it to browse. A confirmation line reports the file name, the number of data rows and the number of columns.
- Multi-sheet workbooks get a Sheet dropdown. Pick a sheet and the wizard re-reads the file
- The first row of the sheet is always treated as the header row. Its headings must match your column names exactly, the same rule Paste rows follows. Export the entity first if you want a file with the headings already correct
- More than 5,000 rows — a warning appears. The import still proceeds
- More than 50,000 rows — the file is refused. Split it and import the parts
A JSON file must be an array of objects. The grid's own JSON export is unwrapped automatically, so a file you exported can be imported again without editing.
Numbers, dates and Yes/No in a file
A file is read the strict way, because nobody watches it and it came out of another system:
| Data type | What a file must hold |
|---|---|
| Whole number | 42 or -7. 42.0 works too, because it is a whole number |
| Decimal | A dot for the decimal and no thousands separator: 1234.56 |
| Date | ISO: 2026-01-31, or 2026-01-31 14:30:00 with a time. A date cell from Excel works too |
| Yes/No | 1, true or yes for yes, and 0, false or no for no. Any other word refuses the row |
| Reference | The code, the exact name, or {CODE} Name |
When you type or paste, a comma works as the decimal point too, because there you see the result before you save. Number Formats has the rule for every route, examples, and how to make a clean file from a Dutch or German Excel.
A date in a file is read as ISO, not in the column's own Date format. The file cannot see that setting, so the same text could mean two different days: 01-02-2026 is the first of February or the second of January, and nothing in the file says which. Typing and pasting still follow the column format, because there you see the result before it is saved.
The column format does decide one thing: whether a time is kept. Import 2026-01-31 14:30:00 into a column whose format has a time, and the time is stored. Import it into a date-only column, and it is stored at midnight, the same as when you type it or load it through staging.
A Yes/No column can show its own labels on screen, such as Ja and Nein. A file holds the words in the table above, not the labels. An export always writes 1 and 0, so a file you export is a file you can import again.
Step 2 — Column mapping
The wizard matches your file's headers against the entity's attributes. Matching ignores case, spaces and punctuation, so First Name, firstname and first_name all reach the same attribute.

The table shows one row per file column: the header, up to three sample values, and a Maps to dropdown. Change any dropdown to correct the guess, or choose — skip column — to leave a column out. Required attributes are marked with an asterisk.
Code and Name must both be mapped. Until they are, a red note names the missing one and Next stays disabled.
On an entity with Auto-generate Code, only Name is required — but Code is still offered, and mapping it is usually what you want. The code is what decides whether a row updates an existing record or creates a new one, so an unmapped Code column leaves Overwrite and Skip with nothing to match, and re-importing a file you exported would add every row a second time. Map it, and any row whose Code cell is empty still gets a generated code.
Step 3 — Preview
This step reports what the wizard found and asks how to handle it. Three cards head the page:
- Total rows — data rows in the file
- Validation errors — problems found while reading the file
- Ready to import — rows with no local error, until the server check below has an answer. Once it does, this card switches to the server's own count, because the two can disagree: a file that passes every local check can still contain a row the database refuses
Validation errors
Errors are listed by row number, field and message. The first 20 are shown, with a count of the rest. The checks are:
| Error | Cause |
|---|---|
Code is required | The Code cell is empty on an entity that does not auto-generate codes |
Name is required | The Name cell is empty |
Duplicate code "X" in file | The same Code appears twice in the file |
Required field is empty | A required attribute has no value |
"X" is not a valid integer / number / date | The value does not fit the target type |
When there are errors, choose what to do with them:
- Skip invalid rows — import the valid rows, leave the rest
- Stop — import nothing. Correct the file and try again
Conflict action
Choose what happens when a Code already exists in the entity:
| Option | A Code that is new | A Code that already exists |
|---|---|---|
| Skip | Imported as a new record | Left exactly as it is — nothing in the file touches it |
| Overwrite | Imported as a new record | Updated with the values from the file, matched on Code |
| Replace all | Imported | Every existing record is deleted first, so the file becomes the whole dataset |
Both columns matter. Skip does not skip the file — it skips only the rows that would collide, and still imports the rest. A file of 100 rows where 30 codes already exist imports 70 and leaves those 30 alone.
Whether you are told about the 30 depends on Import the other rows anyway:
- Off — they are skipped quietly. The result says 70 imported and does not mention the rest
- On — they are listed at Preview with the reason The code … already exists in this entity
Replace all shows a red warning, because it is not reversible.
The options you can pick depend on your permissions on the entity. Skip needs Create. Overwrite also needs Update, and Replace all also needs Delete. An option you do not have the permission for is grayed out and names the permission it needs. See Roles & Permissions.
Empty cells clear the existing value
By default, Overwrite leaves a field as it is when the file has an empty cell for it. To empty the field instead, select Overwrite. A checkbox appears under it: Empty cells clear the existing value. Tick it.

The checkbox is off at the start of every import. Primentra does not remember it. It shows only with Overwrite. If you pick another option, it disappears and unticks.
Preview then shows a line such as 12 values in 4 records will be cleared. The Result step shows 12 values in 4 records cleared. A cell that is already empty in the database is not counted. The audit log line for the import ends with , 12 values cleared.
The rules:
- Only mapped columns clear. A column that is not in the file, or that you set to — skip column —, keeps its values.
- A new record writes nothing for an empty cell. There is no value to clear.
- A required column is never cleared. The row is refused with the reason
"Country" is required, so an empty cell cannot clear it. Without Import the other rows anyway, the whole import stops withRow 7: "Country" is required, so an empty cell cannot clear it.Nothing is written. - Code never clears. It is the key that matches the file to the records.
- An empty Name keeps the existing Name. This holds with or without the checkbox.
- A read-only column refuses the clear. If you may read a column but not change it, a clear that would change the value is refused, like any other write to it.
- A default rule fills the field again. If a business rule sets a default for the column, the field gets that default after the clear. Preview counts that field as cleared, because defaults run only on import. The Result step does not count it.
Skip, Replace all and the other import routes ignore this checkbox. For staging loads, the merge mode Overwrite All works the same way. See Staging Configuration.
Business rules
Refuse rows that break an error rule is on by default. A row that fails an error-severity rule is not imported; the rest of the file still loads. Warnings never block.
Clear the checkbox to load everything and review afterwards with the failing-rows filter in the grid. See Rules in Staging & Imports.
Server-side reject check
Before you can import, Primentra checks the file against the database. This catches problems no local check can see — a code that already exists, a value the column is too narrow for, a domain reference to a record that is not there — without writing anything.
While it runs, the step shows Checking the file against the database…. When it finishes, one of two things appears:
- No data problems found in this file — every row would be written. Nothing else to do.
- N rows would be rejected because of data problems — a red panel groups the rejects by reason, with a table of the row number, code and reason underneath. The full list of reasons is below.

Watch it on a bigger file with a domain reference that points at nothing:
If any row is rejected, a checkbox appears: Import the other rows anyway. Import stays disabled until you tick it — a partial import never happens without you confirming it. Ticking it does not change which rows are rejected; it only allows the rest to load.
Changing the conflict action, the business-rule checkbox, or the error-handling choice re-runs this check and unchecks the box, because any of the three can change which rows the database would refuse.
Why a row is rejected
| Reason | Cause |
|---|---|
| Code is missing | The Code cell is empty and the entity does not auto-generate codes |
| Code already used earlier in the file | Two rows in the file share the same Code |
| Code already exists | The Code is already in the entity and the conflict action is Skip |
| Name is missing | The Name cell is empty |
| An empty cell cannot clear a required field | Empty cells clear the existing value is on, and a required column has an empty cell. The reason reads "Country" is required, so an empty cell cannot clear it |
| A required field has no value | A custom attribute marked Required is empty in the file. For a domain attribute the reason reads "Country" is required and has no value |
| Code is too long | The Code is longer than the column allows (200 characters) |
| Name is too long | The Name is longer than the column allows (500 characters) |
| A value is too long | A text value is longer than the field's configured width |
| A value has the wrong type | A value will not convert to its field's data type — text in a number field, for example |
| A domain value for a source you may not read | The role has no Read on the domain source (error 4113). The reason reads You may not read Countries, so Country cannot be filled. |
| A domain reference matches nothing | The value does not match any record in the linked entity. The reason reads "Country" refers to "XX", which matches no record in the linked entity |
| The row breaks a business rule | Found after the import, when Refuse rows that break an error rule is on. The row is put back to what it was before |
Domain columns and self references
A domain column takes the code of a record of its source. The name and the {CODE} Name form work too. An empty cell loads with no link, unless the attribute is required.
When the column points at its own entity, for example Employees.Manager, the rows can come in any order. Primentra writes every row first and links the managers after. Chris can come before Bram, and Bram before Anna. A manager code that matches no row of the database or of the file refuses that row, and the rows that point at it. Domain Sources & Links shows each case with the file.
Approval bypass
If the entity has Requires approval enabled, the import is refused. A bulk load bypassing review would make the approval setting meaningless, and 5,000 rows arriving as one request is not a review anybody can perform. Switch Requires approval off on the entity if you intend to load the file directly, and switch it back on afterwards.
While the import runs
After you click Import, the preview makes way for the list of steps: Read the file, Delete the current rows (only with Delete and import), Check the rows (only when you import the other rows anyway), Write the rows, Write the values and Check the business rules. A tick marks each finished step, and the running step counts its seconds. On a file of 20,000 rows that can take half a minute.
The import is one transaction: it writes all rows or none. Keep the window open to see the result. If the connection breaks before the result arrives, the result page says so. Then open the grid before you import again, because the import either finished or wrote nothing.
Step 4 — Result
Counters report the outcome: Inserted, Updated, Skipped, Rejected and Errors. The Rejected counter only appears when the import rejected at least one row.
A rejected row was never written. If any were, a table below the counters lists them by row, code and reason, and Download rejected rows writes an Excel file with the same columns for every rejected row — not only the ones shown on screen. Fix those rows in the original file and import them again.
A note underneath the counters also reports any rows a business rule refused, if you left that check on.
Close & refresh closes the wizard and reloads the grid.
Constraints and business rules are not the same thing
Two different kinds of check can refuse a value, and only one of them can be waived.
A constraint is part of the entity's shape: the data type, the maximum length, whether the field is required, and whether it accepts negative numbers. It is enforced on every route, every time, and there is no option to skip it. A row that breaks a constraint cannot be written at all — the column would not hold it.
A business rule is a policy you wrote on top of that shape: a value must be within a range, a field must be filled when another one is, a date must be in the past. An import can be told to carry on past a rule it fails, with Skip business rule failures, because the row is still a row the database can hold. You decided the policy, so you may decide to set it aside for one file.
So "this field does not accept negative numbers" behaves exactly like "this field is required", not like a rule you wrote. Skip business rule failures does not reach it.
What each route checks
Every route enforces the same constraints. What differs is only what a route can accept as input, because in the grid a person is watching the result and in a file nobody is.
| Grid typing | Copy / paste | Excel & CSV import | Staging | REST API | |
|---|---|---|---|---|---|
| Decimal mark | dot or comma | dot or comma | dot only | dot only | dot only |
| Thousands separators | not accepted | only what the grid itself wrote | not accepted | not accepted | not accepted |
| Yes/No values | 1/0 and the labels shown | 1/0 and the labels shown | 1/0, true/false, yes/no | 1/0 | 1/0 |
| Wrong data type | refused | refused | row rejected | row failed | refused |
| Too long for the field | refused | refused | row rejected | row failed | refused |
| Required field empty | refused | refused | row rejected | row failed | refused |
| Negative in a field that refuses them | refused | refused | row rejected | row failed | refused |
| Business rule failure | refused | refused | skippable | configurable per field | refused |
A comma is accepted where a person can see what happened to it. In a file it is genuinely ambiguous — 1,234 is a thousand and a bit in one country and one and a bit in another — so a file, staging and the API take a plain dot and no grouping, whatever the screen is set to display.
Related
- Export: produce a file in the shape the wizard expects
- Adding, Deleting & Pasting: Paste rows, for a quick block of new records
- Rules in Staging & Imports: how business rules judge imported rows
- Staging Overview: loading data from another system on a schedule
- Number Formats: the decimal separator on every route, with examples
- MDS Manual Import: moving many entities at once out of MDS
Did not find what you need?
Try the troubleshooting pages, or ask us.