---
title: "Update configuration workflow"
method: PUT
path: "/api/south/{southId}/workflows/{workflowId}"
tags: ["Configuration Workflows"]
---

# Update configuration workflow

`PUT /api/south/{southId}/workflows/{workflowId}`

Updates an existing configuration workflow

## Path parameters

- `southId` string, required
- `workflowId` string, required

## Request body

- ConfigurationWorkflowCommandDTO
  - `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`

The updated configuration workflow

- ConfigurationWorkflowDTO — A Configuration Workflow: discovers a data source, decides which of what it found actually warrants a configuration change, and either creates/updates south items from it or forwards the raw eligible records to OIAnalytics — run once by hand or recurringly on a scan mode. Exactly one of `itemFieldMapping`/`pushToOIAnalytics` applies — a workflow is either local (`itemFieldMapping` set, `pushToOIAnalytics` false) or remote (`itemFieldMapping` null, `pushToOIAnalytics` true), enforced at the service layer. Remote additionally requires OIBus to be registered with OIAnalytics.
  - `id` string, required — The unique identifier of the entity.
  - `createdBy` UserInfo, required — Represents the user who performed an action, with a computed display name.
    - `id` string, required — The unique identifier of the user.
    - `friendlyName` string, required — A human-readable display name for the user. "OIAnalytics" for the oianalytics system user, "Admin" for the admin login, or "Firstname Lastname (login)" for regular users.
  - `updatedBy` UserInfo, required — Represents the user who performed an action, with a computed display name.
    - `id` string, required — The unique identifier of the user.
    - `friendlyName` string, required — A human-readable display name for the user. "OIAnalytics" for the oianalytics system user, "Admin" for the admin login, or "Firstname Lastname (login)" for regular users.
  - `createdAt` string, required — Represents an instant in time as an ISO 8601 string.
  - `updatedAt` string, required — Represents an instant in time as an ISO 8601 string.
  - `name` string, required — Unique per south connector.
  - `southId` string, required — The south connector this workflow discovers from.
  - `discoveryScope` RecordStringUnknown, required — Construct a type with a set of properties K of type T
  - `identityKeyFields` string[], required — Local mode only: discovered-record field(s) — possibly composite — that uniquely identify a record across re-runs. Always empty for a remote workflow (`pushToOIAnalytics` true), which never diffs against a previous run.
  - `eligibilityFilter` RecordFilterCondition[], required — Conditions a discovered record must all satisfy to be eligible for action — empty means every record is eligible.
    - `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 — Remote mode: forward every run's raw eligible records to OIAnalytics as-is (no mapping, no local item, no per-record diffing) instead of creating/updating items locally. Requires OIBus to be registered with OIAnalytics.
  - `scanMode` ScanModeDTO, required — Data Transfer Object for a scan mode. Represents a configured scan mode with its metadata and schedule.
    - `id` string, required — The unique identifier of the entity.
    - `createdBy` UserInfo, required — Represents the user who performed an action, with a computed display name.
      - `id` string, required — The unique identifier of the user.
      - `friendlyName` string, required — A human-readable display name for the user. "OIAnalytics" for the oianalytics system user, "Admin" for the admin login, or "Firstname Lastname (login)" for regular users.
    - `updatedBy` UserInfo, required — Represents the user who performed an action, with a computed display name.
      - `id` string, required — The unique identifier of the user.
      - `friendlyName` string, required — A human-readable display name for the user. "OIAnalytics" for the oianalytics system user, "Admin" for the admin login, or "Firstname Lastname (login)" for regular users.
    - `createdAt` string, required — Represents an instant in time as an ISO 8601 string.
    - `updatedAt` string, required — Represents an instant in time as an ISO 8601 string.
    - `name` string, required — The name of the scan mode.
    - `description` string, required — A description of the scan mode's purpose or behavior.
    - `type` 'cron' | 'interval', required — How a scan mode decides when to tick. - `cron`: driven by a cron expression (the historical behaviour). - `interval`: driven by a fixed period between ticks.
    - `cron` string, required — A cron expression defining the scan schedule. Empty when `type` is `"interval"`.
    - `interval` ScanModeInterval, required — Fixed period between two ticks of an `interval` scan mode.
      - `value` number, double, required — How many `unit`s between two ticks.
      - `unit` 'ms' | 's' | 'min' | 'hour', required
    - `activationWindow` ActivationWindow, required — Optional gate applied on top of the schedule. A tick only fires when it satisfies every configured criterion; the two criteria below are combined with AND. A tick falling outside the window is skipped silently — it is never queued or deferred.
      - `dateRange` ActivationWindowDateRange — Absolute bounds of an activation window. Each side is independently optional: an absent bound means the window is open-ended on that side.
        - `start` string — Represents an instant in time as an ISO 8601 string.
        - `end` string — Represents an instant in time as an ISO 8601 string.
      - `recurring` ActivationWindowRecurring — A civil-time recurrence rule. Unlike the date range, this is not a pair of instants: "Thursday 12:00" shifts by an hour across DST transitions, so the rule carries the IANA timezone it is expressed in and is re-derived at every evaluation.
        - `timezone` string, required — Represents a timezone as an IANA timezone string.
        - `daysOfWeek` number[], nullable — Days on which the window is active, 0 = Sunday … 6 = Saturday. Absent or empty means every day.
        - `timeOfDay` ActivationWindowTimeOfDay — Local time-of-day bounds. `start` is inclusive, `end` is exclusive. When `end` is earlier than `start` the window is overnight and spans into the following day.
          - `start` string, required — Represents a local time as an ISO time string (HH:MM:SS).
          - `end` string, required — Represents a local time as an ISO time string (HH:MM:SS).
    - `activationWindowExpired` boolean, required — Whether the activation window can never trigger again (for instance its end date is already past). Computed server-side; drives a non-blocking warning in the UI.
  - `enabled` boolean, required

## Changes

- **2026-09-23** `92023a2f20ae` — 1 info
  - endpoint added
- **2026-09-21** `fbefadfe3be3` — 1 breaking
  - api path removed without deprecation
- **2026-09-21** `91dba375a461` — 1 info
  - endpoint added
- **2026-09-21** `52d824185a20` — 1 breaking
  - api path removed without deprecation
- **2026-09-08** `6cc2578622b5` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/optimistiksas/apis/oibus-api/changes/api/south/:southId/workflows/:workflowId/put.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/a34e6afd34e1?raw)