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.

If you are still deciding between overlays and native fields, start with Choose the right fill method. If your PDF already contains supported fillable fields, also read Work with native PDF forms (AcroForm).

What Mapping Means​

Mapping tells Bulk Fill which CSV column should fill each mapped overlay or supported native PDF form field. In the current product, each mapping resolves to a positional column ID such as column_0 or column_1. In the web app, unnamed or generated columns are shown with friendly labels such as Column 1 or Column 2, but those labels still map to the same positional keys in saved mappings and other public contracts.

Static overlays are not part of this guide because they do not read from CSV. This page covers the two CSV-driven layers:

  • overlay mapping
  • native PDF form mapping on supported non-XFA AcroForm PDFs

Section A - Overlay Mapping​

Overlay mapping is the right choice when the value should come from CSV and you need flexible placement anywhere on the page.

In the current product, Bulk Fill supports CSV mapping for these overlay types:

  • text fields
  • QR fields
  • barcode fields

Overlay mappings get 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

How Overlay Mapping Works In The Web App​

  1. Add a mapped overlay in Fields.
  2. Choose the CSV column for that overlay row. For unnamed or generated columns, the closed picker uses friendly labels such as Column 1. The picker menu also includes the current preview row's value for each column, for example Column 1: Carter.
  3. Mapped rows also show the current preview row's CSV value directly in the row as a Preview row N: ... helper so you can spot-check the mapping quickly. If the value is clipped, hovering shows a more detailed tooltip such as Preview from Column 1, row 2: Carter.
  4. Preview one or more rows to confirm that the expected value appears.

On PDFs without supported native AcroForm fields, you can also place a mapped text field directly from the Data tab by using the plus button next to a column. If the PDF already has supported native AcroForm fields, Bulk Fill hides that Data-tab shortcut so the native Form workflow stays primary. Overlay text, QR, and barcode fields still remain available from Fields.

Overlay Mapping Example​

Suppose your CSV rows follow this structure:

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

In the editor UI, that same unnamed or generated column set appears as Column 1, Column 2, Column 3, and Column 4.

A simple overlay-driven 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 overlay positions with the values from row 2 of the CSV.

Section B - Native PDF Form Mapping​

Native PDF form mapping is the right choice when the source PDF already contains supported native AcroForm fields and you want Bulk Fill to write into that form structure directly.

In the current product, Bulk Fill supports native mapping for:

  • supported native PDF text fields
  • supported native PDF checkbox fields
  • supported native PDF single-select dropdown fields
  • supported native PDF radio groups

Native PDF form mapping does not support XFA PDFs. When Bulk Fill detects an XFA form, the Form tab explains that limitation and points you back to overlay Fields, text, QR codes, or barcodes instead.

Native Field Badges And Guides​

Native form rows use these badges:

  • native PDF text rows use FF·1, FF·2, and so on after you add them
  • native PDF checkbox rows use FC·1, FC·2, and so on after you add them
  • native PDF dropdown rows use FD·1, FD·2, and so on after you add them
  • native PDF radio rows use FR·1, FR·2, and so on after you add them

Supported writable native PDF text fields, checkboxes, dropdowns, and radio groups also show pale purple guide boxes directly on the PDF canvas. Before a PDF field is selected in the Form tab, those guide boxes use generic FF, FC, FD, or FR labels. Once a Form row is connected to a specific native PDF field, that PDF guide adopts the row's numbered FF·n, FC·n, FD·n, or FR·n label. The currently selected native mapping uses a stronger purple highlight. Text, checkbox, and dropdown rows also show the current preview row's CSV value directly in the guide when that field type can display it.

