Lorixen.
EN

CSV Import in a Business Web App: Mapping, Errors, Duplicates

Short answer: A good CSV importer is a small product inside your app: it gives users a template, lets them map their columns to your fields, previews the result, flags errors row by row, decides clearly what happens with duplicates, and can be undone. Specify those behaviours up front, including how dates like 03/04/2026 are read in New Zealand, and you'll avoid the most common failure: a half-imported customer list nobody can untangle. Below is a blueprint you can paste into a brief.

Most businesses meet this feature on day one of a new system: moving 2,000 customers, 400 products or three years of job history out of spreadsheets. If the importer is weak, that first week turns into manual retyping. "Can import CSV" in a quote can mean anything from a bare upload button to a full workflow, so write down which one you need.

Blueprint: the importer spec

1. Before the upload

Downloadable template. A CSV with the exact column headers your app expects, one example row, and a short help page explaining each column (required or optional, format, allowed values).

Accepted formats. CSV at minimum. State whether semicolon or tab-separated files are accepted too; parsers can detect delimiters (Papa Parse, a common browser library, has a delimiter-guessing option), but explicit is better.

File size limit, stated on the screen, and what happens above it (split the file, or the import runs in the background and emails when done).

2. Reading the file

CSV looks simple and isn't. RFC 4180, the closest thing to a reference, is an informational document describing the format "most implementations" follow: one record per line, an optional header, and fields containing commas, line breaks or double quotes wrapped in double quotes, with inner quotes doubled. Real files from Excel, Google Sheets, accounting tools and old systems bend those rules.

Specify that the importer must:

  • Handle quoted fields with commas and line breaks (addresses are the usual culprit).
  • Read UTF-8, and deal sensibly with other encodings so names like Māori macrons (ā, ē, ō) and accented characters come through intact. Papa Parse, for example, accepts an encoding setting for local files that must be one the browser's FileReader supports.
  • Ignore empty trailing rows rather than reporting them as errors.
  • Trim stray spaces from headers and values.

In the browser, the File API lets the app read a file the user picks or drags in, without uploading it first, which makes instant previews possible.

3. Column mapping

Users' spreadsheets never match your template exactly. A mapping screen should:

  • List each column found in the file with a sample value.
  • Auto-match obvious ones ("Email", "E-mail", "email address" → Email).
  • Let the user pick the target field for the rest, or choose "Don't import".
  • Remember the mapping for next time, if imports will repeat.
  • Block the next step until required fields are mapped.

4. Formats that need rules

Write these into the spec explicitly, because developers outside New Zealand may assume otherwise:

Data Rule to specify
Dates Day/month/year by default (03/04/2026 = 3 April 2026); accept ISO 2026-04-03; flag ambiguous or impossible dates rather than guessing
Phone numbers Accept with or without +64, spaces and brackets; store in one consistent format
Money Strip "$" and thousands separators; treat GST-inclusive vs exclusive according to a column or a setting, never by guessing
Yes/no fields Accept yes/no, y/n, true/false, 1/0
Lists (tags) Define the separator inside a cell, such as semicolons
Leading zeros Keep them in codes and postcodes stored as text

5. Preview and validation

Before anything is saved, show a preview: the first rows as they will appear in the app, plus a summary ("1,946 rows ready, 38 with errors, 16 possible duplicates").

Validation must be per row, with a clear message: "Row 214: email address is missing @". Offer a download of the error rows as a CSV, with an extra column explaining each problem, so the user can fix them in their spreadsheet and re-import only those.

6. Duplicate rules

This is the decision most briefs forget. Specify:

  • Match key: what makes two records "the same" (email for customers, SKU for products, external ID if one exists).
  • Behaviour on match: skip, update existing, or create anyway. Let the user choose at import time, with a safe default (skip).
  • Blank values on update: a blank cell should not wipe existing data unless the user explicitly chooses that.
  • Duplicates within the file itself, not just against existing records.

7. Partial imports and undo

Decide between "all or nothing" (any error stops the import) and "import the good rows, report the rest". For most small businesses the second is friendlier, provided the error file makes the rest easy to fix.

Every import should be a logged batch: who ran it, when, how many rows created and updated. An undo for the batch (removing records it created and reverting fields it changed) turns a frightening mistake into a two-click fix. If full undo is too costly to build, at least tag every record with its import batch so it can be found and removed.

8. Large files

For thousands of rows, parsing in the browser can freeze the page. Papa Parse's documentation, for instance, offers a worker option to keep the page responsive and step or chunk callbacks to stream a file rather than load it at once. Server-side, large imports should run as a background job with a progress indicator and an email when finished.

9. Safety

Treat imported values as untrusted. Validate types and lengths. OWASP describes CSV (formula) injection: cells starting with = can be interpreted as formulas when a CSV is later opened in a spreadsheet program, so if your app ever exports this data again, neutralise values that start with formula characters.

A hypothetical test file

Before accepting the feature, run a test file through it containing: a name with a macron, an address with a comma, a date of 13/02/2026, a duplicate email, a row with a missing required field, and a trailing empty line. A finished importer handles all six without anyone opening the code.

FAQ

Should users import directly into live data?

For the first big migration, import into a test copy or a staging account first, check it, then run the real import.

Why do my dates come out wrong after an import?

Usually the importer assumed month/day order, or the spreadsheet stored dates as text. Specify day/month/year and test with a date where the day is above 12.

Can the importer accept Excel files instead of CSV?

It can, with extra work. CSV is simpler to support reliably; most spreadsheet programs can save a sheet as CSV.

How do I avoid importing the same file twice?

Duplicate rules catch most of it. Some apps also warn when a file with the same name and size was imported recently.

Moving data into a new system and want the import to get it right first time? Describe the spreadsheets you're working with. For how we build the systems that data moves into, see our page on web app development in Vienna.

Sources

WhatsAppLet’s talk