register-referentie/docs/architecture/adr-0009-external-task-job-worker.md

ADR-0009: The Domain Service drives Flowable as an external-task job worker

• Status: Accepted
• Date: 2026-06-30
• Deciders: Respellion engineering
• Relates to: S-05 (#6); proposal #60; builds on ADR-0001 (loose coupling, §8.1/§8.2), S-03 (#4, the registratie BPMN), S-04 (#5, the ACL OpenZaak operation)

Context

S-05 (#6) adds the BIG Domain Service. Submitting a registration must: create a Registration aggregate, start the Flowable registratie process (S-03), have the OpenZaakAanmaken task open a zaak via the ACL (S-04), and store the resulting zaak URL back on the aggregate.

OpenZaakAanmaken is a Flowable external-worker service task (flowable:type="external-worker", topic OpenZaakAanmaken). Flowable does not push it anywhere — it parks the job and waits for a worker to acquire and lock it, do the work, and complete it. Two coupling rules constrain who may do what:

• §8.2 — the Workflow Client is the only code that talks to Flowable. BPMN models never embed OpenZaak knowledge; they ask the Workflow Client to execute external tasks.
• §8.1 — the ACL is the only code that talks to ZGW. The worker opens the zaak through the ACL, never by constructing ZGW URLs itself.

This is an ADR-worthy moment (§14): a service boundary is defined and both coupling rules are exercised. The open question is how the external task is driven.

Decision

The Domain Service drives the OpenZaakAanmaken task as a hosted external-task job worker (PRD §36). Orchestration is eventually consistent, not request-synchronous.

• POST /registrations is fast and side-effecting only on the domain side. It creates the Registration aggregate in state INGEDIEND, persists it, and asks the Workflow Client to start one registratie process instance, recording the process-instance id on the aggregate. It returns immediately; it does not wait for the zaak to be opened.
• A hosted worker polls Flowable for OpenZaakAanmaken jobs. It acquires and locks a job, calls the ACL OpenZaak operation (§8.1), attaches the returned zaak URL to the matching aggregate (Registration.AttachZaak), and completes the job in Flowable. The process then runs to its end event.
• The Workflow Client is the only Flowable client (§8.2). It lives in the Domain Service's Infrastructure layer and speaks Flowable's REST API (start process-instance; acquire/lock/complete external-worker jobs). No other code — not the Application layer, not the BPMN — knows Flowable exists.
• The worker logic is an Application service over ports, not Flowable-aware code. OpenZaakWorker takes an acquired job (topic + the registration id it carries), calls IAclClient and IRegistrationStore, and returns the zaak URL to complete with. The polling loop is a thin BackgroundService in Infrastructure that fetches jobs via the Workflow Client and feeds them to the worker. So the orchestration is covered by fast unit tests against fakes; only the REST framing needs a container integration test.

Scope decisions for the minimal slice

• Registration persistence is in-memory. The walking skeleton's read path is fed by NRC → Event Subscriber → projection (S-06, #7), not by the domain database. An EF-backed domain store buys nothing the demo needs yet, so it is a documented follow-up; the IRegistrationStore port keeps that change additive. (PRD §88 envisions EF Core for the domain DB eventually.)
• The aggregate's state machine is minimal: INGEDIEND on submission. Later flows (withdrawal, beoordeling, herregistratie) add states in their own slices — they are out of scope here.
• No bsn flows to ZGW yet. The ACL OpenZaak operation already default-fills the ZGW-mandatory fields (ADR-0003) and takes the bsn as its domain payload; the domain hands it through unchanged.

Consequences

• Positive: the submit request is decoupled from ACL/OpenZaak latency; the documented Common Ground pattern (external-task worker) is realised; both coupling rules (§8.1, §8.2) hold with the Flowable knowledge isolated to one Infrastructure class; the orchestration is unit-testable.
• Negative / deferred:
  • Eventual consistency: immediately after POST /registrations the aggregate has no zaak URL yet. Acceptable — the read side is the projection, not the domain store.
  • In-memory registration state is lost on restart; fine for the skeleton, replaced by an EF store in a follow-up.
  • The worker polls (no push); poll interval is a tuning knob, not a correctness concern, since Flowable holds the job until completed.

Alternatives considered

• Synchronous acquire+complete inside the POST /registrations request — rejected: simpler and deterministic, but couples the submit request to ACL/OpenZaak latency and failure, and is not the external-task worker pattern PRD §36 mandates. It would also make the request fail if OpenZaak is briefly down, instead of the job simply staying parked for the worker to retry.
• A standalone Workflow Client service, separate from the Domain Service — rejected for this slice: the worker needs the domain's aggregate store and the ACL client anyway, and PRD §9 places the Workflow Client inside the Domain Service deployment. A separate process adds a hop and a shared store for no current benefit.
• Flowable pushes to a webhook instead of being polled — rejected: Flowable's external-worker model is pull-based (acquire/lock/complete); a push shim would re-implement it with weaker delivery guarantees.