How Native Form Mapping Works In The Web App​

  1. Open Form and add the native row type you need:
    • Add Form Field
    • Add Checkbox
    • Add Dropdown
    • Add Radio
  2. Choose the native PDF field from the Select a FF, Select a FC, Select a FD, or Select a FR picker.
  3. Choose the correct CSV column on the second line of that row. For unnamed or generated columns, the closed picker uses friendly labels such as Column 1. The picker menu also shows the current preview row's value, for example Column 1: Carter, even though the underlying positional key remains column_0.
  4. Mapped rows also show the current preview row's CSV value directly in the row as a Preview row N: ... helper so you can check the selected column before exporting. If the value is clipped, hovering shows a more detailed tooltip such as Preview from Column 1, row 2: Carter.
  5. Preview one or more rows to confirm that the expected value appears.

Each native row starts with the next available row number for that type, but no PDF field is selected until you choose one from the field picker in the row. If the current PDF has no supported fillable form fields, checkboxes, dropdowns, or radio groups, the related add button stays visually unavailable and explains why when you hover or click it.

If you want to keep a Form row but temporarily clear the chosen native PDF field, you can return the first picker to Select a FF, Select a FC, Select a FD, or Select a FR. That keeps the row and any selected CSV column in place so you can park the row and come back to it later.

If the current PDF uses XFA fields, the native add buttons stay unavailable in the Form tab because those native fields are outside the supported scope. You can still place overlay Fields from the Fields tab and map them to CSV columns as usual.

Value Rules For Native Fields​

For native PDF checkbox fields, row values are interpreted as:

  • checked: true, 1, yes, y, x, on
  • unchecked: false, 0, no, n, off, blank

Any other checkbox token is treated as a warning and that native field is skipped for that row.

For native PDF dropdown fields, row values are interpreted as:

  • Bulk Fill first tries an exact match against the visible dropdown option text
  • if the visible option text matches exactly, that option is selected
  • if there is no exact visible-text match and the dropdown is editable, Bulk Fill writes the CSV value as free text
  • if the CSV value is blank and the dropdown is non-editable with no blank visible option, Bulk Fill leaves that field unchanged without raising a warning
  • if the CSV value is not blank, there is no exact visible-text match, and the dropdown is non-editable, Bulk Fill raises a warning and skips that field

Single-select dropdowns only are supported in this version. Multiselect dropdowns, option lists, and XFA native fields stay outside the supported scope.

For native PDF radio groups, row values are interpreted as:

  • Bulk Fill tries an exact match against the option strings returned by PDFRadioGroup.getOptions() in the installed local PDF engine
  • if the CSV value exactly matches one of those option strings, that option is selected
  • if the CSV value is blank, Bulk Fill clears the whole radio group
  • if there is no exact match, Bulk Fill raises a warning and skips that field

Radio groups are supported only as one logical field per group. Widget-level radio editing, option lists, and XFA native fields stay outside the supported scope.

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 row in Fields and every native PDF form row in Form is mapped.
  2. Use the FF·n, FC·n, FD·n, or FR·n button in the Form row if you need to jump back to that native field on the PDF canvas.
  3. Preview several rows, not just the first row.
  4. Inspect the longest or least predictable rows.
  5. Make sure blank cells only appear where blank output is acceptable.

For deletion behavior:

  • unmapped overlay rows in Fields remove immediately
  • mapped overlay rows in Fields ask for confirmation before removal
  • partially configured native Form rows remove immediately
  • fully mapped native Form rows ask for confirmation before removal

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 mapping is probably connected 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.

A Native PDF Field Did Not Fill​

Preview and export now surface warnings when a native PDF field cannot be written. Review the warning summary, then check the field name, CSV token, and whether the PDF field exists in the current document.

For dropdown fields specifically, confirm whether the CSV value exactly matches the visible option text shown in the PDF. A value that matches an internal or export token but not the visible option text is treated as unmatched in this version.

For radio groups specifically, confirm whether the CSV value exactly matches one of the option tokens listed in the Form row helper text. Those tokens can differ from nearby human-visible page captions in some PDFs.

If there are many native field warnings in one preview, the app may show a warning count summary instead of every warning detail in the toast. The row and field-level warning state in the Form tab remains the source of detail.

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​