concert_workflows service has 5 resource kinds, each listed below with its endpoints, fields, and dependencies. Values resolve late, so you reference another resource with ${kind.ref_name}. For defaults, validation rules, and examples, run wxctl explain <kind>.
YAML envelope & reference syntax
YAML envelope & reference syntax
- Envelope: A config is one or more YAML documents separated by
---. Each has top-levelkindandref_name, then the fields below at the top level (not nested underspec). ref_name: Unique handle for this resource within the config. Used to reference it from other resources, then stripped before the API call (not a schema field).- References: Reference another resource by its ref_name:
${<kind>.<ref_name>}resolves to its id,${<kind>.<ref_name>.<field>}to a specific field. Values resolve late, at plan/apply time.
concert_worker_group
A Concert Workflows (Pliant) worker group, a named pool that flow runs and schedules execute on.
Runs on Software · ID field name
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/worker-group |
| Read | GET | /v1/worker-group/{name} |
| List | GET | /v1/worker-group |
| Update | PUT | /v1/worker-group/{name} |
| Delete | DELETE | /v1/worker-group/{name} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Worker-group name, the natural key (id_field: name, {name} path segment). Immutable. |
description | string | Optional | Free-text worker-group description. |
validate_certificates | boolean | Optional | Whether workers validate TLS certificates when connecting. |
meta | object | Optional | WorkerGroupMeta, free-form worker-group metadata (server-shaped; passed through). |
proxy_settings | object | Optional | WorkerGroupProxySettings, optional proxy config (server-shaped; passed through). |
secret | string | Optional | Worker-group join secret. The API rejects a null secret on create (server-side validation the OpenAPI DTO does not document, live-observed HTTP 400 “secret: must not be null”), so WorkerGroupHandler.pre_create generates a random one when the config omits it. Auto-redacted (the “secret” key is in wxctl-core redaction SENSITIVE_FIELDS). |
worker_statistics.
concert_workflow
A Concert Workflows (Pliant) flow, imported from a local zip.
Runs on Software · ID field name
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/flows/{user_name}/import |
| Read | GET | /v1/flows/{user_name}?folder={folder}&name={name} |
| List | GET | /v1/folders/{user_name}?folder={folder} |
| Update | POST | /v1/flows/{user_name}/import |
| Delete | DELETE | /v1/flows/{user_name}?folder={folder}&name={name}&deleteRelated=false |
| Field | Type | Required | Description |
|---|---|---|---|
user_name | string | Required | Pliant user namespace that owns the flow. Fills {user_name} on the import/get/delete endpoints; WorkflowHandler reads it to build the multipart import URL and the computed flow_uri. Immutable (rename is a spec Non-Goal). Precedent for a non-id Path segment: factsheets/model_tracking.yaml {model}. |
folder | string | Required | Folder path the flow lives under, in the API’s canonical slash-wrapped form, the value MUST be written “/segment/” (e.g. “/wxctl/”; a bare “wxctl” 400s against the folders and flows APIs). Path-located so it materializes verbatim into ?folder= on the folders-GET list and the flow get/delete endpoints. WorkflowHandler derives the import target (”/{user_name}{folder}”) and the computed flow_uri (“{user_name}{folder}{name}”) from it by straight concatenation, no separator insertion, since the slashes already live in this value. On read the server returns the folder+name as path (no user prefix), e.g. “/wxctl/wxctl-hello”. Immutable. |
name | string | Required | Flow name, the natural key within (user_name, folder). id_field: name; the folder-list item (ItemDto.name) is matched on it. Materializes into ?name= on get/delete. Immutable. |
source_path | string | Required | Local path to the flow zip to import (relative to the config file or absolute). is_path: true ⇒ build.rs adds it to PATH_FIELDS ⇒ resolved against the config dir by resolve_file_paths; LocalOnly so it is never sent to the API. WorkflowHandler uploads it multipart in pre_create/pre_update. |
flow_uri, hash, platform, language.
Consumers
concert_workflow_exposure→.flow_uri(required)concert_workflow_schedule→.flow_urn(optional)
concert_workflow_exposure
A Concert Workflows (Pliant) flow exposure, publishes a flow at an HTTP path so it can be triggered.
Runs on Software · ID field path
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/flow-exposures/{user_name} |
| Read | GET | /v1/flow-exposures/{user_name} |
| List | GET | /v1/flow-exposures/{user_name} |
| Update | PUT | /v1/flow-exposures/{user_name}?exposurePath={path} |
| Delete | DELETE | /v1/flow-exposures/{user_name}?exposurePath={path} |
| Field | Type | Required | Description |
|---|---|---|---|
user_name | string | Required | Pliant user namespace that owns the exposure. Fills {user_name} on every endpoint. Immutable. Precedent for a non-id Path segment: factsheets/model_tracking.yaml {model}. |
path | string | Required | Exposure HTTP path, the natural key within user_name (id_field: path). Sent in the create/update body as path AND, on update/delete, substituted into ?exposurePath={path} via id_field placeholder filling (the {path} placeholder MUST equal id_field, see docs/troubleshoot/endpoint-placeholder-must-match-id-field-fix.md). Immutable (recreate). |
flow_uri | string | Required | URI of the flow to expose. References the computed flow_uri on concert_workflow (top- level field ⇒ real graph edge → the flow applies first). |
authorization_policy | string | Required | Who may trigger the exposed flow. Nested into meta.authentication.authorizationPolicy on the body (materializer dotted api_field, arbitrary depth, see wxctl-core/src/client/materializer.rs insert_nested). Admins keeps the trigger behind Basic auth. Hard-enforced via top-level allowed_values (validation.enum is not a real DSL key, ValidationRules has no enum field and lacks deny_unknown_fields, so it would silently no-op; allowed_values is the mechanism validate_schema actually checks). |
sync | boolean | Required | Whether the exposure runs the flow synchronously (meta.sync). |
flow_uri→concert_workflow(required)
concert_workflow_role
A Concert Workflows (Pliant) flow role, a named grant bundling users, worker groups, and per-surface policies (flow, application, auth-storage, schedule, automation-panel).
Runs on Software · ID field name
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/flow-roles/ |
| Read | GET | /v1/flow-roles/{name}?includeUserNames=true&includePolicies=true&includeWorkerGroupNames=true |
| List | GET | /v1/flow-roles/ |
| Update | PUT | /v1/flow-roles/{name} |
| Delete | DELETE | /v1/flow-roles/{name} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Flow-role name, the natural key (id_field: name, {name} path segment). Immutable. |
description | string | Optional | Free-text flow-role description. |
user_names | array<string> | Optional | Pliant usernames granted this role (plain strings; not a wxctl-managed kind). |
worker_group_names | array<string> | Optional | Worker groups this role can use. Plain string array with NO reference edge, a nested/ scalar-array reference makes no graph edge (spec Data Flow), so the cell config orders concert_worker_group before the role explicitly. |
application_policies | array<object> | Optional | ApplicationPolicyDto[], application-scope grants (server-shaped; passed through). |
auth_storage_policies | array<object> | Optional | AuthStoragePolicyDto[], auth-storage-scope grants. |
automation_panel_policies | array<object> | Optional | AutomationPanelPolicyDto[], automation-console panel grants. |
flow_policies | array<object> | Optional | FlowPolicyDto[], flow-scope grants. |
flow_schedule_policies | array<object> | Optional | FlowSchedulePolicyDto[], schedule-scope grants. |
concert_workflow_schedule
A schedule that runs a Concert Workflows (Pliant) flow on a cron cadence.
Runs on Software · ID field name
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/flowschedules/{user_name} |
| Read | GET | /v1/flowschedules/{user_name}/{name} |
| List | GET | /v1/flowschedules/{user_name} |
| Update | PUT | /v1/flowschedules/{user_name}/{name} |
| Delete | DELETE | /v1/flowschedules/{user_name}/{name} |
| Field | Type | Required | Description |
|---|---|---|---|
user_name | string | Required | Pliant user namespace that owns the schedule. Fills the {user_name} path segment on every endpoint (not sent in the body). Immutable, a change recreates (rename is a spec Non-Goal). Precedent for a non-id Path segment: factsheets/model_tracking.yaml {model}. |
name | string | Required | Schedule name, the natural key. Sent in the create body and used as the {name} path segment (id_field: name) for read/update/delete. Immutable (rename recreates). |
second | string | Required | Cron seconds field. |
minute | string | Required | Cron minutes field. |
hour | string | Required | Cron hours field. |
day_of_month | string | Required | Cron day-of-month field. |
month | string | Required | Cron month field. |
day_of_week | string | Required | Cron day-of-week field. |
year | string | Required | Cron year field. |
timezone | string | Optional | IANA timezone the cron expression is evaluated in. |
enabled | boolean | Optional | Whether the schedule is active. |
auto_delete | boolean | Optional | Delete the schedule after it fires (one-shot). |
description | string | Optional | Free-text schedule description. |
flow_urn | string | Optional | URN of the flow this schedule runs, the computed flow_uri on concert_workflow (“{user_name}/{folder}/{name}”). Top-level reference field ⇒ real graph edge (the schedule applies after the flow). Phase 3 confirms flowUrn accepts the flow_uri form live. |
flow_revision | integer | Optional | Pinned flow revision to run (omit for latest). |
worker_group | string | Optional | Worker group the scheduled run executes on. Plain string (no reference edge), the spec Data Flow orders worker groups before schedules via cell config, not a DAG edge. |
params | string | Optional | Serialized run parameters passed to the flow. |
repeats | integer | Optional | Repeat count. |
special_condition | string | Optional | Optional special scheduling condition. |
start_time | integer | Optional | Epoch-millis window start. |
end_time | integer | Optional | Epoch-millis window end. |
flow_urn→concert_workflow(optional)