Bulk import

Problem Context

• Users have many records in a spreadsheet or exported system file and cannot reasonably enter each record manually.
• The target system has required fields, typed values, enums, relationships, unique identifiers, ownership rules, and side effects such as notifications or permission changes.
• Column names, date formats, encoding, blank cells, duplicate identifiers, invalid enum values, and missing required values commonly differ between source files and target schema.
• Some imports create records, some update records, and some merge into existing data with different behavior for blank values and duplicates.
• A failed or partially successful import needs a recovery path, because users should not have to rediscover every bad row by trial and error.

Selection Rules

• Choose bulk import when one uploaded file represents many structured records that must be parsed into fields.
• Use ordinary file upload when the uploaded file is evidence or content to store, not data to split into rows and columns.
• Use drag-and-drop upload only as an optional file-selection enhancement inside the import workflow, not as the whole import experience.
• Use multi-step form or complete complex form when a user is creating one record with guided human judgment rather than importing many prepared rows.
• Offer a template, sample file, or clear format rules before upload when users can prepare the file in advance.
• Require mapping review when column headers can differ from target field names or when unmapped columns would be ignored.
• Validate before commit when errors could affect many records, especially required values, type formats, duplicate identifiers, relationships, permissions, and destructive updates.
• Let users choose create-only, update-only, create-and-update, merge, or skip behavior when the same file can affect existing records.
• Support valid-row-only import only when users can see exactly which rows will import, which will be excluded, and how to fix excluded rows.
• Require final confirmation when the import sends notifications, changes permissions, overwrites data, creates many records, or cannot be fully undone.

Required States

• Pre-import requirements state with template, accepted file types, encoding, row limit, column limit, required fields, and side effects.
• File selected state showing filename, size, detected sheet, row count, column count, and parsed headers.
• Mapping state with suggested mappings, required-field gaps, unmapped columns, ignored columns, and sample values.
• Mapping error state for duplicate target fields, missing required mappings, unsupported fields, or ambiguous headers.
• Validation running state with progress and cancel guidance before data commit.
• Validation results state with valid row count, invalid row count, warning count, duplicate count, and row-level details.
• Repair state with filters for errors, warnings, duplicates, and unmapped columns plus links to fix or export issues.
• Duplicate review state with match key, create/update/skip choice, and overwrite behavior for blank values.
• Confirmation state summarizing new, updated, skipped, invalid, warning, notification, and irreversible-change counts.
• Import running state with progress, queued status, safe navigation guidance, and import history link.
• Import complete state with success count, skipped count, failed count, warnings, download report, and next actions.
• Import failed or partially completed state with retry guidance and preserved mapping choices.

Interaction Contract

• Uploading parses the file into headers, sample rows, counts, and metadata before any records are created or updated.
• Auto-mapping is a suggestion, not a commit; users can change, clear, ignore, reset, and review mappings before validation.
• A required target field cannot be left unmapped unless the import mode or existing data makes it explicitly safe.
• Each target field can receive at most one source column unless the product intentionally supports a combine-fields operation.
• Validation reports row number, source column, target field, offending value, reason, severity, and recovery action.
• Create/update/merge mode and duplicate matching are visible before final confirmation, including the identifier used to match existing records.
• Blank-value overwrite behavior is explicit for updates and merges.
• Starting the import after confirmation creates an auditable job with progress and results rather than leaving users on an indefinite spinner.
• Users can export invalid rows or an error report that preserves row identifiers and current mappings.
• Cancelling before final confirmation does not create or update records; cancelling after commit follows the product's documented job-cancel or rollback policy.

Implementation Checklist

• Define accepted file types, encoding, max size, max rows, max columns, supported sheets, required fields, optional fields, ignored fields, relationship fields, duplicate keys, import modes, blank-value behavior, and notification side effects.
• Provide templates or sample files that match required headers and data formats.
• Parse files server-side or with a trusted parser and show detected headers, row count, column count, sample rows, and parse warnings before mapping.
• Build a mapping table that supports auto-map, manual map, ignore, reset, required-field indicators, one-source-to-one-target checks, sample values, and unmapped-column review.
• Validate required values, data types, dates, numbers, enums, relationships, duplicates, permissions, row length, unsupported fields, blank overwrites, and file-level limits before commit.
• Provide repair views that filter invalid rows, warnings, duplicates, and unmapped columns, with exportable errors and preserved mapping decisions.
• Show final confirmation for create/update/merge/skipped counts, notifications, irreversible changes, and valid-row-only behavior.
• Run the import as a tracked job with progress, completion, partial failure, retry, import history, and downloadable result report.
• Test small files, max-limit files, empty files, duplicate headers, missing required mappings, invalid dates, unknown enum values, duplicate existing records, blank update cells, network interruption, refresh/back, and permission-limited users.

Common Generated-UI Mistakes

• Treating a spreadsheet import like a generic file attachment with no mapping or row validation.
• Auto-starting the import immediately after upload.
• Hiding duplicate matching, create/update mode, blank overwrite behavior, or notification side effects until after commit.
• Showing only a generic invalid file error instead of row numbers, column names, and fixable reasons.
• Importing valid rows and skipping invalid ones without telling users exactly which rows were excluded.
• Letting similar headers auto-map into destructive target fields without a preview.
• Forcing users to re-upload and remap from scratch after every recoverable validation error.

Critique Questions

• What records can this import create, update, merge, skip, notify, or overwrite?
• Can users see required fields, detected headers, sample values, unmapped columns, and duplicate mappings before validation?
• What row-level errors, warnings, duplicates, and blank-overwrite risks can the user repair before committing?
• Does the final confirmation explain counts and side effects in terms the importing user can verify?
• What report or export helps users fix failed rows without rebuilding a whole file?
• Can the team audit who imported what file, with which mapping, at what time, and with what result?