# Activiti integration

> **Deferred for full coverage** — Activiti is wired into the codebase
> but no process is deployed in this dev DB. See
> [Slice 7 (deferred)](../../slices/07-workflow.md).

This page captures what's *in the codebase* about Activiti so a future
maintainer doesn't start from zero when the workflow story is finally
exercised.

## Two Activiti versions

The dependency tree carries **two** Activiti versions:

| Module | Version | Notes |
|---|---|---|
| `xlyPersist` | `org.activiti:activiti-engine:5.17.0` | Older 5.x line |
| `xlyFlow` | `org.activiti:activiti-spring-boot-starter-rest-api:6.0.0`, `activiti-json-converter:6.0.0` | Newer 6.0 line |

This is a real version mismatch. Activiti's 5.x and 6.x schemas overlap
but diverge in some `act_*` tables and migration paths. Possibilities:

1. The framework runs Activiti 6.0 (xlyFlow drives the runtime) and
   xlyPersist's 5.17 dependency is dead weight from an earlier era.
2. Different services use different versions for legacy reasons.
3. Both are in the classpath but only one is initialised at runtime.

A future maintainer attacking this should: (a) remove the unused
version to avoid confusion, (b) document which version the live
schema uses, (c) verify the `act_*` table layout matches that version
exactly.

## The `act_*` schema

24 `act_*` tables ship in the dev DB:

- `act_re_*` — process definitions (deployments, BPMN sources)
- `act_ru_*` — runtime tables (running tasks, executions, variables)
- `act_hi_*` — historic tables (completed processes, finished tasks)
- `act_ge_*` — generic infrastructure (binary properties, etc.)
- `act_id_*` — identity tables (users, groups — typically not used
  when xly's own user model is in front)

All 24 are **empty in dev**.

## xly's wrapper layer

Three xly tables wrap the Activiti integration:

- [`biz_flow`](../../auto-catalog/tables/biz_flow.md) — xly's per-document
  flow state.
- [`biz_todo_item`](../../auto-catalog/tables/biz_todo_item.md) —
  pending approver tasks.
- [`biz_todo_copyto`](../../auto-catalog/tables/biz_todo_copyto.md) —
  CC'd parties on a flow.
- [`gdsmoduleflow`](../../auto-catalog/tables/gdsmoduleflow.md) +
  `gdsmoduleflowslave` — module-flow window configuration.

All empty in dev too.

The pattern when active: a document submission writes a `biz_flow`
row + an Activiti process instance starts; pending approvers see
`biz_todo_item` rows; on approval the proc instance advances and
eventually completes.

## Where Activiti is wired in code

`xlyFlow/` is the dedicated module. Notable files (when this page is
fleshed out):

- `xlyFlow`'s `pom`-equivalent gradle build pulls in Activiti 6.0.
- The Spring Boot config for Activiti's process engine.
- `CheckFlowController` in `xlyEntry/com/xly/web/businessweb/` is one
  surface the SPA hits to drive workflow (approve / reject / view).
- BPMN process definitions, when present, live in
  `xlyFlow/src/main/resources/processes/` (or similar) — empty in
  this codebase.

## What's needed to make Activiti work

In a deployment that uses workflow:

1. BPMN process definitions deployed (`act_re_procdef` populated).
2. Modules tagged `bCheck = 1` and linked to the right process via
   `gdsmoduleflow`.
3. Approver users assigned via `act_id_*` or xly's wrapper of it.
4. The save endpoint, on `bCheck = 1` modules, branches to start a
   process instance instead of (or alongside) the standard
   add/update/delete.

This page becomes a real reference once a deployment with deployed
processes is available; until then, treat it as an inventory of what
*ought* to be here.