88 lines
2.9 KiB
Markdown
88 lines
2.9 KiB
Markdown
# Recipient Import Guide
|
|
|
|
Recipient import lets campaign authors turn spreadsheet-like source data into
|
|
campaign-local recipient entries. It is intentionally campaign-local:
|
|
reusable address books and Adrema-style address management belong in the
|
|
`govoplan-addresses` module.
|
|
|
|
## Supported Inputs
|
|
|
|
The current importer is designed for tabular data with a header row. CSV and
|
|
spreadsheet-derived tables should be normalized before import so the campaign UI
|
|
sees:
|
|
|
|
- column headers
|
|
- row values
|
|
- source filename and sheet name when available
|
|
- a stable ordered and unordered header fingerprint
|
|
|
|
Avoid importing production secrets or credentials as recipient fields. Recipient
|
|
custom fields may be used in templates and reports, so they should be treated as
|
|
campaign data.
|
|
|
|
## Mapping Fields
|
|
|
|
Common headers are detected automatically:
|
|
|
|
- `email`, `e_mail`, `mail`, `to`, `to_email`, `recipient`,
|
|
`recipient_email`
|
|
- `name`, `full_name`, `recipient_name`, `to_name`
|
|
- `id`, `entry_id`, `recipient_id`
|
|
|
|
Authors can map columns to address fields:
|
|
|
|
- `from`
|
|
- `to`
|
|
- `cc`
|
|
- `bcc`
|
|
- `reply_to`
|
|
|
|
Rows without a valid `to` address should remain visible with validation issues
|
|
instead of disappearing silently. Authors should be able to fix the source file,
|
|
adjust the mapping, or exclude the row before building the campaign.
|
|
|
|
## Mapping Profiles
|
|
|
|
Mapping profiles save a known column layout so repeated imports can reuse the
|
|
same mapping. The importer stores ordered and unordered header fingerprints so a
|
|
profile can distinguish exact column order from equivalent column sets.
|
|
|
|
Administrators should curate shared profiles only for stable recurring sources.
|
|
Campaign-local profiles are acceptable for one-off work and experiments.
|
|
|
|
## User Workflow
|
|
|
|
1. Open the campaign recipient/data import screen.
|
|
2. Upload or paste a tabular source.
|
|
3. Review detected headers and preview rows.
|
|
4. Pick or adjust a mapping profile.
|
|
5. Confirm validation issues, exclusions, and generated recipient ids.
|
|
6. Import into the campaign draft.
|
|
7. Build messages and review recipient-specific evidence before sending.
|
|
|
|
## Admin Workflow
|
|
|
|
Administrators should:
|
|
|
|
- define naming conventions for recurring mapping profiles
|
|
- verify that imported fields have a lawful processing basis for the campaign
|
|
- keep reusable address-directory ownership out of campaigns because
|
|
`govoplan-addresses` owns that domain
|
|
- use campaign reports and audit evidence to trace which source produced which
|
|
recipient entries
|
|
- remove obsolete shared profiles when an upstream source layout changes
|
|
|
|
## Evidence Expectations
|
|
|
|
The campaign should preserve enough evidence to explain a send:
|
|
|
|
- source filename and sheet name where available
|
|
- header fingerprints
|
|
- mapping profile id/name when used
|
|
- row number or source id
|
|
- validation status and exclusion reason
|
|
- final recipient addresses used for the built message
|
|
|
|
The evidence should be available in reports without requiring the original
|
|
source file to be reprocessed.
|