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

- **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 `businessRuleTask`; 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 `businessRuleTask`
  (`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.
- **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 like the BPMN.** The DMN is version-controlled in `workflows/` and deployed to the DMN
  engine by the same `flowable-init` step (via `dmn-api/dmn-repository/deployments`), staged into the
  `fl-bpmn` volume alongside the BPMN.

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