---
title: "Preview a configuration workflow before saving it"
method: POST
path: "/api/south/{southId}/test/workflow-preview"
tags: ["South Connectors"]
---

# Preview a configuration workflow before saving it

`POST /api/south/{southId}/test/workflow-preview`

Dry-runs a configuration workflow as currently edited (possibly never saved) against the south
connector settings as currently edited: identical discovery and classification as a real run, but
nothing is written. Used from the south connector edit page, where workflows can be previewed but not run.

## Path parameters

- `southId` string, required

## Query parameters

- `southType` 'opcua' | 'mqtt' | 'modbus' | 'oianalytics' | 'ads' | 'bacnet' | 'folder-scanner' | 'ftp' | 'influxdb' | 'mongodb' | 'mssql' | 'mysql' | 'odbc' | 'oledb' | 'opc' | 'oracle' | 'osisoft-pi' | 'postgresql' | 'rest' | 's7' | 'sftp' | 'sqlite', required — Type representing the possible types for a South connector.

## Request body

- SouthWorkflowPreviewRequest
  - `southSettings` union, required
    - SouthADSSettings
      - `netId` string, required
      - `port` number, double, required
      - `routerAddress` string, nullable, required
      - `routerTcpPort` number, double, nullable, required
      - `clientAmsNetId` string, nullable, required
      - `clientAdsPort` number, double, nullable, required
      - `retryInterval` number, double, required
      - `plcName` string, nullable, required
      - `enumAsText` 'text' | 'integer', required
      - `boolAsText` 'text' | 'integer', required
      - `structureFiltering` SouthADSSettingsStructureFiltering[], nullable, required
        - `name` string, required
        - `fields` string, required
    - SouthBACnetSettings
      - `localInterface` string, nullable, required
      - `port` number, double, required
      - `apduTimeout` number, double, required
      - `broadcastAddress` string, required
      - `retryInterval` number, double, required
      - `maxParallelRun` number, double, required
      - `discoveryTargetAddress` string, nullable, required
      - `covDefaultLifetime` number, double, required
      - `covRenewalMargin` number, double, required
      - `maxObjectsPerRequest` number, double, required
      - `maxNumberOfMessages` number, double, required
      - `flushMessageTimeout` number, double, required
      - `bbmd` SouthBACnetSettingsBbmd, required
        - `enabled` boolean, required
        - `address` string
        - `foreignDeviceTtl` number, double
    - SouthFolderScannerSettings
      - `inputFolder` string, required
      - `compression` boolean, required
      - `username` string, nullable
      - `password` string, nullable
      - `domain` string, nullable
    - SouthFTPSettings
      - `host` string, required
      - `port` number, double, required
      - `authentication` 'none' | 'password', required
      - `username` string, nullable
      - `password` string, nullable
      - `compression` boolean, required
      - `retryInterval` number, double, required
    - SouthInfluxDBSettings
      - `version` '1' | '2' | '3', required
      - `host` string
      - `port` number, double
      - `protocol` 'http' | 'https'
      - `database` string
      - `username` string, nullable
      - `password` string, nullable
      - `url` string
      - `token` string, nullable
      - `organisation` string
      - `bucket` string
    - SouthModbusSettings
      - `host` string, required
      - `port` number, double, required
      - `connectTimeout` number, double, required
      - `networkTimeout` number, double, required
      - `retryInterval` number, double, required
      - `slaveId` number, double, required
      - `addressOffset` 'modbus' | 'jbus', required
      - `endianness` 'big-endian' | 'little-endian', required
      - `swapBytesInWords` boolean, required
      - `swapWordsInDWords` boolean, required
      - `batchQuery` boolean, required
      - `groupingGap` number, double
    - SouthMongoDBSettings
      - `connectionString` string, required
      - `connectionTimeout` number, double, required
      - `username` string, nullable, required
      - `password` string, nullable, required
    - SouthMQTTSettings
      - `url` string, required
      - `qos` '0' | '1' | '2', required
      - `persistent` boolean
      - `authentication` SouthMQTTSettingsAuthentication, required
        - `type` 'none' | 'basic' | 'cert', required
        - `username` string
        - `password` string, nullable
        - `certFilePath` string
        - `keyFilePath` string
        - `caFilePath` string
      - `rejectUnauthorized` boolean, required
      - `reconnectPeriod` number, double, required
      - `connectTimeout` number, double, required
      - `maxNumberOfMessages` number, double, required
      - `flushMessageTimeout` number, double, required
    - SouthMSSQLSettings
      - `host` string, required
      - `port` number, double, required
      - `connectionTimeout` number, double, required
      - `database` string, required
      - `encryption` boolean, required
      - `trustServerCertificate` boolean, required
      - `username` string, nullable, required
      - `password` string, nullable, required
      - `domain` string, nullable, required
      - `requestTimeout` number, double, required
    - SouthMySQLSettings
      - `host` string, required
      - `port` number, double, required
      - `connectionTimeout` number, double, required
      - `database` string, required
      - `username` string, nullable, required
      - `password` string, nullable, required
    - SouthODBCSettings
      - `remoteAgent` boolean, required
      - `agentUrl` string
      - `connectionTimeout` number, double, required
      - `retryInterval` number, double, required
      - `requestTimeout` number, double
      - `connectionString` string, required
      - `password` string, nullable, required
    - SouthOIAnalyticsSettings
      - `useOiaModule` boolean, required
      - `timeout` number, double, required
      - `specificSettings` SouthOIAnalyticsSettingsSpecificSettings
        - `host` string, required
        - `acceptUnauthorized` boolean, required
        - `authentication` 'basic' | 'aad-client-secret' | 'aad-certificate', required
        - `accessKey` string
        - `secretKey` string, nullable
        - `tenantId` string
        - `clientId` string
        - `clientSecret` string, nullable
        - `certificateId` string
        - `scope` string
        - `useProxy` boolean, required
        - `proxyUrl` string
        - `proxyUsername` string
        - `proxyPassword` string, nullable
    - SouthOLEDBSettings
      - `agentUrl` string, required
      - `connectionTimeout` number, double, required
      - `retryInterval` number, double, required
      - `requestTimeout` number, double, required
      - `connectionString` string, required
      - `password` string, nullable, required
    - SouthOPCSettings
      - `agentUrl` string, required
      - `retryInterval` number, double, required
      - `host` string, required
      - `serverName` string, required
      - `mode` 'hda' | 'da', required
    - SouthOPCUASettings
      - `url` string, required
      - `keepSessionAlive` boolean, required
      - `readTimeout` number, double, required
      - `retryInterval` number, double, required
      - `maxNumberOfMessages` number, double, required
      - `flushMessageTimeout` number, double, required
      - `securityMode` 'none' | 'sign' | 'sign-and-encrypt', required
      - `securityPolicy` 'none' | 'basic128' | 'basic192' | 'basic256' | 'basic128-rsa15' | 'basic192-rsa15' | 'basic256-rsa15' | 'basic256-sha256' | 'aes128-sha256-rsa-oaep' | 'pub-sub-aes-128-ctr' | 'pub-sub-aes-256-ctr'
      - `maxParallelRun` number, double, required
      - `authentication` SouthOPCUASettingsAuthentication, required
        - `type` 'none' | 'basic' | 'cert', required
        - `username` string
        - `password` string, nullable
        - `certFilePath` string
        - `keyFilePath` string
    - SouthOracleSettings
      - `thickMode` boolean, required
      - `oracleClient` string
      - `host` string, required
      - `port` number, double, required
      - `connectionTimeout` number, double, required
      - `database` string, required
      - `username` string, nullable, required
      - `password` string, nullable, required
    - SouthPISettings
      - `agentUrl` string, required
      - `retryInterval` number, double, required
    - SouthPostgreSQLSettings
      - `host` string, required
      - `port` number, double, required
      - `sslMode` boolean, required
      - `database` string, required
      - `connectionTimeout` number, double, required
      - `requestTimeout` number, double, required
      - `username` string, nullable, required
      - `password` string, nullable, required
    - SouthRestSettings
      - `host` string, required
      - `acceptUnauthorized` boolean, required
      - `timeout` number, double, required
      - `authentication` SouthRestSettingsAuthentication, required
        - `type` 'none' | 'basic' | 'bearer' | 'api-key', required
        - `username` string
        - `password` string, nullable
        - `token` string, nullable
        - `apiKey` string
        - `apiValue` string, nullable
        - `addTo` 'header' | 'query-params'
      - `proxy` SouthRestSettingsProxy, required
        - `useProxy` boolean, required
        - `proxyUrl` string
        - `proxyUsername` string, nullable
        - `proxyPassword` string, nullable
      - `test` SouthRestSettingsTest, required
        - `method` 'GET' | 'POST' | 'PUT', required
        - `endpoint` string, required
        - `successCode` number, double, required
        - `body` string, nullable
    - SouthS7Settings
      - `host` string, required
      - `port` number, double, required
      - `connectionType` 'PG' | 'OP' | 'S7Basic', required
      - `rack` number, double, required
      - `slot` number, double, required
      - `connectTimeout` number, double, required
      - `requestTimeout` number, double, required
      - `retryInterval` number, double, required
    - SouthSFTPSettings
      - `host` string, required
      - `port` number, double, required
      - `authentication` 'password' | 'private-key', required
      - `username` string, required
      - `password` string, nullable
      - `privateKey` string
      - `passphrase` string, nullable
      - `compression` boolean, required
      - `retryInterval` number, double, required
    - SouthSQLiteSettings
      - `databasePath` string, required
  - `workflowId` string, nullable, required — The saved workflow being edited, to classify entries against its previous run - null for a workflow not saved yet
  - `workflow` ConfigurationWorkflowCommandDTO, required
    - `id` string, nullable, required — The ID of the workflow - null (or a `temp_`-prefixed id minted client-side) when creating a new one. Only meaningful when the workflow is sent as part of a south connector command; ignored by the standalone workflow endpoints, which take the id from the path.
    - `name` string, required
    - `discoveryScope` RecordStringUnknown, required — Construct a type with a set of properties K of type T
    - `identityKeyFields` string[], required — Local mode: at least one field is required. Remote mode (`pushToOIAnalytics` true): ignored, and stored empty — send `[]`.
    - `eligibilityFilter` RecordFilterCondition[], required
      - `field` string, required — A key of the discovered record to test.
      - `operator` 'equals' | 'notEquals' | 'contains' | 'matches' | 'exists' | 'greaterThan' | 'lessThan', required — How one condition of a workflow's eligibility filter compares a discovered record's field.
      - `value` string — The value to compare against — not used for `exists`.
    - `itemFieldMapping` RecordStringString, required — Construct a type with a set of properties K of type T
    - `pushToOIAnalytics` boolean, required
    - `scanModeId` string, nullable, required — The ID of the scan mode to use for this workflow, or null for manual-only.
    - `enabled` boolean, required

