REQ-20260625-COMP: Bulk Import as a Distinct, Admin-Owned Onboarding Workflow

Date: 2026-06-25 Requestor: the implementation partner (CTN / BDI) Priority: High Status: Under Review

Request Summary

The current bulk upload of Onboarding Requests is internally just the manual (self-service) intake path run per row. This must be split into its own workflow: bulk rows must survive validation failure (persisted for admin repair), provision a Keycloak account without emailing the applicant yet, be edited by an admin rather than the requesting entity, be classified by an explicit source, be separable per upload, and later be deduplicated/grouped in the admin stage.

Business Context

Business Driver

The association admin onboards many participants from a spreadsheet namens de aanvrager. The demo-era implementation (reuse the anonymous intake path) cannot support the real operational flow: bad rows vanish, applicants get emailed prematurely, and the applicant — not the admin — would own correction. The admin needs a controlled, auditable batch workflow they drive end-to-end.

Stakeholders Affected

• Primary: association admins running bulk onboarding.
• Secondary: prospective participants (applicants) whose accounts are pre-provisioned and who are invited on the admin’s schedule; the consortium (potential four-eyes rule).

Business Impact

• If Implemented: a usable bulk onboarding channel — failed rows are fixable, first contact is deliberate, uploads are traceable, duplicates are surfaced.
• If Not Implemented: bulk import stays a demo wrapper — lost rows, premature mails, wrong ownership of correction.

Technical Requirements

Functional Requirements

1. Every Onboarding Request carries an explicit source of SELF_SERVICE or BULK_IMPORT.
2. A bulk row that fails mapping/validation is persisted (not dropped), flagged incomplete, and repairable by an admin; only whole-file failures hard-fail the upload.
3. A bulk row provisions the applicant’s Keycloak account but does not send the set-password mail at creation.
4. An admin can later send that mail as an idempotent action, only once the row is complete; the event is recorded.
5. Bulk rows are editable by an admin (any admin), not by the requesting entity.
6. A request cannot be approved until it is complete (“validate before accept”).
7. Multiple uploads are separable.
8. Duplicates are detectable; before enrichment “duplicate” means same Identifier URI; the admin panel groups them (full grouping = COMP-19).

Non-Functional Requirements

• Security: import and invitation are admin-gated; the account↔request link stays consistent (no email change after invitation in MVP).
• Reliability: per-row independence (one bad row cannot abort the batch).
• Maintainability: must not erode the pure-flat onboarding lifecycle core (ADR-00012) or its duplicate-guard reuse.

Integration Requirements

• Keycloak account provisioning (ADR-00013) with deferred set-password mail.
• The TDR-0003 scheme→country / court-code derivation for identifier repair.

Current State Analysis

Existing Capabilities

• BulkImportService parses .xlsx and loops rows through OnboardingRequestService.save(req, adminSub) (TDR-0003), which validates-or-rejects, provisions the account and sends the set-password mail.
• Failed rows are returned transiently in ImportResultResp.failed[] and lost.
• OnboardingRequest.identifierUri is nullable = false; the lifecycle is a pure flat edge table whose openStates() also scopes the duplicate guard.

Gaps Identified

• No persistence of failed rows; no admin repair path.
• No way to provision without emailing; no separate invitation action.
• No source classification; no per-upload identity; no completeness gate on approval.

Impact on Current Architecture

• A nullable identifierUri; new source / batchId / invitedAt / validity columns; a distinct bulk create path; admin-scoped editing rules; an approval guard.

Proposed Approach

See ADR-00019 for the decided design (Source axis + orthogonal Validity, distinct create path, deferred Invitation, admin-owned repair, batchId separability).

Success Criteria

Acceptance Criteria

• A failed bulk row is persisted, visibly incomplete, and repairable by an admin.
• Bulk creation provisions the account but sends no mail until the admin invites.
• Invitation is admin-only, idempotent, allowed only when complete, and recorded.
• An incomplete request cannot be approved.
• Each request exposes its source; bulk rows are admin-editable, self-service rows are not.
• Uploads are distinguishable and groupable; same-Identifier-URI duplicates surface grouped.

Related Documents

• ADR-00019 — the decision.
• TDR-0003 — prior bulk import.
• COMP-24, COMP-119, COMP-19 (Jira).

Status History

Date	Status	Reviewer	Notes
2026-06-25	Submitted	the implementation partner	Captured from the grill-with-docs design session.
2026-06-25	Under Review	the implementation partner	Drives ADR-00019 (Proposed).

---

Requests help capture and track stakeholder requirements in a structured way