Developer Guide / Workflow Engine

Workflow Engine

Route API calls through BPMN approval workflows.

The workflow service (magicvarsh-workflow-service, internal port 8094) embeds Flowable 7.0.1 (BPMN 2.0) and can also delegate to an external Camunda or Activiti engine. A gateway filter intercepts matching API calls and runs them through a workflow before (or after) they reach the target service.

Workflow configuration under Settings → Workflow.
Workflow configuration under Settings → Workflow.
Workflow interception flow: the gateway filter checks for a service binding; matched requests create a PENDING StagedRequest and start a Flowable process, returning 202; after human approval the original request is forwarded and marked APPROVED, otherwise REJECTED.
Workflow interception — when a route is bound to an approval flow, the gateway holds the request (202 + correlationId), starts a BPMN process, and only forwards it to the real service once a reviewer approves.

Core concepts

  • Workflow definitions — BPMN 2.0 XML deployed via the admin UI or POST /api/workflow/definitions/deploy; the process_key comes from the BPMN process id, auto-versioned with one active version per key.
  • Service bindings — map an API call (service_name, Ant-style path_pattern, http_method, PRE/POST trigger_type) to a workflow. First match wins; the gateway binding cache refreshes every 60s.
  • PRE interception — holds the request, returns 202 with a correlationId and PENDING status; the client polls until it is approved and forwarded.
  • POST interception — the request passes through immediately and the workflow runs asynchronously afterwards (audit, notifications, post-processing).

Staged requests move through PENDING → APPROVED | REJECTED | EXPIRED | ERROR. Tasks are claimed and completed from the admin Task Inbox or the /api/workflow/tasks API; completion sends an outcome variable that BPMN exclusive gateways branch on.

The content workflow / approvals view.
The content workflow / approvals view.

Escalation

Each binding can set an escalation threshold (default 60 minutes). An escalation scheduler runs every 5 minutes and emails the assigned manager (via the email service) for overdue tasks.

i
To use an external engine, set the engine type to CAMUNDA or ACTIVITI with its REST URL and credentials under Settings → Workflow — the switch is live and needs no restart.