Documentation

Getting Started

Data Grid

Modeling

Business Rules

Approvals

Users, Roles & Security

Administration

Integration & API

Integration Views Staging Overview Staging Table Structure Staging Configuration Processing & Errors Drift & Rebuild Staging Scheduler REST API Staging API Reference

Installation

Migrating from MDS

Architecture

Documentation/Integration & API/Staging API Reference

Staging API Reference

Technical reference for the staging endpoints. Every path is prefixed with /api/staging and requires an authenticated administrator session.

These endpoints drive the staging screens. They are not part of the public /api/v1/ surface described in REST API, which is the one to use for ordinary record reads and writes with an API key.

Writing rows into a stg table is done in SQL, not over HTTP. These endpoints configure staging, start batches and report on them.

Configuration endpoints

Get staging configuration

GET /api/staging/:entityId/config

Field	Type	Description
`configuration.tableName`	string	The staging table name, for example `stg.Currency`
`configuration.defaultImportAction`	string	Default import action
`configuration.defaultMergeMode`	string	Default merge mode
`configuration.sentinelText`	string	Text sentinel value
`configuration.sentinelNumber`	string	Number sentinel value
`configuration.sentinelDateTime`	string	DateTime sentinel value
`fieldRules[]`	array	Per-attribute merge and error rules
`fieldRules[].attributeName`	string	Attribute name
`fieldRules[].isRequired`	boolean	Required attribute — `onValidationError` is fixed at `error_row`
`fieldRules[].mergeMode`	string	Override merge mode. `auto` inherits the default
`fieldRules[].onValidationError`	string	`error_row` or `skip_field`

Merge mode values are overwrite, overwrite_all, fill_empty, ignore and overwrite_with_sentinel.

Save staging configuration

PUT /api/staging/:entityId/config

Body fields, all optional: defaultImportAction, defaultMergeMode, sentinelText, sentinelNumber, sentinelDateTime, fieldRules.

Enable staging

POST /api/staging/:entityId/enable

Creates the staging table in the stg schema and initializes the configuration record. Returns the new configuration.

Disable staging

DELETE /api/staging/:entityId/disable

Drops the staging table and removes the configuration. Batch history is preserved.

Get staging drift

GET /api/staging/drift

Query parameter entityId is optional — omit it to check every staging-enabled entity at once. Only entities with drift are returned, so an empty array means nothing is out of sync.

Field	Type	Description
`entityId`	integer	Entity id
`entityName`	string	Entity name
`modelId`	integer	Parent model id
`modelName`	string	Parent model name
`tableName`	string	Staging table name
`tableMissing`	boolean	`true` when the `stg` table no longer exists
`severity`	string	`error` (a missing column) or `warning` (orphans only)
`missingColumns[]`	array of string	Attributes with no matching staging column
`orphanColumns[]`	array of string	Staging columns with no matching attribute

Rebuild staging table

POST /api/staging/:entityId/rebuild

Adds missing columns and drops orphan columns so the table matches the entity's attributes. Staged rows are kept — only the values in dropped columns are lost.

Returns columnsAdded, columnsDropped and tableName.

Data endpoints

Get staged rows

GET /api/staging/:entityId/rows

Parameter	Type	Default	Description
`importStatus`	integer	(all)	0 = Ready, 1 = OK, 2 = Error, 3 = Processing
`batchId`	integer	(all)	Filter by batch
`pageSize`	integer	50	Rows per page
`page`	integer	1	Page number

The response carries three parts:

rows[] — the staged rows, with every system and attribute column
summary — TotalRows, ReadyRows, OkRows, ErrorRows, ProcessingRows
columns[] — attribute metadata: attributeId, name, displayName, dataType, sortOrder

Process a batch

POST /api/staging/:entityId/process

Body: batchTag (optional label) and batchId (optional, to reprocess a specific batch).

Returns batchId, status, totalRows, successRows, errorRows and skippedRows.

Retry failed rows

POST /api/staging/:entityId/retry

Puts failed rows back in the queue as Ready, clearing each row's error and detaching it from the batch it failed in. Body: batchId (optional) scopes it to one batch; without it every failed row for the entity is requeued.

Returns requeuedRows.

Recover a stuck batch

POST /api/staging/:entityId/recover

Releases rows left claimed by a batch that never finished, and closes the dead batch as Failed. Body: staleMinutes (default 60) sets how old a claim must be to count as stuck.

Returns recoveredBatches and releasedRows.

Clear rows

DELETE /api/staging/:entityId/rows?status=processed

Deletes finished rows across every batch for the entity. status accepts processed (the default) or all.

DELETE /api/staging/batches/:batchId/clear?status=processed does the same for one batch.

Both return deletedRows.

Batch history endpoints

