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/Integration & API/Staging Configuration

Staging Configuration

On this page

The Staging Config tab controls how staged data is validated and merged into production. Settings apply to every row in the table unless a row or a field rule overrides them.

Default import action

The action applied when a staged row's ImportAction column is 0 or not set. The default is Upsert. See Staging Table Structure for what each action does.

Default merge mode

Watch the merge modes in seven minutes — Overwrite next to Fill Empty on the same data, then a sentinel value that clears a field on purpose instead of leaving it untouched:

Staging merge modes in Primentra — overwrite, fill empty and sentinel values

Controls how staged values combine with existing data during an update. It applies only when the import action results in an update — Upsert or Update Only.

ModeBehavior
OverwriteReplace existing values with staged values. A NULL in the staging row is skipped, so existing data is preserved
Overwrite AllReplace existing values including NULLs. A NULL in the staging row clears the production field. On an update, a NULL for a required column is refused with error 128
Fill EmptyOnly update fields that are currently empty in production. Existing values are never overwritten
IgnoreSkip all fields. Use this with field rules to update specific columns only
Overwrite with SentinelLike Overwrite, but a sentinel value explicitly sets a field to NULL

When the import action is Delete or Delete cascade, the merge mode selector is disabled. There is nothing to merge when deleting rows.

Sentinel values

Sentinels solve a common ETL problem. The staging column is NVARCHAR(MAX), and an actual NULL in it means "do not touch this field". So how do you say "set this field to NULL"?

Under the Overwrite with Sentinel merge mode, the engine compares each value against the configured sentinel. On a match, the production field is set to NULL. This works for Text, Boolean, Integer, Decimal, DateTime and Domain columns.

A sentinel never empties a required column. The row is refused with error 128. A blank value for a required Text column on an update is refused the same way under Overwrite, Overwrite All and Overwrite with Sentinel. Under Fill Empty a blank only fills an empty field, so Primentra accepts it.

A number is the sentinel only when it is equal to it. With a number sentinel of 2, a staged 1.6 is an ordinary value. The number sentinel must be a whole number of 28 digits at most. The configuration refuses anything else, such as 2.5.

TypeDefault sentinelApplied to
Text~NULL~Text, Domain and Boolean columns
Number-98765432101234567890Integer and Decimal columns
DateTime5555-11-22T12:34:56DateTime columns

Change these in the Sentinel Values section, collapsed by default under the Processing Schedule.

Field rules

Field rules override the default merge mode and error handling for one attribute. Each attribute has two settings.

Merge Mode — Auto inherits the entity default, or pick any of the five modes above. This lets you set the entity default to Overwrite and mark specific sensitive fields as Fill Empty.

On Error — what happens to the row when this field's value fails validation:

  • Reject the row (default) — the whole row is rejected and listed in Batch History with the reason. Nothing from it is imported.
  • Import row, drop this value — the row is imported without this one value. Its other fields arrive normally, and the dropped value is still recorded in the batch's error list.
The row is never skipped, only the value. Despite what the older name "Skip Field" suggested, this option keeps the record. It just leaves out the value it could not use. Use it for non-critical columns where a source system occasionally sends something unusable and you would rather have the record than lose it.

A dropped value is genuinely left out, not guessed at. An unparseable boolean is not stored as false, an unknown domain code does not become an empty reference, and over-length text is not truncated into the field.

Required fields always reject the row. A required attribute has no On Error choice — the option is disabled. "Import row, drop this value" cannot apply, because a row missing a required value is invalid whatever the field rule says.

Retention

Successfully imported rows and closed batch history are removed after stagingRetentionDays, which defaults to 7. Failed rows are never removed automatically. They are the record of what did not import, and clearing them would hide it. Remove them yourself once you have dealt with them, with the Clear Failed button on the Staging Data tab.

Retention runs from the maintenance step of the scheduler job. See Data Retention.

Business rules

A staging batch is checked against the entity's business rules after the rows are written. A row that breaks an error rule is rolled back to the value it had; the rest of the batch loads. This stops staging from loading data the grid itself would have refused.