# Activiti integration

> **Deferred for full coverage** — Activiti is wired into the codebase
> but cannot be observed end-to-end in a deployment that doesn't run
> approval flows. 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`, `xlyApi` | `org.activiti:activiti-engine:5.17.0` | Older 5.x line — declared in both modules |
| `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 from both `xlyPersist` and `xlyApi` to avoid confusion,
(b) document which version the live schema uses, (c) verify the
`act_*` table layout matches that version exactly.

One extra code fact matters in this branch: `xlyFlow/build.gradle` pulls
in the Activiti 6 starter, but `xlyFlow/src/main/java/com/xly/XlyFlowApplicationBoot.java`
is fully commented out. So workflow code is present, but this repository
does not currently present `xlyFlow` as a clearly runnable standalone app.

## The `act_*` schema

The framework ships the expected Activiti `act_*` schema — 24 base
tables (deployment, process-definition, runtime task, history etc.)
plus 3 *views* (`act_id_user`, `act_id_group`, `act_id_membership`).
The base tables populate only when a BPMN process is deployed and a
process instance is started. The identity views are notable: xly does
not maintain real Activiti identity tables; it projects its own
user/group schema into the `act_id_*` shapes via views, so Activiti
sees xly's logins as if they were native Activiti users.

## 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.

Like the underlying Activiti tables, these wrappers populate only in
deployments that actually run an approval flow.

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.
- `xlyFlow/src/main/java/com/xly/activiti/config/ActivitiConfig.java` —
  `@Configuration` implementing `ProcessEngineConfigurationConfigurer`,
  the Spring Boot wire-up for Activiti's process engine.
- `CheckFlowController` in `xlyEntry/com/xly/web/businessweb/` is one
  surface the SPA hits to drive workflow (approve / reject / view).
  Note: the URL prefix is `/checkflow` (lowercase), not the camelCase
  class name.
- `xlyFlow/src/main/java/com/xly/XlyFlowApplicationBoot.java` is fully
  commented out on this branch — the workflow code is consumed as a
  library through xlyEntry rather than as a standalone runnable.
- **No BPMN definitions ship in this repo** under
  `xlyFlow/src/main/resources/` (no `processes/` subdir, no `*.bpmn*`
  files). Deployments must supply them at runtime, e.g. via the
  Activiti modeler whose static assets live at
  `xlyFlow/src/main/resources/static/modeler/`.

## 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.