Workflow — How it works

Overview

The workflow engine is a generic, versioned process engine: define a workflow, edit its structure as a draft, publish immutable versions, then run instances that move through declared stages, raise tasks, and record an append-only event log. It carries no clinical/domain knowledge — domain plug-ins (and the program engine's state-change hook) drive it.

Data model & ownership

Area	Tables
Definition & versions	workflow_definition (editable draft, unique code), workflow_version (append-only immutable snapshot)
Structure	workflow_stage, workflow_transition, workflow_role_assignment, workflow_rule
Runtime	workflow_instance, workflow_task, workflow_event (append-only)

Key rules & invariants

• Published versions are immutable. Structure is edited only while the definition is a draft; publishVersion snapshots the config and bumps the version.
• Transition-graph validation: no self-transition, both stages must belong to the same definition, no duplicate transitions/codes, and at most one initial stage.
• Runtime: instances run only published definitions and start at the declared initial stage; a move is rejected unless a declared workflow_transition exists current→target; reaching a terminal stage auto-completes the instance; task lifecycle is PENDING → ASSIGNED → COMPLETED; every change appends an immutable workflow_event (never updated/voided).

API

See the API Reference. Endpoint groups under /api/v1/workflow: workflow definitions (+ versions), draft structure (/{id}/stages|transitions|rules, /stages/{id}/role-assignments), and runtime instances (start/get/search/move/cancel/events/tasks) + /workflow-tasks/{id}/assign|complete.

Configuration & feature flags

Domain-module Feign URL workflow.service.url (WORKFLOW_SERVICE_URL) — used only by plug-ins.

Related features

• Queue (often paired for operational flow), Program (ProgramStateChangeHook). Domain plug-ins call via exchange.client.workflow.