Get batches

GET /api/staging/:entityId/batches

Query parameters pageSize (default 50) and page (default 1). Returns batches[] and totalCount.

Get batch errors

GET /api/staging/batches/:batchId/errors

Query parameters pageSize (default 100) and page (default 1). Returns errors[] with row-level detail, and summary with aggregate counts.

Clear batch history

DELETE /api/staging/:entityId/history

Removes all completed and failed batch records for the entity, with their staging rows and error details. Running and queued batches are kept. Returns deletedBatches.

Scheduler endpoints

Get scheduler configuration

GET /api/staging/:entityId/scheduler

Returns the configuration plus live runtime fields: isRunning, pendingRows, oldestRowAge, nextScheduledRun, lastCompletedAt.

Save scheduler configuration

PUT /api/staging/:entityId/scheduler

Field	Type	Description
`processingMode`	string	`manual`, `scheduled` or `triggered`
`scheduleType`	string	`interval`, `daily`, `weekly` or `monthly`
`intervalMinutes`	integer	Interval in minutes, for the interval type
`runTimes`	string	Comma-separated times, for example `06:00,18:00`
`runDays`	string	Comma-separated days, for example `Mon,Wed,Fri`
`runDaysOfMonth`	string	Comma-separated days, for example `1,15`
`triggerOnNewRows`	boolean	Enable the new-rows trigger
`triggerRowThreshold`	integer	Row count threshold
`triggerIdleMinutes`	integer	Idle timeout in minutes
`triggerDebounceSeconds`	integer	Debounce window, default 60
`isEnabled`	boolean	Enable or disable the scheduler

Validation is enforced server-side:

scheduled requires scheduleType
triggered requires at least one trigger
manual clears every schedule and trigger field

Get scheduler log

GET /api/staging/:entityId/scheduler/log

Query parameters pageSize (default 50) and page (default 1). Returns log[] and totalCount.

Test the scheduler

POST /api/staging/:entityId/scheduler/test

Evaluates the current conditions without firing a batch — what the dispatcher would do right now.

Field	Type	Description
`wouldFire`	boolean	Whether a batch would fire
`reason`	string	Why it would or would not
`pendingRows`	integer	Unprocessed rows
`oldestRowAge`	integer	Age of the oldest unprocessed row, in minutes
`nextScheduledRun`	datetime	Next scheduled execution

Database tables

Table	Contents
`StagingConfigurations`	Per-entity import action, merge mode and sentinel values. One row per staging-enabled entity
`StagingFieldRules`	Per-attribute merge mode and error handling
`StagingBatches`	Batch history: one row per processing run, with status, counts and timing
`SchedulerConfigurations`	Per-entity processing mode, schedule, triggers and runtime state
`SchedulerLog`	Every scheduler event — fired, skipped, completed, error

Stored procedures

Procedure	Description
`usp_Staging_CreateTable`	Creates the staging table in the `stg` schema
`usp_Staging_DropTable`	Drops the staging table and its configuration
`usp_Staging_GetConfiguration`	Returns configuration and field rules
`usp_Staging_SaveConfiguration`	Saves configuration and field rules
`usp_Staging_GetStagedRows`	Paginated staged rows with a status filter
`usp_Staging_ProcessBatch`	The batch processing engine
`usp_Staging_GetBatches`	Paginated batch history
`usp_Staging_GetErrors`	Row-level errors for a batch
`usp_Staging_RetryErrors`	Requeues failed rows as Ready
`usp_Staging_RecoverStuck`	Releases rows held by a batch that never finished
`usp_Staging_ClearRows`	Deletes rows by status across every batch
`usp_Staging_ClearBatch`	Deletes rows from one batch
`usp_Staging_ClearBatchHistory`	Clears completed batch records
`usp_Staging_GetDrift`	Compares staging tables against entity attributes
`usp_Staging_RebuildTable`	Syncs staging columns with entity attributes
`usp_Scheduler_GetConfig`	Scheduler configuration with live stats
`usp_Scheduler_SaveConfig`	Saves scheduler configuration
`usp_Scheduler_GetLog`	Paginated scheduler event log
`usp_Scheduler_TestRun`	Dry-run evaluation of current conditions
`usp_Scheduler_CalculateNextRun`	Calculates the next scheduled execution
`usp_Scheduler_Dispatch`	The dispatcher, called every 60 seconds by SQL Agent

REST API — the public /api/v1/ record endpoints and API-key authentication
Staging Configuration — what these configuration fields do in the UI
Processing & Errors — the error codes the error endpoints return
Staging Scheduler — the screens these scheduler endpoints drive
Database Schema — where these tables sit in the wider schema

REST API

Ready to get started?

Start managing your master data with Primentra today.

View Pricing