Staging Configuration
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:
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.
| Mode | Behavior |
|---|---|
| Overwrite | Replace existing values with staged values. A NULL in the staging row is skipped, so existing data is preserved |
| Overwrite All | Replace existing values including NULLs. A NULL in the staging row clears the production field |
| Fill Empty | Only update fields that are currently empty in production. Existing values are never overwritten |
| Ignore | Skip all fields. Use this with field rules to update specific columns only |
| Overwrite with Sentinel | Like 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.
| Type | Default sentinel | Applied to |
|---|---|---|
| Text | ~NULL~ | Text, Domain and Boolean columns |
| Number | -98765432101234567890 | Integer and Decimal columns |
| DateTime | 5555-11-22T12:34:56 | DateTime 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.
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.
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.
Related
- Staging Table Structure — the columns these rules act on
- Processing & Errors — what a failed field looks like afterwards
- Rules in Staging & Imports — how business rules apply to a batch
- Data Retention — where
stagingRetentionDaysis set - Staging API Reference — setting this configuration over HTTP