Staging API Reference
Technical reference for the staging REST API. All endpoints are prefixed with /api/staging and require authentication.
Approval workflows and staging
The staging pipeline writes directly to master data and does not go through the approval workflow, even if the entity has Requires approval enabled. This applies to both scheduled and manually triggered batch processing. Staging is treated as a trusted, pre-validated data channel — the assumption is that validation happens in the source system before rows are written to the staging table.
Configuration endpoints
Get staging configuration
GET /api/staging/:entityId/config
Returns the staging configuration and field rules for an entity.
Response:
| Field | Type | Description |
|---|---|---|
configuration.tableName | string | The staging table name (e.g. stg.Currency) |
configuration.defaultImportAction | string | Default import action code |
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[].mergeMode | string | Override merge mode (null = inherit default) |
fieldRules[].onValidationError | string | ErrorRow or SkipField |
Save staging configuration
PUT /api/staging/:entityId/config
Request body:
| Field | Type | Required |
|---|---|---|
defaultImportAction | string | No |
defaultMergeMode | string | No |
sentinelText | string | No |
sentinelNumber | string | No |
sentinelDateTime | string | No |
fieldRules | array | No |
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.
Rebuild staging table
POST /api/staging/:entityId/rebuild
Adds missing columns and removes orphan columns to match the current entity attributes. Returns a list of changes made.
Data endpoints
Get staged rows
GET /api/staging/:entityId/rows
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
importStatus | integer | (all) | Filter by ImportStatus (0=Ready, 1=OK, 2=Error) |
batchId | integer | (all) | Filter by batch ID |
pageSize | integer | 50 | Rows per page |
page | integer | 1 | Page number |
Response: Three result sets:
rows[]— the staged data rows with all system and attribute columnssummary— counts by status:TotalRows,ReadyRows,OkRows,ErrorRows,ProcessingRowscolumns[]— attribute metadata:attributeId,name,displayName,dataType,sortOrder
Process a batch
POST /api/staging/:entityId/process
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
batchTag | string | No | Optional label for the batch |
batchId | integer | No | Process a specific batch (re-process) |
Response:
| Field | Type | Description |
|---|---|---|
batchId | integer | The batch ID |
status | string | Final status |
totalRows | integer | Total rows processed |
successRows | integer | Rows processed successfully |
errorRows | integer | Rows that failed |
skippedRows | integer | Rows skipped |
Clear batch rows
DELETE /api/staging/batches/:batchId/clear?status=processed
Deletes staging rows from a specific batch. The status parameter filters which rows to delete (all or processed).
Batch history endpoints
Get batches
GET /api/staging/:entityId/batches
Query parameters: pageSize (default 50), page (default 1).
Response: batches[] array with batch metadata, and totalCount.
Get batch errors
GET /api/staging/batches/:batchId/errors
Query parameters: pageSize (default 100), page (default 1).
Response: errors[] array with row-level error details, and summary with aggregate counts.
Clear batch history
DELETE /api/staging/:entityId/history
Removes all completed and failed batch records for the entity, including their staging rows and error details. Running and queued batches are preserved.
Scheduler endpoints
Get scheduler configuration
GET /api/staging/:entityId/scheduler
Returns the scheduler config with live runtime status fields: isRunning, pendingRows, oldestRowAge, nextScheduledRun, lastCompletedAt.
Save scheduler configuration
PUT /api/staging/:entityId/scheduler
Request body:
| Field | Type | Description |
|---|---|---|
processingMode | string | manual, scheduled, or triggered |
scheduleType | string | interval, daily, weekly, or monthly (required when mode is scheduled) |
intervalMinutes | integer | Interval in minutes (for interval type) |
runTimes | string | Comma-separated times, e.g. 06:00,18:00 |
runDays | string | Comma-separated days, e.g. Mon,Wed,Fri |
runDaysOfMonth | string | Comma-separated days, e.g. 1,15 |
triggerOnNewRows | boolean | Enable new-rows trigger |
triggerRowThreshold | integer | Row count threshold |
triggerIdleMinutes | integer | Idle timeout in minutes |
triggerDebounceSeconds | integer | Debounce window (default 60) |
isEnabled | boolean | Enable/disable the scheduler |
Validation (enforced server-side):
- Mode
scheduledrequiresscheduleTypeto be set - Mode
triggeredrequires at least one trigger to be configured - Mode
manualclears all schedule and trigger fields
Get scheduler log
GET /api/staging/:entityId/scheduler/log
Query parameters: pageSize (default 50), page (default 1).
Response: log[] array of scheduler events, and totalCount.
Test scheduler (dry run)
POST /api/staging/:entityId/scheduler/test
Evaluates current conditions without firing a batch. Returns what the dispatcher would do right now.
Response:
| Field | Type | Description |
|---|---|---|
wouldFire | boolean | Whether the scheduler would fire a batch |
reason | string | Explanation of why it would or would not fire |
pendingRows | integer | Current number of unprocessed rows |
oldestRowAge | integer | Age of the oldest unprocessed row in minutes |
nextScheduledRun | datetime | Next scheduled execution time |
Database tables
StagingConfigurations
Stores per-entity staging configuration (import action, merge mode, sentinel values). One row per entity with staging enabled.
StagingBatches
Stores batch processing history. Each row represents one processing run with status, row counts, and timing.
SchedulerConfigurations
Stores per-entity scheduler configuration (processing mode, schedule settings, trigger settings, runtime state). One row per entity.
SchedulerLog
Audit log of all scheduler events (fired, skipped, completed, error). Used for troubleshooting and monitoring.
Stored procedures
| Procedure | Description |
|---|---|
usp_Staging_CreateTable | Creates the staging table in the stg schema |
usp_Staging_DropTable | Drops the staging table and configuration |
usp_Staging_GetConfiguration | Returns config + field rules |
usp_Staging_SaveConfiguration | Saves config and field rules |
usp_Staging_GetStagedRows | Returns paginated staged rows with status filter |
usp_Staging_ProcessBatch | Core batch processing engine |
usp_Staging_GetBatches | Returns paginated batch history |
usp_Staging_GetErrors | Returns row-level errors for a batch |
usp_Staging_ClearBatch | Deletes rows from a specific batch |
usp_Staging_ClearBatchHistory | Clears completed batch records |
usp_Staging_RebuildTable | Syncs staging table columns with entity attributes |
usp_Scheduler_GetConfig | Returns scheduler config with live stats |
usp_Scheduler_SaveConfig | Saves scheduler configuration |
usp_Scheduler_GetLog | Returns paginated scheduler event log |
usp_Scheduler_TestRun | Dry-run evaluation of current conditions |
usp_Scheduler_CalculateNextRun | Calculates next scheduled execution time |
usp_Scheduler_Dispatch | The dispatcher — called every 60s by SQL Agent |