Workflow Configuration and Definition Reference

This page describes the configurable fields shared by workflow types. Each type exposes only a subset of context paths, events, triggers, preconditions, and actions. See Deploy Approval and System Lifecycle.

Configuration fields

Field	Meaning
Name	Human-readable configuration name.
Description	Optional administrative context.
Enabled	Whether the configuration can be selected for new starts.
Priority	Positive integer; lower values are selected first.
Activation scope	Expression that decides whether the configuration applies to a new subject.
Definition versions	Immutable published snapshots of stages and transitions.

Activation scope

Activation scope is evaluated only when selecting a configuration for a new subject. It is not part of definitionYaml. An empty scope matches every supported subject and is represented as:

exists:
  path: subject.ref

Operator	Configuration
all	Non-empty list of expressions; every expression must match.
any	Non-empty list of expressions; at least one must match.
eq	path and one value.
in	path and a non-empty values list.
exists	A path that must be present.

Available paths depend on the workflow type's subject context:

all:
  - eq:
      path: system.type
      value: data-product
  - in:
      path: release.environment
      values: [staging, production]

Workflow types that expose descriptor context support environment-qualified Edit & Test descriptor paths:

all:
  - eq:
      path: system.type
      value: data-product
  - eq:
      path: descriptor.production.classification
      value: restricted

Only scalar fields compatible with every selected System Type can be used. Witboost resolves only requested fields and does not persist the complete descriptor.

Definition root

Definitions use workflow.definition/v2:

schema: workflow.definition/v2
stages:
  - name: READY
    initial: true
  - name: COMPLETED
    terminal: success
transitions:
  - id: start
    from: null
    to: READY
    trigger:
      type: EVENT
      config:
        eventTypes: [example.started]

Root field	Required	Meaning
schema	Yes	Definition format; currently workflow.definition/v2.
stages	Yes	Non-empty list of states. Exactly one is initial.
transitions	Yes	Non-empty list of movements between stages.
macroPhases	Type-specific	Higher-level groups for stage visualization.
parameters	Type-specific	Values exposed by a workflow type when supported.

Stages

Each stage has a unique name. Optional fields include:

• initial: true, required on exactly one stage;
• terminal: success or terminal: failure;
• metadata.label, metadata.description, and a mui: icon;
• metadata.macroPhase when the workflow type provides macro phases.

Transitions

Field	Required	Meaning
id	Recommended	Stable unique identifier used in history.
from	Yes	Source stage, or null for an initial transition.
to	Yes	Target stage.
trigger	Yes	Signal that starts the transition.
preconditions	No	Ordered checks that must pass.
actions	No	Ordered side effects executed before committing the target stage.
when	No	EXPRESSION used to choose between matching branches.
priority	No	Non-negative priority; lower values run first.
metadata	No	User-facing label and graph presentation, including show: false.

when.value uses the same expression operators as activation scope, but reads runtime context provided by the workflow type.

Available building blocks

The engine implements the following catalog. A workflow type exposes only its registered subset; both the Work definition guide and backend validation enforce it.

Triggers

Type	Purpose	Main configuration
EVENT	Start or correlate a transition from a platform event.	Non-empty eventTypes; optionally where, environmentPriority, or environmentRef.
MANUAL	Start a transition from a manual command.	No configuration fields.
APPROVAL_RESPONSE	Route an ASK_APPROVAL result.	alias plus outcome: APPROVE | REJECT.
MANUAL_APPROVAL_RESPONSE	Route a MANUAL_APPROVAL result.	approvalId plus outcome: APPROVE | REJECT.

Event names are constrained by each workflow type's event policy.

Preconditions

Type	Purpose	Main configuration
WORKFLOW_RELATED	Require a stage from a correlated workflow instance.	workflowId, state, correlator; optionally an environment.

Actions

Type	Purpose	Main configuration
ASK_APPROVAL	Create the standard Deploy Approval request.	Unique alias, non-empty approvers, optional outcome messages.
MANUAL_APPROVAL	Create a generic approval with custom templates and delivery channels.	Unique approvalId, non-empty approvers, notifications, optional channels.

Approvers support Team Roles and RBAC roles:

approvers:
  - strategy: team-role
    recipient: OWNER
  - strategy: rbac-role
    recipient: GOVERNANCE_TEAM
    scope:
      anyOf: [domain, wildcard]

RBAC scope dimensions are entity, domain, systemType, and wildcard. Role recipients are exact RBAC role IDs. Resolved recipients are merged and deduplicated; the first authorized response wins.

Manual approval channels

MANUAL_APPROVAL.config.channels is an exact, non-empty selection from push, email, and webhook. It applies to request and outcome notifications.

Configuration	Delivery behavior
Field omitted	Push only
channels: [push]	Push only; actionable in-app
channels: [email]	Email only
channels: [webhook]	Webhook only; no in-app notification
channels: [push, email, webhook]	All three channels

Webhook delivery requires an enabled Manual approval requested binding in Extension Manager -> Webhooks. The webhook body contains the callback URL, method, approve/reject statuses, and responder identity field.

Manual approval templates

MANUAL_APPROVAL.notifications requires request, approved, and rejected. Each entry contains title and bodyHtml.

Variable	Availability
system.name, system.url	System context
release.displayName, release.version, release.isSnapshot	Release context
environment.name, domain.name	Optional context
requester.displayName	Request context
responder.displayName	Approved/rejected templates only
approval.id, workflow.name, transition.from, transition.to	Workflow context

Unknown variables and unsafe HTML are rejected or sanitized. Optional presentation values do not prevent delivery: when requester display data cannot be resolved, approvers still receive the request and the value is empty.

Validation

Saving and publishing validates YAML structure, identifiers, stage references, terminal outcomes, macro phases, context paths, event policies, building-block availability, configuration schemas, and approval correlations. Invalid drafts remain editable and never replace the published version.