docs: make distribution lists the AdreMa capability owner
This commit is contained in:
@@ -0,0 +1,445 @@
|
||||
# AdreMa Capability Assessment And Distribution-List Roadmap
|
||||
|
||||
## Purpose
|
||||
|
||||
This document records a behavior-level assessment of the historical AdreMa
|
||||
application supplied in `/mnt/DATA/tmp.tar`. The goal is not to reproduce its
|
||||
implementation or UI. The goal is to preserve the useful administrative
|
||||
capabilities while replacing hard-coded queries and output paths with
|
||||
governed, reusable GovOPlaN contracts.
|
||||
|
||||
The archive was inspected as untrusted historical material. No archived code
|
||||
was executed. Generated documents and record-level output were excluded from
|
||||
the analysis.
|
||||
|
||||
## Evidence And Handling
|
||||
|
||||
- Archive SHA-256:
|
||||
`328edbaf05df084f9c63cc3b9b36f7c5ae0c639942be4b7ad830efc0905a311b`
|
||||
- Compressed size: about 1.49 GB
|
||||
- Inventory: 8,966 files and 190 directories
|
||||
- Uncompressed payload: about 1.79 GB
|
||||
- The AdreMa selection UI contains 258 distinct segment variables, 265 query
|
||||
cases, 13 sort definitions, seven action definitions, and 24
|
||||
department-specific forms.
|
||||
- The adjacent configurable list/report layer contains 47 ETI definitions.
|
||||
- The wider print-server archive contains 127 SQL files, 181 XSLT files, and 82
|
||||
Python workflow sources.
|
||||
|
||||
The archive contains generated person-level documents and embedded
|
||||
credentials. It must not be committed, copied into test fixtures, or treated as
|
||||
safe sample data. Any credential that could still be valid must be rotated.
|
||||
Future fixtures derived from this assessment must be synthetic.
|
||||
|
||||
## What AdreMa Actually Is
|
||||
|
||||
AdreMa is not primarily a master address database. It is a role-specific
|
||||
audience selection and output application over authoritative institutional
|
||||
databases.
|
||||
|
||||
Its main flow is:
|
||||
|
||||
1. Authenticate against a directory.
|
||||
2. Show a menu of saved recipient selections permitted for the current user or
|
||||
department.
|
||||
3. Run a fixed SQL selection against organization, person, employment,
|
||||
function, student, geography, and address data.
|
||||
4. Apply a selected sort order and address variant.
|
||||
5. Produce a table, spreadsheet, label preview, printable label file, or BCC
|
||||
mail draft.
|
||||
6. Record a basic process log and recipient count.
|
||||
|
||||
The broader print-server application adds SQL-to-XML extraction, XSLT
|
||||
transformation, HTML/Excel output, TeX/PDF generation, batch letters, PDF
|
||||
protection, and deployment-specific printer submission.
|
||||
|
||||
This means an AdreMa replacement should not be one large Addresses feature.
|
||||
Distribution Lists is the core user-facing domain for audience definitions,
|
||||
expansion, and reusable `Verteiler`. It composes capabilities from Addresses,
|
||||
Organizations/IDM, Datasources, Connectors, and Dataflow, then supplies frozen
|
||||
results to Templates, Campaign, Files, Audit, Policy, Reporting, and Workflow.
|
||||
No separate Print module is required: Templates owns printable output and an
|
||||
optional printer endpoint is an export destination, not a new party or audience
|
||||
domain.
|
||||
|
||||
## Observed Functional Model
|
||||
|
||||
### Sources And Identities
|
||||
|
||||
The application reads live authoritative data rather than maintaining a
|
||||
separate copy. Its selections use:
|
||||
|
||||
- people and institutional units
|
||||
- functions and role assignments
|
||||
- employment and student state
|
||||
- effective dates and exclusions
|
||||
- internal and external organizations
|
||||
- geography, country, and postal-code ranges
|
||||
- source-specific person, registration, and unit identifiers
|
||||
|
||||
Access to selections is hard-coded by user and department. Administrative
|
||||
users receive the union of those menus.
|
||||
|
||||
### Contact And Address Semantics
|
||||
|
||||
Observed recipient fields include:
|
||||
|
||||
- display name, given name, family name, title, and formal salutation
|
||||
- organization/unit and function context
|
||||
- phone, fax, email, and URL
|
||||
- `care of`/`for the attention of` lines
|
||||
- street, postal code, locality, country, and internal mail routing
|
||||
- person, registration, and organizational-unit identifiers
|
||||
- address purpose variants such as private, semester, home, business, service,
|
||||
and correspondence address
|
||||
- effective employment or membership data used to decide eligibility
|
||||
|
||||
The legacy system also allows a requested number of labels for an individual
|
||||
recipient. That quantity belongs to an output job, not to the canonical address
|
||||
record.
|
||||
|
||||
### Recipient Selection
|
||||
|
||||
Selections cover several distinct patterns:
|
||||
|
||||
- static categories of institutional units
|
||||
- people assigned to a function or organizational level
|
||||
- current-state selections with effective-date rules and exclusions
|
||||
- geographic and demographic selections
|
||||
- combinations and unions of predefined audiences
|
||||
- explicit person or unit lookup by source identifier
|
||||
- department-specific variants of a shared audience
|
||||
- user-selected additional predicates and sort orders in the adjacent ETI
|
||||
report layer
|
||||
|
||||
The important reusable abstraction is therefore a versioned, parameterized,
|
||||
permissioned segment definition. The 265 query branches must not become 265
|
||||
new backend endpoints.
|
||||
|
||||
### Output
|
||||
|
||||
The directly observed output modes are:
|
||||
|
||||
- on-screen recipient table with contact and postal fields
|
||||
- spreadsheet export
|
||||
- plain-text label preview
|
||||
- generated label file
|
||||
- emailed label file
|
||||
- printable label output
|
||||
- BCC mail draft
|
||||
|
||||
The adjacent print-server flows additionally produce:
|
||||
|
||||
- formatted lists and grouped reports
|
||||
- personalized letters and notices
|
||||
- HTML, spreadsheet-compatible, TeX, PostScript, and PDF artifacts
|
||||
- printer-specific layouts and deployment-specific print submission
|
||||
- password-protected output and combined document bundles
|
||||
|
||||
### Configuration
|
||||
|
||||
The ETI layer is an early configuration-driven report system. A definition can
|
||||
declare:
|
||||
|
||||
- a SQL source
|
||||
- named optional filter predicates
|
||||
- named sort orders
|
||||
- list and label layouts
|
||||
- page, line, margin, repetition, and format settings
|
||||
- screen or spreadsheet output
|
||||
|
||||
That is conceptually close to a GovOPlaN combination of a Dataflow template,
|
||||
typed output template, and Report/Campaign run configuration.
|
||||
|
||||
## Legacy Limitations We Should Not Reproduce
|
||||
|
||||
- users, departments, permissions, query variants, and output paths are
|
||||
hard-coded
|
||||
- credentials are embedded in source files
|
||||
- request values are interpolated into SQL and shell commands
|
||||
- authentication, authorization, session transfer, and application routing are
|
||||
coupled
|
||||
- selection names do not carry version, owner, purpose, legal basis, or
|
||||
provenance
|
||||
- past output cannot be reproduced reliably after source data or query code
|
||||
changes
|
||||
- exclusions and exceptional recipients are hidden inside SQL
|
||||
- there is no first-class consent, suppression, address-quality, or duplicate
|
||||
resolution model
|
||||
- mail generation relies on client-side `mailto` BCC links
|
||||
- output submission has weak status and evidence handling
|
||||
- temporary files and generated artifacts are not governed records
|
||||
- the UI does not explain why a recipient was included, excluded, or
|
||||
inaccessible
|
||||
|
||||
## Current GovOPlaN Coverage
|
||||
|
||||
| Capability | Current state | Primary owner |
|
||||
| --- | --- | --- |
|
||||
| Scoped address books and contacts | Implemented | Addresses |
|
||||
| Multiple email, phone, and postal contact points | Implemented | Addresses |
|
||||
| Static address lists | Implemented | Addresses |
|
||||
| vCard import/export and CardDAV sync | Implemented | Addresses |
|
||||
| Read-only lookup and immutable email-recipient snapshots | Implemented | Addresses |
|
||||
| Source provenance and sync conflicts | Implemented | Addresses |
|
||||
| Organization units and function definitions | Implemented | Organizations |
|
||||
| Effective-dated identity-to-function assignments | Implemented first slice | IDM |
|
||||
| Governed source catalogue, snapshots, and frozen states | Implemented first slice | Datasources |
|
||||
| Connector-backed tabular acquisition and preview | Implemented first slice | Connectors |
|
||||
| Graphical/SQL transformations, joins, filters, expressions, quality, and reconciliation | Implemented broad first slice | Dataflow |
|
||||
| Campaign snapshots, review, digital delivery, and evidence | Implemented first channel | Campaign |
|
||||
| Typed template library and document rendering | Scaffold/issue only | Templates |
|
||||
| BI reports and spreadsheet-grade exports | Scaffold/issue only | Reporting |
|
||||
| Mixed operational distribution lists and governed segments | Contract/implementation issues only | Distribution Lists |
|
||||
| Contact-point consent, suppression, and preferences | Open issue | Addresses/Policy |
|
||||
| Deduplication, merge, quality, and complete history | Open issue | Addresses |
|
||||
| Channel-neutral expansion and frozen postal targets | Missing | Distribution Lists/Addresses |
|
||||
| Printable label, envelope, and letter output | Open issue | Templates |
|
||||
| End-to-end guided AdreMa workflow | Missing | Workflow plus consuming modules |
|
||||
|
||||
## Target Architecture
|
||||
|
||||
### 1. Identities, Groups, Functions, And Contact Points
|
||||
|
||||
The authoritative subject model is shared deliberately:
|
||||
|
||||
- Organizations owns tenant-local units, structures, and function definitions.
|
||||
- IDM owns identities' effective-dated assignments to those functions and the
|
||||
typed group/membership relationships used as audience sources.
|
||||
- Addresses owns contact records and contact points, including formal
|
||||
addressing fields, postal purposes, validity, preference, and provenance.
|
||||
- Distribution Lists stores stable provider references and expansion evidence;
|
||||
it does not copy any provider's master records.
|
||||
|
||||
An IDM identity status is a lifecycle indicator such as active, suspended, or
|
||||
retired. A business status used for selection is represented by a typed group,
|
||||
function, or effective-dated relationship. The two meanings must not share one
|
||||
field.
|
||||
|
||||
Addresses still needs postal fields for care-of/addressee lines, PO boxes,
|
||||
country codes, internal-mail routes, and delivery instructions. It may preserve
|
||||
vCard `KIND`/`RELATED` data for round-trip compatibility, but it must not become
|
||||
a parallel party or organizational-relationship authority.
|
||||
|
||||
Every provider remains optional. A deployment without IDM can still use local
|
||||
address contacts and raw targets; a deployment without Addresses can still
|
||||
expand identities, groups, functions, and provider-native targets.
|
||||
|
||||
### 2. Governed Distribution Lists And Segments
|
||||
|
||||
Distribution Lists owns reusable audience definitions and their user
|
||||
experience. Dataflow evaluates complex tabular predicates, while Datasources
|
||||
and Connectors provide governed inputs. Addresses may expose simple contact
|
||||
search/filter capabilities, but a reusable segment is a Distribution List
|
||||
definition.
|
||||
|
||||
A segment needs:
|
||||
|
||||
- immutable definition revisions
|
||||
- system, tenant, group, and user scope
|
||||
- complete-flow versus reusable-template semantics
|
||||
- parameters with types, defaults, constraints, and permitted overrides
|
||||
- explicit include, exclude, and manual-override sets
|
||||
- source fingerprints and freshness requirements
|
||||
- preview, count, sample, and "why included/excluded" diagnostics
|
||||
- schedule/event refresh policy where materialization is wanted
|
||||
- owner, purpose, legal basis, retention, and policy provenance
|
||||
- materialized/frozen recipient snapshots for reproducible use
|
||||
|
||||
Simple tag/contact predicates may be delegated to Addresses. Cross-source joins
|
||||
and complex expressions compile to a pinned Dataflow revision rather than
|
||||
creating a second query engine in Distribution Lists.
|
||||
|
||||
### 3. Expansion And Channel Resolution
|
||||
|
||||
Distribution Lists orchestrates a versioned, channel-neutral expansion
|
||||
contract. Provider capabilities contribute identities, groups, function
|
||||
incumbents, contact-point candidates, or tabular rows. The expansion can
|
||||
resolve:
|
||||
|
||||
- email targets
|
||||
- postal targets
|
||||
- internal-mail targets
|
||||
- digital portal targets when Campaign has such a delivery provider
|
||||
- unresolved or blocked targets with stable reason codes
|
||||
|
||||
Resolution must consider:
|
||||
|
||||
- requested channel and communication purpose
|
||||
- effective date
|
||||
- preferred address/contact point
|
||||
- explicit address-purpose selection and fallback rules
|
||||
- locale and international postal formatting
|
||||
- channel opt-in/preference, consent, legal basis, suppression, and Policy
|
||||
decisions
|
||||
- duplicate targets and household/organization grouping
|
||||
- source revision, selected contact-point ID, and complete provenance
|
||||
|
||||
Addresses owns contact-point preference/consent facts; Policy decides what is
|
||||
permitted and explains provenance; Distribution Lists records the applied
|
||||
decision in its expansion result. Campaign then applies explicit hybrid-channel
|
||||
routing and freezes the result. A future Portal self-service surface may edit
|
||||
permitted preferences through these same contracts and receive Campaign output,
|
||||
but it is not required for the core AdreMa implementation.
|
||||
|
||||
Consumers never retain only a live pointer to a list or segment.
|
||||
|
||||
### 4. Static And Operational Lists
|
||||
|
||||
The existing split remains correct:
|
||||
|
||||
- Addresses owns address books and simple classical groupings of contacts or
|
||||
contact points.
|
||||
- Distribution Lists owns static and dynamic operational `Verteiler` containing
|
||||
address records, IDM identities and typed groups, organization units,
|
||||
functions/effective incumbents, raw targets, Dataflow-backed rows, and nested
|
||||
distribution lists.
|
||||
- Workflow/Tasks owns an `Umlauf` with ordering, state, deadlines, escalation,
|
||||
and decisions.
|
||||
|
||||
Distribution-list entries need stable IDs. A consumer stores an immutable
|
||||
expansion snapshot. Consumer-specific enrichment belongs to that consumer;
|
||||
reusable derived lists are separate, revision-pinned definitions.
|
||||
|
||||
### 5. Templates, Artifacts, And Delivery
|
||||
|
||||
Templates should provide typed render contracts for:
|
||||
|
||||
- labels and label sheets
|
||||
- envelopes
|
||||
- form and serial letters
|
||||
- email and other digital messages
|
||||
- list/report layouts
|
||||
|
||||
Templates declare required fields and output capabilities. Rendering produces a
|
||||
managed Files artifact with template revision, input snapshot hash, renderer
|
||||
version, page/count summary, and diagnostics.
|
||||
|
||||
Campaign should orchestrate postal batches with the same lifecycle as other
|
||||
delivery channels: freeze recipients, validate required fields, review
|
||||
exceptions, render, approve, deliver or export, reconcile outcomes, and retain
|
||||
evidence.
|
||||
|
||||
Templates owns printable content and layout. Files persists approved artifacts,
|
||||
Campaign owns batch review and channel routing, and Audit records the evidence.
|
||||
Downloading or handing a generated PDF to the operating system is a complete
|
||||
supported path. If a deployment later needs an IPP/CUPS or managed print-server
|
||||
destination, Connectors can expose it as a governed artifact export provider;
|
||||
that does not require a separate Print module.
|
||||
|
||||
Hybrid campaigns may choose email, printable postal output, or a portal-capable
|
||||
delivery target per recipient. Opt-in is an input to the Policy decision, never
|
||||
an implicit instruction to duplicate delivery across channels. Campaign must
|
||||
freeze the chosen route, fallback rule, and reason for every recipient.
|
||||
|
||||
### 6. Governance And Quality
|
||||
|
||||
Parity is not sufficient without:
|
||||
|
||||
- purpose- and channel-specific consent/legal-basis records
|
||||
- do-not-contact and returned/invalid-address suppression
|
||||
- normalization and validation with original-value preservation
|
||||
- duplicate candidates, survivorship rules, manual merge/split, and undo
|
||||
evidence
|
||||
- field-level provenance and source-of-truth precedence
|
||||
- stale-source and stale-segment warnings
|
||||
- field/row/export policy decisions with user-readable explanations
|
||||
- complete audit events for read, export, resolution, merge, rendering, and
|
||||
delivery
|
||||
- retention, legal hold, and deletion behavior for source records and frozen
|
||||
output evidence
|
||||
|
||||
### 7. Guided User Experience
|
||||
|
||||
The default journey should be:
|
||||
|
||||
1. Choose or create a distribution list/segment.
|
||||
2. Preview the authorized audience and inspect included, excluded, duplicate,
|
||||
invalid, and suppressed counts.
|
||||
3. Select channel, address purpose/fallback, sort, and grouping.
|
||||
4. Freeze a recipient snapshot.
|
||||
5. Select a compatible template/output format.
|
||||
6. Review individual exceptions and approve the run.
|
||||
7. Export or deliver through available capabilities.
|
||||
8. inspect progress, outcomes, returned items, and evidence.
|
||||
|
||||
Workflow may package this as a reusable guided process and activate a focused
|
||||
View. Every underlying resource must remain independently accessible and
|
||||
permission-checked.
|
||||
|
||||
## Representative Golden Flow
|
||||
|
||||
Before migrating any historical selection, build a synthetic AdreMa fixture
|
||||
covering:
|
||||
|
||||
- people, organizations, units, functions, and effective-dated assignments
|
||||
- multiple postal-purpose variants and internal mail
|
||||
- a function-based segment
|
||||
- an organization-unit segment
|
||||
- a geography-based segment
|
||||
- a union of segments
|
||||
- explicit inclusion and exclusion
|
||||
- duplicate and suppressed recipients
|
||||
- deterministic sorting and address fallback
|
||||
- frozen postal and email snapshots
|
||||
- label, spreadsheet, and letter output expectations
|
||||
|
||||
The fixture should assert exact recipient IDs, selected contact-point IDs,
|
||||
ordering, exclusion reasons, source fingerprints, and output hashes. It must
|
||||
contain no archived record-level data.
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
Do not translate the legacy source one query branch at a time into application
|
||||
code.
|
||||
|
||||
1. Inventory each still-relevant named selection with owner, purpose, legal
|
||||
basis, source systems, parameters, output type, and expected use frequency.
|
||||
2. Retire obsolete and duplicate selections before migration.
|
||||
3. Map source tables to governed Connector/Datasource definitions.
|
||||
4. Convert reusable predicates into Distribution List definitions backed by
|
||||
pinned Dataflow templates or provider-native predicates.
|
||||
5. Compare the new result against an authorized legacy run using counts and
|
||||
pseudonymized stable keys.
|
||||
6. Approve and version the new segment.
|
||||
7. Migrate output layouts into typed Templates.
|
||||
8. Retain a migration report and decommission the corresponding legacy path.
|
||||
|
||||
## Recommended Delivery Order
|
||||
|
||||
### Priority 1: Functional Parity Foundation
|
||||
|
||||
1. Distribution-list DTOs, versioned definitions, expansion, and snapshot
|
||||
contracts.
|
||||
2. Typed IDM groups and effective-dated identity/function relationships, with
|
||||
identity lifecycle status kept separate.
|
||||
3. Channel-neutral contact-point candidates and preference/consent facts from
|
||||
Addresses, evaluated through Policy.
|
||||
4. Dynamic governed segments through Dataflow, Datasources, and Connectors.
|
||||
5. Synthetic AdreMa golden-flow fixture.
|
||||
6. Typed label, envelope, and letter templates with managed artifacts.
|
||||
|
||||
### Priority 2: Operational Parity
|
||||
|
||||
1. Campaign hybrid-channel review, routing, and printable-output flow.
|
||||
2. Spreadsheet/report exports with exact frozen-snapshot evidence.
|
||||
3. Consent, suppression, preferences, deduplication, merge, and quality UI.
|
||||
4. CSV/XLSX and directory/database migration profiles.
|
||||
5. Distribution-list expansion and Campaign integration.
|
||||
|
||||
### Priority 3: Beyond AdreMa
|
||||
|
||||
1. Portal self-service for permitted channel opt-in and digital receipt.
|
||||
2. Returned-mail and correction workflows.
|
||||
3. Postal-provider/franking integration and delivery reconciliation.
|
||||
4. Scheduled/event-driven segment refresh and recurring campaigns.
|
||||
5. Address analytics, geocoding where policy permits, and quality trends.
|
||||
|
||||
## Completion Standard For The Umbrella Feature
|
||||
|
||||
The AdreMa umbrella is complete when a user can define or reuse a permissioned
|
||||
Distribution List, explain and freeze the exact recipients and chosen channels,
|
||||
create reviewed label/letter or digital outputs, export or deliver through
|
||||
installed modules, and later prove exactly which source data, rules, template,
|
||||
actor, and delivery outcome were involved. The same flow must degrade cleanly
|
||||
for every optional provider or consumer module combination.
|
||||
Reference in New Issue
Block a user