[Guide] incident.processing-rules documents pre-#290 institution matching (key->name) — code is key-to-key #29

New Issue

2026-07-17T08:18:49-04:00

hiveiq commented

2026-07-17 08:18:49 -04:00

Type: Documentation — incident.processing-rules describes pre-#290 behaviour.

Problem

The module documents institution matching as key → name resolution, compared against the ATM's institution name. That is how it worked before #290/#232. The code now compares KEY to KEY and never resolves a name.

Current code (IncidentAutoCreationService.findApplicableRule, and the same shape in processConfigurableClosingRules):

// #290/#232 — rules are scoped by the tenant KEY, which the UI writes and the ATM now carries.
// This used to resolve the rule's key to a display NAME and compare it to atms.institution —
// NULL for most devices — so NO institution-scoped rule could ever fire.
.filter(r -> r.getInstitution() != null && !r.getInstitution().isBlank()
        && institutionKey != null
        && r.getInstitution().equalsIgnoreCase(institutionKey))

institutionKeyService is still injected but is not used for rule matching.

Why this matters (it cost real time today)

While investigating incident#241 (PBNC EMV fallback reported twice by a customer), the Guide's gotcha —

Institution match resolves rule's stored institution as a KEY → institution NAME, then compares to ATM's institution name ... Key-vs-name mismatch = rule silently falls through to global

— led me to conclude the customer's rule was silently falling through and that #232 was the root cause. Both were wrong. The rule is firing correctly in production (verified in Loki: SUPPRESS rule 'EMV Fallback Suppression for Peoples Bank ONLY' matched for APPLICATION_ERROR_CARD on ATM NC000936, institution=PBNC, as recently as this morning). I posted that wrong conclusion onto a customer-facing ticket and had to retract it.

The Guide is meant to stop exactly this. Here it actively caused it.

Stale locations

File	Line	Says
`claude.md`	74	"resolves rule's stored `institution` as a KEY → institution NAME, then compares to ATM's institution name; unresolved key falls back to raw value. Key-vs-name mismatch = rule silently falls through to global."
`internal.md`	62	failure-mode row: "ATM institution name doesn't equal the rule's institution name" / "Verify the institution key resolves to the ATM's institution name"
`internal.md`	68	cites `institutionKeyService.findByKey(...).getInstitutionName()` — that call no longer exists in the matcher
`architect.md`	52	"rule institution key → institution name, compared to ATM institution"

claude.md:83 ("Do NOT assume rule institution is a display name — it's stored as the institution KEY") is still correct and should stay.

Fix

Rewrite those four to describe key-to-key matching, and keep the historical note that pre-#290 name-based matching was the old defect — the "silently falls through to global" fallback behaviour is still real when a rule's key genuinely does not match the ATM's key, so that warning should be preserved, just for the right reason.

**Type:** Documentation — `incident.processing-rules` describes pre-#290 behaviour. ## Problem The module documents institution matching as **key → name resolution**, compared against the ATM's institution *name*. That is how it worked before #290/#232. **The code now compares KEY to KEY** and never resolves a name. Current code (`IncidentAutoCreationService.findApplicableRule`, and the same shape in `processConfigurableClosingRules`): ```java // #290/#232 — rules are scoped by the tenant KEY, which the UI writes and the ATM now carries. // This used to resolve the rule's key to a display NAME and compare it to atms.institution — // NULL for most devices — so NO institution-scoped rule could ever fire. .filter(r -> r.getInstitution() != null && !r.getInstitution().isBlank() && institutionKey != null && r.getInstitution().equalsIgnoreCase(institutionKey)) ``` `institutionKeyService` is still injected but is **not** used for rule matching. ## Why this matters (it cost real time today) While investigating **incident#241** (PBNC EMV fallback reported twice by a customer), the Guide's gotcha — > Institution match resolves rule's stored `institution` as a KEY → institution NAME, then compares to ATM's institution name ... Key-vs-name mismatch = rule silently falls through to global — led me to conclude the customer's rule was silently falling through and that #232 was the root cause. **Both were wrong.** The rule is firing correctly in production (verified in Loki: `SUPPRESS rule 'EMV Fallback Suppression for Peoples Bank ONLY' matched for APPLICATION_ERROR_CARD on ATM NC000936`, institution=PBNC, as recently as this morning). I posted that wrong conclusion onto a customer-facing ticket and had to retract it. The Guide is meant to stop exactly this. Here it actively caused it. ## Stale locations | File | Line | Says | |---|---|---| | `claude.md` | 74 | "resolves rule's stored `institution` as a **KEY** → institution NAME, then compares to ATM's institution name; unresolved key falls back to raw value. Key-vs-name mismatch = rule silently falls through to global." | | `internal.md` | 62 | failure-mode row: "ATM institution name doesn't equal the rule's institution *name*" / "Verify the institution key resolves to the ATM's institution name" | | `internal.md` | 68 | cites `institutionKeyService.findByKey(...).getInstitutionName()` — that call no longer exists in the matcher | | `architect.md` | 52 | "rule institution key → institution name, compared to ATM institution" | `claude.md:83` ("Do NOT assume rule `institution` is a display name — it's stored as the institution KEY") is **still correct** and should stay. ## Fix Rewrite those four to describe key-to-key matching, and keep the historical note that pre-#290 name-based matching was the old defect — the "silently falls through to global" fallback behaviour is still real when a rule's key genuinely does not match the ATM's key, so that warning should be preserved, just for the right reason.

hiveiq self-assigned this 2026-07-17 08:18:49 -04:00

hiveiq referenced this issue from a commit

2026-07-17 08:20:57 -04:00

docs(guide): incident.processing-rules — institution match is KEY to KEY

hiveiq referenced this issue

2026-07-17 08:21:21 -04:00

docs(guide): incident.processing-rules — institution match is KEY to KEY (#29) #30

hiveiq referenced this issue from a commit

2026-07-17 08:23:52 -04:00

Merge pull request 'docs(guide): incident.processing-rules — institution match is KEY to KEY (#29)' (#30) from docs/29-institution-key-matching into develop

Sign in to join this conversation.