[Feature] Design recipient fallback hierarchies and failure-only notifications #104

New Issue

2026-10-13T13:11:30+02:00

zemion commented

2026-10-13 13:11:30 +02:00

Problem and intended model

A Campaign entry is a content/data/attachment unit and may have multiple primary recipients. Each recipient has its own stable identity, name, distribution channel, and channel-specific destination. The campaign channel standard is only a preselection when adding a recipient, never a policy that reroutes existing recipients.

Design fallback as subordinate recipient rows: “if this recipient/entry is not reached, send to these recipient rows.” A fallback row has the same name/channel/destination structure and may itself have multiple subordinate fallbacks. Keep normal primary recipients separate from conditional fallbacks. Do not implement fallback as a flat entry-wide channel-policy selector.

The current implementation scope is primary recipient rows with Email/Postbox channels only. This issue captures all fallback work; fallback controls and execution stay disabled until its design and acceptance criteria are agreed.

Decisions to resolve

Does a trigger belong to one recipient, an entry, or an explicitly defined group? For multiple primary recipients, define “entry reached” (any/all/quorum), partial success, and whether multiple fallback children are all attempted or alternatives in order.
Define eligible failure states and timing: confirmed rejection before acceptance, permanent failure, retry exhaustion, timeout, delivery receipt, or unread status. SMTP/Postbox acceptance, actual delivery, and human reading must be distinguished. Never treat an accepted or outcome-unknown effect as an automatic safe trigger for resending the content.
Decide whether the UI is a strict tree or permits references to reusable recipient rows. Prevent cycles, impose bounded depth/branching, preserve stable identities and authored order, and specify deletion/move/duplicate behavior.
Define content and attachment behavior for fallback recipients, including classification, authorization, recipient-specific rendering, review/approval, and cross-channel compatibility.

Failure-only notification action

A subordinate row may mean “notify me that something went wrong” rather than “deliver the original message to me.” Model this as a distinct action/purpose; do not infer it from the destination or channel. Decide the notification template, minimal diagnostic fields, aggregation/rate limits, and acknowledgement workflow. Such notifications must not include the original body, original attachments, or sensitive recipient details by default. Define who may see failure evidence and whether Notifications or another optional provider owns this effect. This is an open design question, not part of the current recipient-row implementation.

Acceptance criteria

Document the agreed recipient/entry/group reachability and trigger semantics with examples involving multiple primaries and multiple nested fallback rows.
Provide an accessible hierarchy editor with add/edit/remove/reorder actions and clear primary/fallback/notify-only labels and conditions.
Freeze the exact hierarchy, purpose, content references, and trigger policy in the approved build; later editing cannot change an executing version.
Use durable per-recipient/per-edge execution state, idempotency, worker/recovery fences and append-only trigger/attempt evidence; accepted/uncertain effects cannot be blindly replayed.
Show partial outcomes and trigger reasons in review/reporting and permit separately authorized reconciliation where needed.
Validate cycles, depth/size limits, invalid/missing destinations, unavailable optional modules, notification privacy, and review/approval boundaries on the server.
Cover safe failure, partial acceptance, unknown outcomes, retries/recovery, nested/multiple branches, disabled providers and notify-only payload exclusion with tests.
Update bilingual user/admin documentation, import/export/schema compatibility, and migration behavior without rewriting historical delivery evidence.

Related context

Existing entry-wide hybrid routing in #81 and #90 is historical implementation context, not the target fallback model. Coordinate print-related fallbacks with the separate print-campaign design issue.

Related design issue: #105

## Problem and intended model A Campaign entry is a content/data/attachment unit and may have multiple primary recipients. Each recipient has its own stable identity, name, distribution channel, and channel-specific destination. The campaign channel standard is only a preselection when adding a recipient, never a policy that reroutes existing recipients. Design fallback as subordinate recipient rows: “if this recipient/entry is not reached, send to these recipient rows.” A fallback row has the same name/channel/destination structure and may itself have multiple subordinate fallbacks. Keep normal primary recipients separate from conditional fallbacks. Do not implement fallback as a flat entry-wide channel-policy selector. The current implementation scope is primary recipient rows with Email/Postbox channels only. This issue captures all fallback work; fallback controls and execution stay disabled until its design and acceptance criteria are agreed. ## Decisions to resolve - Does a trigger belong to one recipient, an entry, or an explicitly defined group? For multiple primary recipients, define “entry reached” (any/all/quorum), partial success, and whether multiple fallback children are all attempted or alternatives in order. - Define eligible failure states and timing: confirmed rejection before acceptance, permanent failure, retry exhaustion, timeout, delivery receipt, or unread status. SMTP/Postbox acceptance, actual delivery, and human reading must be distinguished. Never treat an accepted or outcome-unknown effect as an automatic safe trigger for resending the content. - Decide whether the UI is a strict tree or permits references to reusable recipient rows. Prevent cycles, impose bounded depth/branching, preserve stable identities and authored order, and specify deletion/move/duplicate behavior. - Define content and attachment behavior for fallback recipients, including classification, authorization, recipient-specific rendering, review/approval, and cross-channel compatibility. ## Failure-only notification action A subordinate row may mean “notify me that something went wrong” rather than “deliver the original message to me.” Model this as a distinct action/purpose; do not infer it from the destination or channel. Decide the notification template, minimal diagnostic fields, aggregation/rate limits, and acknowledgement workflow. Such notifications must not include the original body, original attachments, or sensitive recipient details by default. Define who may see failure evidence and whether Notifications or another optional provider owns this effect. This is an open design question, not part of the current recipient-row implementation. ## Acceptance criteria - [ ] Document the agreed recipient/entry/group reachability and trigger semantics with examples involving multiple primaries and multiple nested fallback rows. - [ ] Provide an accessible hierarchy editor with add/edit/remove/reorder actions and clear primary/fallback/notify-only labels and conditions. - [ ] Freeze the exact hierarchy, purpose, content references, and trigger policy in the approved build; later editing cannot change an executing version. - [ ] Use durable per-recipient/per-edge execution state, idempotency, worker/recovery fences and append-only trigger/attempt evidence; accepted/uncertain effects cannot be blindly replayed. - [ ] Show partial outcomes and trigger reasons in review/reporting and permit separately authorized reconciliation where needed. - [ ] Validate cycles, depth/size limits, invalid/missing destinations, unavailable optional modules, notification privacy, and review/approval boundaries on the server. - [ ] Cover safe failure, partial acceptance, unknown outcomes, retries/recovery, nested/multiple branches, disabled providers and notify-only payload exclusion with tests. - [ ] Update bilingual user/admin documentation, import/export/schema compatibility, and migration behavior without rewriting historical delivery evidence. ## Related context Existing entry-wide hybrid routing in #81 and #90 is historical implementation context, not the target fallback model. Coordinate print-related fallbacks with the separate print-campaign design issue. Related design issue: https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/105

zemion added the

status

triage

module/campaign codex/needs-human

type

feature

area/api labels 2026-10-13 13:11:30 +02:00

zemion referenced this issue

2026-10-13 13:29:48 +02:00

[Feature] Design print campaigns with governed templates and file incorporation #105

Sign in to join this conversation.