Guided ingestion wizard

Guided ingestion wizard

This guide documents the guided ingestion wizard (/ingestion/wizard, dashboard). It records the first-release scope, the preflight contract, and the rollout decision for the direct advanced flow. The wizard is a guided wrapper over the existing ingestion backbone — it is not a second ingestion implementation, does not enqueue work on its own, and cannot bypass authorization, idempotency, provider limits, or queue backpressure.

First-release scope (recorded decisions)

• Source types: ORCID researcher ingestion only, the platform’s supported queue-based ingestion source. DOI import stays on the direct import flow and is not wizard-covered in this release. Source expansion is a later decision after pilot evidence (TKT-004).
• Run types:
  • Run once now — composes the existing queueIngestion contract (member-level authority, the same membership rule: only external/outside memberships are blocked).
  • Recurring sync — composes the ING-001 saveOrcidSyncSchedule contract (daily/weekly, operator-only: workspace owner/admin or superadmin, cesam/internal memberships only).
• Direct advanced flow decision: the existing direct Import page remains available as the advanced-user path. The wizard ships as an additional guided entrypoint alongside it (source packet deployment plan step 2). Promoting the wizard to the default entrypoint is deferred until pilot evidence exists; rollback keeps the direct flow as default.
• Preflight is read-only. The preflight server function never mutates; preview never enqueues.

How the wizard composes existing contracts

Researcher input → run type → read-only preflight → launch (existing contracts) → outcome reporting

• Preflight (preflightOrcidIngestion) validates ORCID formats, dedupes input, and reads the same state the launch paths rely on: workspace membership (person_entity_memberships), the active job behind the ORCID-scoped partial unique index on ingestion_jobs, and any ING-001 schedule. It mirrors each launch path’s authorization before reading: one-time runs need any workspace member; recurring sync needs the ING-001 operator rule.
• Launch always goes through the existing server functions — queueIngestion for one-time runs (idempotent through INSERT OR IGNORE plus the active-job unique index) and saveOrcidSyncSchedule for recurring sync. The wizard introduces no write path.
• Workspace scope is server-resolved from the authenticated session. A client-supplied workspace is never accepted.

Preflight honesty

The preflight distinguishes what is known from what is not:

• Known before launch: format validity, membership eligibility, duplicate suppression (an active job already exists — the request would be skipped), and overlapping schedules.
• Known after launch only: how many publications ORCID returns, enrichment outcomes, and queue wait time. The wizard never predicts these.

Outcome reporting

The wizard reports one shared outcome vocabulary with recovery guidance and never reports false success:

Outcome	Meaning	Recovery guidance
Queued	Accepted; waiting in the ingestion queue or for the scheduler.	No action needed yet.
Running	Job processing in progress.	Outcomes update as work finishes.
Delayed	Processing age exceeds one hour, or the schedule is delayed.	Check Activity before retrying; do not relaunch duplicates.
Skipped	Membership not eligible, an identical active job exists, or the schedule is paused.	Not a failure; explanation shown.
Failed	Terminal failure with the recorded error.	Read the detail; retry or contact an operator.
Completed	Terminal success (publications found, or a scheduled success).	Verify in the publications list.

Anything not proven terminal stays pending. A launch whose queue accepts fewer jobs than requested reports the remainder as skipped (duplicate suppression), not as success.

Testing and evidence

• Schemas: packages/schemas/src/ingestion-wizard-schemas.test.ts
• Preflight model and server function: apps/dashboard/src/server/functions/ingestion-wizard/preflight.test.ts and index.test.ts (authorization, dedupe, malformed input, store-unavailable handling)
• Client model, outcomes, and component behavior (state transitions, permissions, duplicate submission, failures, accessibility): apps/dashboard/src/features/ingestion-wizard/*.test.ts*

Rollout and rollback

1. Deploy the dashboard. The wizard route is gated by the import workspace module, exactly like the Import page.
2. The wizard is an additional entrypoint; the direct Import flow remains the default. Pilot with internal admins and compare completion and error rates before considering promotion.
3. Rollback: hide the wizard link and/or the route without touching the ingestion contracts; the direct flow is unaffected. No migration is involved — the wizard adds no schema.