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

@@ -36,12 +36,18 @@ only new job is to carry the diploma origin and pass it into the process as a st
   `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 in one `.bar` with the BPMN.** The DMN is version-controlled in `workflows/` and bundled
-  with `registratie.bpmn` into a single `registratie.bar` (by `seed-config.sh`) that `flowable-init`
-  deploys as one deployment. This is required, not cosmetic: `flowable-rest` does not expose the
-  `dmn-api` app, and Flowable resolves an inline DMN scoped to the process's own deployment — so a
-  standalone `.dmn` deployment is invisible to the process (`FlowableObjectNotFoundException: No
-  decision found for key`). Co-deploying gives the decision the process's parent deployment id.
+- **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
 

infra/docker-compose.yml

@@ -259,23 +259,30 @@ services:
   flowable-init:
     image: docker.io/curlimages/curl:latest
     restart: "no"
-    # registratie.bar (registratie.bpmn + diploma-eligibility.dmn) is streamed into this external
-    # volume by infra/seed-config.sh.
+    # registratie.bpmn + diploma-eligibility.dmn are streamed into this external volume by
+    # infra/seed-config.sh.
     volumes:
       - fl-bpmn:/work:ro
     command:
       - sh
       - -c
       - |
-        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        # Deploy the BPMN + its DMN as ONE .bar so the inline DMN service task resolves the decision by
-        # the process's own (shared) parent deployment id — flowable-rest does not expose the dmn-api app,
-        # and a standalone .dmn deployment is not visible to the process (S-13, ADR-0016).
-        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        svc=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        dmn=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
+        until curl -sf -u rest-admin:test "$$svc" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        # Deploy the DMN to the DMN engine and the BPMN to the process engine as SEPARATE deployments:
+        # flowable-rest does NOT cascade a .dmn bundled in a process .bar into the DMN engine, so the DMN
+        # must go via dmn-api. The process's DMN service task then resolves the decision across deployments
+        # by key (S-13, ADR-0016). Both steps are idempotent (skip if already deployed).
+        if curl -s -u rest-admin:test "$$dmn" | grep -q '"name":"diploma-eligibility.dmn"'; then
+          echo "diploma-eligibility DMN already deployed; skip"
         else
-          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bar;filename=registratie.bar' "$$base" >/dev/null && echo "deployed registratie (bpmn + dmn)"
+          curl -sf -u rest-admin:test -F 'file=@/work/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmn" >/dev/null && echo "deployed diploma-eligibility DMN"
+        fi
+        if curl -s -u rest-admin:test "$$svc?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie BPMN already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$svc" >/dev/null && echo "deployed registratie BPMN"
         fi
     depends_on:
       flowable-rest:

infra/flowable/docker-compose.yml

@@ -35,28 +35,35 @@ services:
         condition: service_healthy
     networks: [cg]
 
-  # Deploys registratie.bar (registratie.bpmn + diploma-eligibility.dmn) via the REST API once
-  # flowable-rest is up. Idempotent: skips if a deployment named "registratie" already exists.
+  # Deploys registratie.bpmn (process engine) and diploma-eligibility.dmn (DMN engine) via the REST
+  # API once flowable-rest is up. Idempotent: skips each if already deployed.
   flowable-init:
     image: docker.io/curlimages/curl:latest
     restart: "no"
-    # registratie.bar (registratie.bpmn + diploma-eligibility.dmn) is streamed into this external
-    # volume by infra/seed-config.sh.
+    # registratie.bpmn + diploma-eligibility.dmn are streamed into this external volume by
+    # infra/seed-config.sh.
     volumes:
       - fl-bpmn:/work:ro
     command:
       - sh
       - -c
       - |
-        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        # Deploy the BPMN + its DMN as ONE .bar so the inline DMN service task resolves the decision by
-        # the process's own (shared) parent deployment id — flowable-rest does not expose the dmn-api app,
-        # and a standalone .dmn deployment is not visible to the process (S-13, ADR-0016).
-        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        svc=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        dmn=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
+        until curl -sf -u rest-admin:test "$$svc" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        # Deploy the DMN to the DMN engine and the BPMN to the process engine as SEPARATE deployments:
+        # flowable-rest does NOT cascade a .dmn bundled in a process .bar into the DMN engine, so the DMN
+        # must go via dmn-api. The process's DMN service task then resolves the decision across deployments
+        # by key (S-13, ADR-0016). Both steps are idempotent (skip if already deployed).
+        if curl -s -u rest-admin:test "$$dmn" | grep -q '"name":"diploma-eligibility.dmn"'; then
+          echo "diploma-eligibility DMN already deployed; skip"
         else
-          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bar;filename=registratie.bar' "$$base" >/dev/null && echo "deployed registratie (bpmn + dmn)"
+          curl -sf -u rest-admin:test -F 'file=@/work/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmn" >/dev/null && echo "deployed diploma-eligibility DMN"
+        fi
+        if curl -s -u rest-admin:test "$$svc?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie BPMN already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$svc" >/dev/null && echo "deployed registratie BPMN"
         fi
     depends_on:
       flowable-rest:

infra/seed-config.sh

@@ -35,18 +35,13 @@ populate() {  # volume  source(file or dir/.)
 
 [ "$#" -gt 0 ] || { echo "usage: seed-config.sh <oz|nrc|kc|fl> ..." >&2; exit 2; }
 
-# The registratie process and its diploma-eligibility DMN must land in ONE Flowable deployment, so the
-# process's inline DMN service task resolves the decision by its (shared) parent deployment id (S-13,
-# ADR-0016). We bundle both into a single .bar (zip) and deploy that one artefact.
-build_flowable_bar() {
-  local out="$1"
-  python3 - "$here/../workflows/registratie.bpmn" "$here/../workflows/diploma-eligibility.dmn" "$out" <<'PY'
-import sys, zipfile
-bpmn, dmn, out = sys.argv[1:4]
-with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
-    z.write(bpmn, "registratie.bpmn")
-    z.write(dmn, "diploma-eligibility.dmn")
-PY
+# The registratie process (BPMN) and its diploma-eligibility DMN are deployed as SEPARATE Flowable
+# deployments — the process engine and the DMN engine each own theirs (S-13, ADR-0016). flowable-rest
+# does not cascade a .dmn bundled in a process .bar into the DMN engine, so we seed both raw files and
+# let flowable-init deploy each via its own REST app. We stage them in a temp dir and copy its contents.
+stage_flowable_workflows() {
+  local dir="$1"
+  cp "$here/../workflows/registratie.bpmn" "$here/../workflows/diploma-eligibility.dmn" "$dir/"
 }
 
 for key in "$@"; do
@@ -54,7 +49,7 @@ for key in "$@"; do
     oz) populate rr-oz-config "$here/openzaak/setup_configuration/." ;;
     nrc) populate rr-nrc-config "$here/opennotificaties/setup_configuration/." ;;
     kc) populate rr-kc-realms "$here/keycloak/realms/." ;;
-    fl) bar="$(mktemp -d)/registratie.bar"; build_flowable_bar "$bar"; populate rr-fl-bpmn "$bar" ;;
+    fl) d="$(mktemp -d)"; stage_flowable_workflows "$d"; populate rr-fl-bpmn "$d/." ;;
     *)  echo "unknown seed key: $key" >&2; exit 2 ;;
   esac
 done

workflows/diploma-eligibility.dmn

@@ -1,14 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- Diploma-eligibility decision (S-13, ADR-0016). Evaluated inline by the registratie process as a
-     BPMN DMN service task: given the diploma's origin, it sets the `route` the process should take.
-     A foreign (Buitenlands) diploma routes through the extra CBGV-advies assessment step; a domestic
-     one (or anything else) goes DIRECT to beoordeling. FIRST hit policy: the foreign rule wins, and
-     the empty-input catch-all is the default. -->
 <definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/"
              xmlns:flowable="http://flowable.org/dmn"
              id="diplomaEligibilityDefinitions"
              name="Diploma eligibility"
              namespace="http://respellion.nl/big/dmn">
+  <!-- Diploma-eligibility decision (S-13, ADR-0016). Evaluated inline by the registratie process as a
+       BPMN DMN service task: given the diploma's origin, it sets the `route` the process should take.
+       A foreign (Buitenlands) diploma routes through the extra CBGV-advies assessment step; a domestic
+       one (or anything else) goes DIRECT to beoordeling. FIRST hit policy: the foreign rule wins, and
+       the empty-input catch-all is the default.
+       NB: the comment lives INSIDE <definitions> on purpose — Flowable's DMN XML converter chokes on a
+       comment between the XML declaration and the root element ("XMLStreamReader not in START_DOCUMENT
+       or START_ELEMENT state"), unlike its BPMN converter. -->
   <decision id="diploma-eligibility" name="Diploma eligibility">
     <decisionTable id="dt-diploma-eligibility" hitPolicy="FIRST">
       <input id="in-origin" label="Diploma origin">