eho/register-referentie
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

adr-proposal: ACL resolves its zaaktype by identificatie, not a pinned URL (S-27) #117

New Issue
Closed
opened 2026-07-22 13:10:38 +00:00 by not · 0 comments
not commented 2026-07-22 13:10:38 +00:00
Contributor
Copy Link
Copy Source

ADR-proposal for S-27 (#113) — the design to agree before coding (CLAUDE.md §14).

Context

Today the ACL is handed a pinned zaaktype URL (Acl__Defaults__ZaaktypeUrl) and informatieobjecttype URL. Those UUIDs are server-assigned by OpenZaak at creation, so every stack must seed the catalogus and then inject the resulting URLs out of band — CI does it in run-domain-check.sh, and the local stack does it via the local-seed→acl.env bootstrap added in ADR-0020 (#110). Brittle, and a placeholder URL fails opaquely (OpenZaak 400).

Proposed decision

The ACL resolves its zaaktype (and diploma informatieobjecttype) by stable business key against OpenZaak's Catalogi API, instead of a pinned URL.

  • Config: replace Acl__Defaults__ZaaktypeUrl → Acl__Defaults__ZaaktypeIdentificatie (BIG-REGISTRATIE) and …InformatieobjecttypeUrl → …InformatieobjecttypeOmschrijving (Diploma).
  • Lookup (in the gateway, §8.1): GET /catalogi/api/v1/zaaktypen?identificatie=BIG-REGISTRATIE&status=definitief → the published zaaktype URL; GET /catalogi/api/v1/informatieobjecttypen?status=definitief matched on omschrijving. Reuses the existing GetCatalogusAsync machinery.
  • Timing = lazy + cached for process lifetime. Resolve on first use (first zaak open / document store), then cache the URLs. Rationale: avoids a startup ordering coupling (the zaaktype may be published after the ACL boots — e.g. the seed runs concurrently), so the ACL never crash-loops waiting for the catalogus; a per-request lookup is avoided by the cache. A restart re-resolves. (Alternatives: resolve-at-startup — simpler cache but reintroduces ordering coupling; per-request — no cache but a lookup every call. Rejected.)
  • Failure mode: if no published zaaktype/iot matches, throw a clear, actionable error ("no published BIG-REGISTRATIE zaaktype found in OpenZaak") — replacing today's opaque placeholder-URL 400.

Consequences

  • Both compose stacks drop the pinned-URL injection: docker-compose.yml/run-domain-check.sh stop capturing+injecting the URL, and the local local-seed no longer writes acl.env (it still creates/publishes the zaaktype; the ACL just discovers it). The seed-env volume + ACL entrypoint shim from ADR-0020 can be removed → simpler local stack.
  • New branching logic in the gateway/resolver → new unit + integration tests; mutation ratchet must stay ≥ baseline (§5).
  • A seed step is still required to create + publish the zaaktype (this ADR only changes discovery, not creation).

Scope / plan

TDD: red test for the cached resolver + gateway lookup → implement → live integration test (resolve against a real seeded OpenZaak) → remove the pinned-URL injection from both stacks + verify scripts → ADR-0021 file + docs. Supersedes the ADR-0020 acl.env mechanism.

Seeking agreement on the lazy+cached timing and the identificatie/omschrijving config keys before implementing.

ADR-proposal for **S-27 (#113)** — the design to agree before coding (CLAUDE.md §14). ## Context Today the ACL is handed a **pinned zaaktype URL** (`Acl__Defaults__ZaaktypeUrl`) and informatieobjecttype URL. Those UUIDs are server-assigned by OpenZaak at creation, so every stack must seed the catalogus and then inject the resulting URLs out of band — CI does it in `run-domain-check.sh`, and the local stack does it via the `local-seed`→`acl.env` bootstrap added in ADR-0020 (#110). Brittle, and a placeholder URL fails opaquely (OpenZaak 400). ## Proposed decision **The ACL resolves its zaaktype (and diploma informatieobjecttype) by stable business key against OpenZaak's Catalogi API, instead of a pinned URL.** - **Config:** replace `Acl__Defaults__ZaaktypeUrl` → `Acl__Defaults__ZaaktypeIdentificatie` (`BIG-REGISTRATIE`) and `…InformatieobjecttypeUrl` → `…InformatieobjecttypeOmschrijving` (`Diploma`). - **Lookup (in the gateway, §8.1):** `GET /catalogi/api/v1/zaaktypen?identificatie=BIG-REGISTRATIE&status=definitief` → the published zaaktype URL; `GET /catalogi/api/v1/informatieobjecttypen?status=definitief` matched on `omschrijving`. Reuses the existing `GetCatalogusAsync` machinery. - **Timing = lazy + cached for process lifetime.** Resolve on first use (first zaak open / document store), then cache the URLs. Rationale: avoids a startup ordering coupling (the zaaktype may be published *after* the ACL boots — e.g. the seed runs concurrently), so the ACL never crash-loops waiting for the catalogus; a per-request lookup is avoided by the cache. A restart re-resolves. (Alternatives: resolve-at-startup — simpler cache but reintroduces ordering coupling; per-request — no cache but a lookup every call. Rejected.) - **Failure mode:** if no **published** zaaktype/iot matches, throw a clear, actionable error ("no published BIG-REGISTRATIE zaaktype found in OpenZaak") — replacing today's opaque placeholder-URL 400. ## Consequences - Both compose stacks drop the pinned-URL injection: `docker-compose.yml`/`run-domain-check.sh` stop capturing+injecting the URL, and the local `local-seed` no longer writes `acl.env` (it still *creates/publishes* the zaaktype; the ACL just discovers it). The `seed-env` volume + ACL entrypoint shim from ADR-0020 can be removed → simpler local stack. - New branching logic in the gateway/resolver → new unit + integration tests; mutation ratchet must stay ≥ baseline (§5). - A seed step is still required to *create + publish* the zaaktype (this ADR only changes discovery, not creation). ## Scope / plan TDD: red test for the cached resolver + gateway lookup → implement → live integration test (resolve against a real seeded OpenZaak) → remove the pinned-URL injection from both stacks + verify scripts → ADR-0021 file + docs. Supersedes the ADR-0020 `acl.env` mechanism. Seeking agreement on the **lazy+cached** timing and the **identificatie/omschrijving** config keys before implementing.
not added this to the Iteration 2 — Flow Completeness milestone 2026-07-22 13:10:38 +00:00
not added the type:adr-proposalarea:acl labels 2026-07-22 13:10:38 +00:00
not closed this issue 2026-07-22 14:49:27 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:acl
area:bff
area:docs
area:domain
area:event-subscriber
area:infra
area:portal-behandel
area:portal-beheer
area:portal-openbaar
area:portal-self-service
area:projection
area:workflow
type:adr-proposal
type:bug
type:chore
type:slice
No labels area:acl type:adr-proposal
Milestone
No items
No Milestone Iteration 2 — Flow Completeness
Projects
Clear projects
No projects
Assignees
Clear assignees
eho (Edwin van den Houdt)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: eho/register-referentie#117