---
title: "Test south connector item"
method: POST
path: "/api/south/{southId}/items/test"
tags: ["South Connectors"]
---

# Test south connector item

`POST /api/south/{southId}/items/test`

Test a south connector item

## Path parameters

- `southId` string, required

## Query parameters

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

## Request body

- SouthItemTestRequest
  - `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
    - 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
    - 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
    - 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
  - `itemSettings` union, required
    - SouthADSItemSettings
      - `address` string, required
    - SouthFolderScannerItemSettings
      - `regex` string, required
      - `minAge` number, double, required
      - `preserveFiles` boolean, required
      - `ignoreModifiedDate` boolean
      - `maxFiles` number, double, required
      - `maxSize` number, double, required
      - `recursive` boolean, required
    - SouthFTPItemSettings
      - `remoteFolder` string, required
      - `regex` string, required
      - `minAge` number, double, required
      - `preserveFiles` boolean, required
      - `ignoreModifiedDate` boolean
      - `maxFiles` number, double, required
      - `maxSize` number, double, required
      - `recursive` boolean, required
    - SouthInfluxDBItemSettings
      - `query` string, required
      - `requestTimeout` number, double, required
    - SouthModbusItemSettings
      - `address` string, required
      - `modbusType` 'coil' | 'discrete-input' | 'input-register' | 'holding-register', required
      - `data` SouthModbusItemSettingsData
        - `dataType` 'uint16' | 'int16' | 'uint32' | 'int32' | 'big-uint64' | 'big-int64' | 'float' | 'double' | 'bit', required
        - `bitIndex` number, double
        - `multiplierCoefficient` number, double, required
    - SouthMQTTItemSettings
      - `topic` string, required
    - SouthMSSQLItemSettings
      - `query` string, required
      - `dateTimeFields` SouthMSSQLItemSettingsDateTimeFields[], nullable, required
        - `fieldName` string, required
        - `useAsReference` boolean, required
        - `type` 'string' | 'date' | 'date-time' | 'date-time-2' | 'date-time-offset' | 'small-date-time' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
        - `timezone` string — Represents a timezone as an IANA timezone string.
        - `format` string
        - `locale` string
      - `serialization` SouthMSSQLItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
    - SouthMySQLItemSettings
      - `query` string, required
      - `requestTimeout` number, double, required
      - `dateTimeFields` SouthMySQLItemSettingsDateTimeFields[], nullable, required
        - `fieldName` string, required
        - `useAsReference` boolean, required
        - `type` 'string' | 'date-time' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
        - `timezone` string — Represents a timezone as an IANA timezone string.
        - `format` string
        - `locale` string
      - `serialization` SouthMySQLItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
    - SouthODBCItemSettings
      - `query` string, required
      - `dateTimeFields` SouthODBCItemSettingsDateTimeFields[], nullable, required
        - `fieldName` string, required
        - `useAsReference` boolean, required
        - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
        - `timezone` string — Represents a timezone as an IANA timezone string.
        - `format` string
        - `locale` string
      - `serialization` SouthODBCItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
    - SouthOIAnalyticsItemSettings
      - `endpoint` string, required
      - `queryParams` SouthOIAnalyticsItemSettingsQueryParams[], required
        - `key` string, required
        - `value` string, required
      - `serialization` SouthOIAnalyticsItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
    - SouthOLEDBItemSettings
      - `query` string, required
      - `dateTimeFields` SouthOLEDBItemSettingsDateTimeFields[], nullable, required
        - `fieldName` string, required
        - `useAsReference` boolean, required
        - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
        - `timezone` string — Represents a timezone as an IANA timezone string.
        - `format` string
        - `locale` string
      - `serialization` SouthOLEDBItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
    - SouthOPCItemSettings
      - `nodeId` string, required
      - `aggregate` 'raw' | 'interpolative' | 'total' | 'average' | 'time-average' | 'count' | 'stdev' | 'minimum-actual-time' | 'minimum' | 'maximum-actual-time' | 'maximum' | 'start' | 'end' | 'delta' | 'reg-slope' | 'reg-const' | 'reg-dev' | 'variance' | 'range' | 'duration-good' | 'duration-bad' | 'percent-good' | 'percent-bad' | 'worst-quality' | 'annotations', required
      - `resampling` 'none' | '1s' | '10s' | '30s' | '1min' | '1h' | '1d'
    - SouthOPCUAItemSettings
      - `nodeId` string, required
      - `mode` 'da' | 'ha', required
      - `haMode` SouthOPCUAItemSettingsHaMode
        - `aggregate` 'raw' | 'average' | 'count' | 'minimum' | 'maximum', required
        - `resampling` 'none' | '1s' | '10s' | '30s' | '1min' | '1h' | '1d'
      - `timestampOrigin` 'oibus' | 'point' | 'server'
    - SouthOracleItemSettings
      - `query` string, required
      - `requestTimeout` number, double, required
      - `dateTimeFields` SouthOracleItemSettingsDateTimeFields[], nullable, required
        - `fieldName` string, required
        - `useAsReference` boolean, required
        - `type` 'string' | 'date-time' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
        - `timezone` string — Represents a timezone as an IANA timezone string.
        - `format` string
        - `locale` string
      - `serialization` SouthOracleItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
    - SouthPIItemSettings
      - `type` 'point-id' | 'point-query', required
      - `piPoint` string
      - `piQuery` string
    - SouthPostgreSQLItemSettings
      - `query` string, required
      - `dateTimeFields` SouthPostgreSQLItemSettingsDateTimeFields[], nullable, required
        - `fieldName` string, required
        - `useAsReference` boolean, required
        - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms' | 'timestamp' | 'timestamptz', required
        - `timezone` string — Represents a timezone as an IANA timezone string.
        - `format` string
        - `locale` string
      - `serialization` SouthPostgreSQLItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
    - SouthRestItemSettings
      - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required
      - `endpoint` string, required
      - `returnType` 'file' | 'body', required
      - `queryParams` SouthRestItemSettingsQueryParams[], required
        - `key` string, required
        - `value` string, required
        - `dateTimeInput` SouthRestItemSettingsQueryParamsDateTimeInput
          - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
          - `timezone` string — Represents a timezone as an IANA timezone string.
          - `format` string, nullable
      - `headers` SouthRestItemSettingsHeaders[], required
        - `key` string, required
        - `value` string, required
        - `dateTimeInput` SouthRestItemSettingsHeadersDateTimeInput
          - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
          - `timezone` string — Represents a timezone as an IANA timezone string.
          - `format` string, nullable
      - `body` SouthRestItemSettingsBody
        - `content` string, nullable, required
        - `dateTimeInput` SouthRestItemSettingsBodyDateTimeInput
          - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
          - `timezone` string — Represents a timezone as an IANA timezone string.
          - `format` string, nullable
      - `trackingInstant` SouthRestItemSettingsTrackingInstant
        - `trackInstant` boolean, required
        - `jsonPath` string
        - `dateTimeInput` SouthRestItemSettingsTrackingInstantDateTimeInput
          - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
          - `timezone` string — Represents a timezone as an IANA timezone string.
          - `format` string
          - `locale` string
    - SouthSFTPItemSettings
      - `remoteFolder` string, required
      - `regex` string, required
      - `minAge` number, double, required
      - `preserveFiles` boolean, required
      - `ignoreModifiedDate` boolean
      - `maxFiles` number, double, required
      - `maxSize` number, double, required
      - `recursive` boolean, required
    - SouthSQLiteItemSettings
      - `query` string, required
      - `dateTimeFields` SouthSQLiteItemSettingsDateTimeFields[], nullable, required
        - `fieldName` string, required
        - `useAsReference` boolean, required
        - `type` 'string' | 'iso-string' | 'unix-epoch' | 'unix-epoch-ms', required
        - `timezone` string — Represents a timezone as an IANA timezone string.
        - `format` string
        - `locale` string
      - `serialization` SouthSQLiteItemSettingsSerialization, required
        - `type` 'csv', required
        - `filename` string, required
        - `delimiter` 'DOT' | 'SEMI_COLON' | 'COLON' | 'COMMA' | 'NON_BREAKING_SPACE' | 'SLASH' | 'TAB' | 'PIPE', required
        - `compression` boolean, required
        - `outputTimestampFormat` string, required
        - `outputTimezone` string, required — Represents a timezone as an IANA timezone string.
  - `testingSettings` SouthConnectorItemTestingSettings, required — Settings for testing a South connector item. Used when manually testing data collection for an item.
    - `history` object — Historical data range for testing. Undefined when testing real-time data collection (which for folder-scanner means last file).
      - `endTime` string, required — End time for historical data test (ISO 8601 format). Not applicable for folder-scanner as it doesn't support history mode.
      - `startTime` string, required — Start time for historical data test (ISO 8601 format). Not applicable for folder-scanner as it doesn't support history mode.
    - `transformer` object — Optional transformer to run the raw test result through before returning it. When omitted, the raw collected value is returned (default behavior). `transformerId` references a transformer in the global catalog; `options` are the per-binding options to apply.
      - `options` RecordStringUnknown, required — Construct a type with a set of properties K of type T
      - `transformerId` string, required

## Response `200`

Raw and (optionally) transformed test results

- SouthConnectorItemTestResult — Result of testing a South/History item. `raw` is always the value collected by the connector; `transformed` is the output of running `raw` through the selected transformer with its options, or null when no transformer was requested. This lets the UI show the Raw → transformer → Output pipeline. `connectionDuration`/`queryDuration` are passed through from the connector's `SouthConnectorItemQueryResult`.
  - `raw` union, required — Type representing OIBus content.
    - OIBusTimeValueContent — Time-value content.
      - `type` 'time-values', required — The type of content.
      - `content` OIBusTimeValue[], required — The array of time-value pairs.
        - `pointId` string, required — The ID of the point.
        - `timestamp` string, required — Represents an instant in time as an ISO 8601 string.
        - `data` object, required — The data associated with the point.
          - `value` union, required — The value of the point.
            - string
            - number, double
    - OIBusFileContent — Raw content.
      - `type` 'any', required — The type of content.
      - `filePath` string, required — The path to the file containing the content.
      - `filename` string — The logical filename to store in cache metadata (used as the output filename by north connectors). When omitted, north connectors fall back to path.basename(filePath). South connectors that preserve directory structure (e.g. folder-scanner with recursive=true) set this to the path relative to the source folder, e.g. "subdir/file.json".
      - `content` string — The content itself, if available.
    - OIBusAnyContent
      - `type` 'any-content', required — The type of content.
      - `content` string, required — The content
    - OIBusSetpointContent — Setpoint content.
      - `type` 'setpoint', required — The type of content.
      - `content` OIBusSetpoint[], required — The array of setpoints.
        - `reference` string, required — The reference of the setpoint.
        - `value` union, required — The value of the setpoint.
          - string
          - number, double
          - boolean
  - `transformed` union, required — Type representing OIBus content.
    - OIBusTimeValueContent — Time-value content.
      - `type` 'time-values', required — The type of content.
      - `content` OIBusTimeValue[], required — The array of time-value pairs.
        - `pointId` string, required — The ID of the point.
        - `timestamp` string, required — Represents an instant in time as an ISO 8601 string.
        - `data` object, required — The data associated with the point.
          - `value` union, required — The value of the point.
            - string
            - number, double
    - OIBusFileContent — Raw content.
      - `type` 'any', required — The type of content.
      - `filePath` string, required — The path to the file containing the content.
      - `filename` string — The logical filename to store in cache metadata (used as the output filename by north connectors). When omitted, north connectors fall back to path.basename(filePath). South connectors that preserve directory structure (e.g. folder-scanner with recursive=true) set this to the path relative to the source folder, e.g. "subdir/file.json".
      - `content` string — The content itself, if available.
    - OIBusAnyContent
      - `type` 'any-content', required — The type of content.
      - `content` string, required — The content
    - OIBusSetpointContent — Setpoint content.
      - `type` 'setpoint', required — The type of content.
      - `content` OIBusSetpoint[], required — The array of setpoints.
        - `reference` string, required — The reference of the setpoint.
        - `value` union, required — The value of the setpoint.
          - string
          - number, double
          - boolean
  - `connectionDuration` number, double, required
  - `queryDuration` number, double, required

---

[API](https://skmtc.net/optimistiksas/apis/oibus-api.md) · [All operations](https://skmtc.net/optimistiksas/apis/oibus-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/optimistiksas/oibus-api/revisions/fe8fd32c9fdc/schema)