Configure and Operate Workflows

Use this guide to create, publish, update, and retire workflow configurations from Administration panel -> Workflows. For field-level syntax, see the Workflow Configuration and Definition Reference.

Create and publish a configuration

1. Open Administration panel -> Workflows.
2. Select a workflow type.
3. Create a configuration with a descriptive name and positive priority.
4. Select the guided activation-scope values and add any advanced conditions to the activation scope YAML.
5. Review and save the initial workflow definition. The first version is a draft.
6. Enable the configuration.
7. Publish the draft.

Only enabled configurations with a published version can start new instances. Lower priority numbers are selected first, and enabled configurations of the same workflow type must have distinct priorities.

Route workflow starts

Use lower priority numbers for specific rules and higher values for fallbacks. For example:

Configuration	Activation scope	Priority
Restricted production	Production and restricted descriptor	10
Production fallback	Any production subject	20

When both scopes match, Witboost selects priority 10.

The editor provides guided filters defined by the workflow type, such as System Types and environments. Extend the generated YAML for additional supported conditions, including descriptor fields when available:

all:
  - eq:
      path: release.environment
      value: production
  - eq:
      path: descriptor.production.classification
      value: restricted

Save routing changes after resolving validation errors. Priority and activation scope belong to the configuration: changing them does not create a definition version or reroute existing instances.

Configure event catch-up polling

The Workflow Engine periodically checks for events that were persisted while live delivery was unavailable. Configure the interval in seconds in the Witboost application configuration:

workflowEngine:
  eventCatchUp:
    pollIntervalSeconds: 60

The default interval is 60 seconds. Increasing it reduces polling frequency but can delay recovery of missed events.

Update a workflow definition

A published version cannot be edited in place:

1. Open the published or retired version that you want to change.
2. Select Edit and confirm draft creation.
3. Update the YAML definition.
4. Use View definition to inspect its stages and transitions.
5. Save and correct all validation errors.
6. Publish the draft.

Publishing retires the previous published version. Instances that already started continue using their original version. Deleting a draft discards only unpublished changes.

Inspect and terminate instances

Each version lists pending, blocked, and completed instances. Open a list to inspect the subject, current stage, selected priority, activation scope, history, and failure reason where applicable.

Administrators can terminate pending or blocked instances individually or in bulk. Termination is irreversible: the instance becomes CANCELLED and cannot continue. Completed instances are read-only.

Disable, archive, and purge

1. Disable a configuration to stop it from being selected for future starts.
2. Archive a disabled configuration to make it read-only while retaining its versions and instance history.
3. Use Purge only when permanent deletion is required and no active instance remains.

Purge removes the configuration, versions, instances, actions, and execution history. For Deploy Approval it also removes historical approval evidence.

Operate System Lifecycle instances

System Lifecycle provides additional administrative operations for existing Systems and exceptional recovery. See System Lifecycle for backfill, placement, Builder inspection, and relocation.