## Response `200`

What a run would find and how it would classify it

- WorkflowPreviewResultDTO — A dry run of a Configuration Workflow: identical discovery as a real run, but nothing is written - no items, no point metadata, no `workflow_runs` record, no OIAnalytics push. Discovery itself is a real round-trip to the data source, so a preview costs what a run costs minus the writes.
  - `discoveredCount` number, double, required
  - `eligibleCount` number, double, required
  - `entries` WorkflowPreviewEntryDTO[], required — Local (item-creating) workflow only - the per-entry new/changed/unchanged/missing classification against the previous run. Empty for a remote workflow.
    - `key` string, required — The identity key computed from the workflow's `identityKeyFields`.
    - `status` 'new' | 'changed' | 'unchanged' | 'reactivated' | 'missing', required — How a preview classifies one discovered/tracked entry against the workflow's previous run - the same classification a real run's Decide step uses, before Act would touch anything.
    - `record` OIBusRecord, required — Construct a type with a set of properties K of type T
    - `previousMetadata` RecordStringUnknown, required — Construct a type with a set of properties K of type T
  - `records` OIBusRecord[], required — Remote (push-to-OIAnalytics) workflow only - the raw eligible records that would be sent, exactly as discovered, with no mapping or diffing applied. Empty for a local workflow.

## Changes

- **2026-10-05** `fa9a57387b34` — 1 info
  - endpoint added
- **2026-10-01** `c49410ca1eee` — 1 breaking
  - api path removed without deprecation
- **2026-09-29** `011be71f42e5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/optimistiksas/apis/oibus-api/changes/api/south/:southId/test/workflow-preview/post.md)

---

[API](https://skmtc.dev/optimistiksas/apis/oibus-api.md) · [All operations](https://skmtc.dev/optimistiksas/apis/oibus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/optimistiksas/apis/oibus-api/revisions/fa9a57387b34?raw)