How to Map CSV Columns Between Two Systems Before an Import

To make a CSV export match another system's import schema, map each source column to the destination's expected name, exclude columns the destination does not need, and reorder the remaining columns to match its template. The mapper changes headers, inclusion, and order while leaving the cell values unchanged.

Nablyx processes one CSV locally in your browser without uploading it, up to 200 MB, and writes mapped.csv as UTF-8, comma-delimited CSV. The mapper cannot infer a destination schema or reshape cell values; the first-party cap and streaming evidence is recorded in docs/tool-audit/batch-a.md.

A U.S. CRM-to-marketing handoff

Suppose a source CRM exports these fields for a U.S. team. The data is usable, but the receiving marketing system uses a different schema.

Assume the destination template requires email, first_name, last_name, state, in that order. Your mapping is:

• FirstName → first_name
• LastName → last_name
• EmailAddress → email
• State → state
• ContactId, LifetimeValue, CreatedDate — excluded when the destination does not need them

The values 000125, 1234.50, and 12/31/2026 are not reformatted by the mapping. If the receiving system expects a different date or number format, handle that separately from the header mapping.

Applying a multi-column mapping, step by step

1. 01

   Pull the destination's field table first

   Find the required and accepted field names in the importer's documentation, its sample or template CSV, or its API reference. The mapper renames columns to whatever you type — it has no view of what the destination expects, so it cannot supply this list for you.

2. 02

   Drop the source CSV in

   Pick or drop the file. The first rows are inspected to learn the headers; nothing is uploaded. Check the tool page for the current file-size limit.

3. 03

   Apply the rename table

   For each source column, type the destination's expected field name in the Output name field. The value is trimmed of surrounding whitespace before it is written, so a trailing space does not produce a duplicate-looking header.

4. 04

   Drop the columns the destination does not want

   Unticking Use removes the column from the output entirely; the dropped values are not read into the result. At least one column must remain included, every included column needs a non-empty Output name, and output names must be unique across included columns — that is enforced when the download starts.

5. 05

   Reorder with the up and down buttons

   Some destination importers require a specific column order or accept the data only in the order their docs show. The new order appears immediately in the preview and is what the exported file uses.

6. 06

   Download the mapped CSV

   The output is written as a UTF-8, comma-delimited file named mapped.csv. The preview shows the first rows of the mapped result with the new headers and order; the full file is generated when you click Download.

The Output name is trimmed but not otherwise changed. The trim only removes leading and trailing whitespace — internal spaces, punctuation, the receiver's preferred casing, and any underscores you want instead of spaces all stay exactly as you typed them.

When the mapper is the right tool, and when it is not

The mapper is a structural transform that knows nothing about your destination's semantics. It only changes which columns are present, what they are called, and the order they appear in. Three checks decide which tool to reach for.

A sensible sequence when the source needs repair is clean → fix encoding → map → import. The mapper can run after repair because it only changes which columns are present, their names, and their order.

Four pitfalls that look like "the mapper is broken"

Three of these are the mapper refusing to guess something it has no information about. None of them throw an error; they all produce a mapped file that the destination will reject.

Source not comma-delimited. The mapper reads the source as comma-delimited CSV and the output is always written with a comma delimiter, so the source separator does not propagate to the mapped file. A semicolon-delimited export reaches the renamed columns all right, but every value inside lands in the wrong cell because the parser was told comma. If your source uses semicolons, tabs, or pipes, run it through the encoding doctor first to switch it to comma, then map.

Required field not in your source. If the destination expects a column your source simply does not export, the mapper cannot invent one — that header does not appear in the output at all. Reconcile your included set against the destination's required-field list before you click download, and supply any missing required field through a destination import flow that can default it.

Values that need reshaping. The mapper keeps values exactly as they are. It does not reformat dates, strip currency symbols, normalise phone numbers, trim whitespace, or change letter case. If the destination expects ISO dates and your source exports 01/12/2026, change the date format before mapping.

Destination's required names differ from your source's casing or naming. Email and email are different headers in the strictest sense, and some importers reject either as an "unknown field". The mapper trims whitespace; it does not normalise case. Type the destination's exact expected spelling into the Output name column.

Verifying the mapped file before you import

The preview shows the first rows of the mapped result with the new headers and order, recomputed on every keystroke. That is enough to catch most wiring mistakes, but three checks catch the rest.

Confirm the included columns cover the receiver's required fields. Compare the preview header row against the destination's required-field list. Each included Output name should map to a field the importer lists, and any field the destination lists that is not in the preview is absent from the output entirely — the mapper cannot create a column that the source does not provide. Reconcile the missing fields against your source before you click download.

Confirm the source values did not get reshaped. Spot-check one row's values in the preview against the source. They should match exactly, including leading zeros, date text, and spaces. If the values need changing, do that before mapping.

Confirm the count and the delimiter. Open the downloaded mapped.csv in a text editor. The header should match the preview header exactly, every data row should have the same field count, and the separator should be a comma. Where the destination offers a test import or sandbox, use it to confirm that system's required fields and business rules before a full import.

Map CSV columns between systems

See the transformation

Awkward source headers become import-ready columns.

Rename the columns you need while keeping every value under the correct header.

cust_idcustomer_id

given_namefirst_name

mailemail

✓ Values stay with the right column