Documentation
Use Primentra
Getting Started
Data Grid
Approvals
Set up
Modeling
Business Rules
Users & Roles
Sign-in & Security
Install and run
Installation
Administration
Integration & API
Architecture
Migrate from MDS
Migrating from MDS
Documentation/Data Grid/Import from Excel & CSV

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:

How to import a CSV or Excel file into Primentra
Import needs a database. In the interactive demo the button reports that no database is connected.

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 typeWhat a file must hold
Whole number42 or -7. 42.0 works too, because it is a whole number
DecimalA dot for the decimal and no thousands separator: 1234.56
DateISO: 2026-01-31, or 2026-01-31 14:30:00 with a time. A date cell from Excel works too
Yes/No1, true or yes for yes, and 0, false or no for no. Any other word refuses the row
ReferenceThe 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 column mapping step matching file headers to entity attributes
The column mapping step matching file headers to entity attributes(click to enlarge)

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:

ErrorCause
Code is requiredThe Code cell is empty on an entity that does not auto-generate codes
Name is requiredThe Name cell is empty
Duplicate code "X" in fileThe same Code appears twice in the file
Required field is emptyA required attribute has no value
"X" is not a valid integer / number / dateThe 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:

OptionA Code that is newA Code that already exists
SkipImported as a new recordLeft exactly as it is — nothing in the file touches it
OverwriteImported as a new recordUpdated with the values from the file, matched on Code
Replace allImportedEvery 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 Preview step with Overwrite selected and Empty cells clear the existing value ticked, showing how many values will be cleared
The Preview step with Overwrite selected and Empty cells clear the existing value ticked, showing how many values will be cleared(click to enlarge)

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 with Row 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.
The empty Name change is a fix. Before version 1.2026.10.15, an empty Name cell on Overwrite stored an empty Name.

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.
The Preview step reporting one rejected row, grouped by reason, with the confirmation checkbox to import the rest
The Preview step reporting one rejected row, grouped by reason, with the confirmation checkbox to import the rest(click to enlarge)

Watch it on a bigger file with a domain reference that points at nothing:

How to import a file with bad rows in Primentra

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.

This check covers data problems only. A business rule is evaluated against rows that exist in the database, so it cannot be checked before anything is written. Rule failures are still caught — they are refused and put back after the import, and they appear in the same report on the result screen.

Why a row is rejected

ReasonCause
Code is missingThe Code cell is empty and the entity does not auto-generate codes
Code already used earlier in the fileTwo rows in the file share the same Code
Code already existsThe Code is already in the entity and the conflict action is Skip
Name is missingThe Name cell is empty
An empty cell cannot clear a required fieldEmpty 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 valueA 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 longThe Code is longer than the column allows (200 characters)
Name is too longThe Name is longer than the column allows (500 characters)
A value is too longA text value is longer than the field's configured width
A value has the wrong typeA 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 readThe 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 nothingThe 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 ruleFound 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 typingCopy / pasteExcel & CSV importStagingREST API
Decimal markdot or commadot or commadot onlydot onlydot only
Thousands separatorsnot acceptedonly what the grid itself wrotenot acceptednot acceptednot accepted
Yes/No values1/0 and the labels shown1/0 and the labels shown1/0, true/false, yes/no1/01/0
Wrong data typerefusedrefusedrow rejectedrow failedrefused
Too long for the fieldrefusedrefusedrow rejectedrow failedrefused
Required field emptyrefusedrefusedrow rejectedrow failedrefused
Negative in a field that refuses themrefusedrefusedrow rejectedrow failedrefused
Business rule failurerefusedrefusedskippableconfigurable per fieldrefused

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.