Skip to main content

CSV Mapping Guide

Use this page when you are ready to connect placed overlays on the PDF to the data in your CSV. This is the step that usually decides whether your batch export succeeds cleanly.

What Mapping Means​

Mapping tells Bulk Fill which CSV column should fill each mapped overlay on the PDF. In the current product, the mapping target is a positional column ID such as column_0 or column_1.

Bulk Fill currently supports CSV mapping for:

  • text fields
  • QR fields
  • barcode fields

Each mapped overlay gets a short badge in the editor:

  • text fields use F·1, F·2, and so on
  • QR fields use QR·1, QR·2, and so on
  • barcode fields use BC·1, BC·2, and so on

The mapping controls in the Fields tab connect each mapped overlay to one CSV column.

How Mapping Works In The Web App​

  1. Add a mapped overlay from CSV Mapping.
  2. Open the Fields tab.
  3. Choose the correct CSV column for that overlay.
  4. Preview one or more rows to confirm that the expected value appears.

You can also place a mapped text field directly from the Data tab by using the plus button next to a column. QR and barcode mapped overlays are added from the CSV Mapping section.

Simple Mapping Example​

Suppose your CSV rows follow this structure:

column_0 = customer name
column_1 = invoice number
column_2 = invoice date
column_3 = amount

A simple invoice layout might use these mappings:

  • customer name text field -> column_0
  • invoice number barcode field -> column_1
  • date text field -> column_2
  • invoice lookup QR field -> column_3

When you preview row 2, Bulk Fill fills those field positions with the values from row 2 of the CSV.

What Matters Most In The Current Contract​

Because Bulk Fill currently identifies columns by position, stable column order matters more than header text. If your upstream CSV changes the order of the columns, re-check every mapping before you export again.

This also affects header rows:

  • a header row is still treated as row data
  • preview row 1 will show that header content
  • batch export includes row 1 unless you exclude it

How To Check Your Mapping​

Before you run the full export:

  1. Confirm that every mapped overlay in the Fields tab is mapped.
  2. Preview several rows, not just the first row.
  3. Inspect the longest or least predictable rows.
  4. Make sure blank cells only appear where blank output is acceptable.

For mapped QR and barcode overlays, row data matters more than template state:

  • if a row value is blank, that overlay is skipped for that row
  • if a row value is invalid for that QR/barcode format, that overlay is skipped for that row
  • other overlays on the same row still continue

Common Mapping Problems​

The CSV Column Exists But The Field Is Still Blank​

The overlay may not actually be mapped, or the selected row may have an empty cell in that column.

The Wrong Value Appears​

The overlay is probably mapped to the wrong positional column. Re-check column order and remap it.

A QR Or Barcode Does Not Render For One Row​

That usually means the current row value is blank or invalid for the selected code format. The row can still export, but that mapped code overlay is skipped.

Two Mapped Overlays Are Easy To Confuse​

Place one overlay at a time, preview after each change, and avoid changing column order once the layout is already mapped.

Next Steps​