register-referentie/docs/architecture/adr-0016-diploma-eligibility-dmn.md

# ADR-0016: Diploma eligibility is a DMN evaluated inline as a BPMN DMN service task

- **Status:** Accepted
- **Date:** 2026-07-17
- **Deciders:** Respellion engineering
- **Relates to:** S-13 (#14); proposal #100. Builds on ADR-0009 (external-task worker / Workflow
  Client), ADR-0014/0015 (the boundary-event and routing constructs on the registratie process).

## Context

S-13 adds flow 4: a foreign diploma must get an extra CBGV-advies assessment before beoordeling
(PRD §5). The eligibility decision — domestic goes straight to beoordeling, foreign routes through
CBGV-advies — needs a home. The Flowable REST app bundles a DMN engine, and the same
`repository/deployments` machinery that deploys `registratie.bpmn` can deploy a `.dmn`. §8.2 makes
the Workflow Client the only code that talks to Flowable; the PRD frames the workflow as "BPMN + DMN
governing the registration workflow" (Flowable as a peer orchestration module).

The issue's wording ("a DMN decision table evaluated by the Domain Service via Workflow Client")
suggests the domain reaches into Flowable's DMN API to evaluate the decision and feeds the result
back. That is one option; it is not the only one, and it is not the cleanest.

## Decision

**The diploma-eligibility DMN is deployed to Flowable and evaluated inline by the registratie process
as a DMN service task (`flowable:type="dmn"`); an exclusive gateway routes on its output. The domain's
only new job is to carry the diploma origin and pass it into the process as a start variable.**

- **The decision lives in the workflow.** `workflows/diploma-eligibility.dmn` maps `diplomaOrigin`
  → `route` (`Buitenlands` ⇒ `CBGV_ADVIES`, otherwise `DIRECT`). A DMN service task
  (`flowable:type="dmn"`, `decisionTableReferenceKey=diploma-eligibility`) runs it between
  `OpenZaakAanmaken` and `Beoordelen`, and an exclusive gateway sends `CBGV_ADVIES` through a new
  `CBGVAdvies` user task before `Beoordelen`, `DIRECT` straight there. (A `businessRuleTask` would
  bind Flowable's legacy Drools/KIE implementation, which `flowable-rest` does not bundle — its parse
  handler throws `NoClassDefFoundError` at deploy time; the DMN service task is the supported route.)
- **The domain carries the input, not the decision.** The `Registration` aggregate gains a
  `DiplomaOrigin` (Binnenlands/Buitenlands); `SubmitRegistration` passes it to
  `StartRegistrationProcessAsync`, which sets it as the `diplomaOrigin` start variable. The domain
  never evaluates the DMN and never learns the route — that is the process's concern.
- **Deployed as its own DMN-engine deployment, separate from the BPMN.** The DMN is version-controlled
  in `workflows/` and `flowable-init` deploys it to the DMN engine via the `dmn-api`
  (`/dmn-api/dmn-repository/deployments`), while `registratie.bpmn` goes to the process engine via
  `/service/repository/deployments`. Two things were learned the hard way here (both cost a CI cycle):
  (1) `flowable-rest` does **not** cascade a `.dmn` bundled inside a process `.bar` into the DMN engine
  — the resource is stored but no decision is created, so the service task fails at runtime with
  `FlowableObjectNotFoundException: No decision found for key`; the DMN must go through `dmn-api`.
  (2) Flowable's DMN XML converter rejects an XML comment placed between the `<?xml?>` declaration and
  the root `<definitions>` element (`XMLStreamReader not in START_DOCUMENT or START_ELEMENT state`),
  unlike its BPMN converter — so the DMN's documentation comment lives *inside* `<definitions>`.
  With the decision present in the DMN repository, the process's DMN service task resolves it across
  deployments by key (verified live), so no shared parent deployment id is needed.

## Consequences

**Positive**

- The eligibility rule is a first-class, inspectable workflow artefact (matching the PRD's BPMN+DMN
  framing); business users can read/adjust the decision table without touching domain code.
- §8.2 stays clean: the Workflow Client remains the only code talking to Flowable, and the decision
  runs inside the process the client already started — no domain→Flowable round-trip for a decision.
- The domain change is minimal and additive: one value on the aggregate, one start variable.

**Negative / costs**

- Deviates from #14's literal "evaluated by the Domain Service via Workflow Client" wording (noted on
  the issue). The outcome — DMN decides eligibility, foreign diplomas get the CBGV step — is unchanged.
- The DMN and its service-task wiring are validated live (verify-domain drives a foreign
  registration through CBGV-advies and a domestic one straight to beoordeling, exercising both
  branches), not in unit tests — consistent with ADR-0009/0014/0015. The domain unit/acceptance tests
  cover only that the origin is carried into the process.

## Alternatives considered

- **Domain evaluates the DMN via the Workflow Client** (the issue's wording). Rejected: it couples
  the domain to Flowable for a decision and splits the routing across two places (domain computes,
  BPMN branches), for no benefit over letting the engine that owns the process own the decision.
- **Eligibility rules in domain C#.** Rejected: it moves a governable business decision out of the
  DMN the PRD calls for, and hard-codes what the reference app is meant to demonstrate as data.