> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/flow/tutorials/components/csv-parser/pre-map-csv-columns.md).

# Pre-map CSV columns for a recurring import

Map the headers of a file that comes back every month once, in the flow, so users drop the export and press Next while required fields stay enforced.

Every month the events team exports the booth scans from the same badge scanner, with the same headers. Picking `First Name` to FirstName by hand each time is wasted effort and a chance to get it wrong. With **Default Mappings** and **Required Fields To Map** on the [CSV Parser](https://docs.avonnicomponents.com/flow/flow-components/csv-parser.md), the flow matches every column itself and refuses a file that lacks a field you cannot do without. The same setup works for any file with stable headers, such as a monthly price list from a supplier.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2F8HlSKXpeIbkwzg3MruLz%2Fcsv-pre-map-csv-columns-result.png?alt=media" alt="The CSV Parser after an upload: Found 5 rows, and all seven column headers already matched to Lead fields without any user action."><figcaption><p>With default mappings in place, every column is matched before the user does anything.</p></figcaption></figure>

## Before you start

* A screen flow with the CSV Parser on its first screen and a Create Records after it. [Import a CSV file in a screen flow](https://docs.avonnicomponents.com/flow/tutorials/components/csv-parser/101-tutorial.md) builds it with the same booth leads file used here.
* One real export from the system that produces the file. You need its header line exactly as written.

## How the parser matches a column on its own

For each header in the file, the parser tries these rules in order and stops at the first that works.

| Order | Rule                                                                                                | Example                                                      |
| ----- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 1     | A **Default Mappings** entry whose **Column Header** is the header, character for character         | `Booth notes` mapped to `Description`                        |
| 2     | The header is the API name of a field (spaces at the start or end are ignored)                      | `Company`, `Email`, `Phone`                                  |
| 3     | The header becomes a custom field API name when its spaces turn into underscores and `__c` is added | `Booth Notes` matches `Booth_Notes__c`, if that field exists |
| 4     | Nothing matches: the picker stays empty and the user picks a field                                  | `Surname`                                                    |

Every comparison is case sensitive. `email` and `EMAIL` do not match the `Email` field.

{% hint style="warning" %}
**Headers like "First Name" never map themselves.** The parser recognizes that `First Name` without its space is the `FirstName` field, but it keeps the header text instead of the field, so the picker shows empty and a required check on that field fails. It happens with every header that is a standard field's API name plus spaces: `Last Name`, `Mobile Phone`, `Lead Source` and so on. Add a **Default Mappings** entry for each of them.
{% endhint %}

## Steps

{% stepper %}
{% step %}

### Copy the header line from a real export

Open one export in a text editor rather than a spreadsheet app, so you see the headers exactly as the file stores them. The badge scanner export used in this tutorial starts with:

```csv
First Name,Last Name,Company,Job title,Email,Phone,Booth notes
```

Watch for capital letters and spaces at the end of a header. A **Default Mappings** entry only applies when its **Column Header** is identical.
{% endstep %}

{% step %}

### Add a default mapping for each header that does not match

Select the CSV Parser on the screen and find **Default Mappings** in the panel on the right. Click **Add Item** once per header that the rules above do not cover, and fill in its two fields:

* **Column Header**: the header as written in the file.
* **Object Field**: the API name of the field, not its label.

Each saved item shows as a card, with the header above the field name. Click the pencil on a card to change it, or the X to remove it.

For the booth scanner export:

| Column Header | Object Field  |
| ------------- | ------------- |
| `First Name`  | `FirstName`   |
| `Last Name`   | `LastName`    |
| `Job title`   | `Title`       |
| `Booth notes` | `Description` |

`Company`, `Email` and `Phone` need no entry. If some files call the last name `Surname`, add a second item `Surname` to `LastName`: several headers can point to the same field.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FS1hjfOA2hrmp4aP6XU20%2Fcsv-pre-map-csv-columns-panel.png?alt=media" alt="The CSV Parser panel with Required Fields To Map set to Last Name and Company, and four Default Mappings: First Name to FirstName, Last Name to LastName, Job title to Title, Booth notes to Description." width="320"><figcaption><p>Four default mappings cover the headers that do not match on their own.</p></figcaption></figure>
{% endstep %}

{% step %}

### Or build the list from a sample file

Instead of typing the pairs, click **Open Component Builder** at the top of the panel. The preview starts with example data and lets you upload your own file.

1. Upload your export in the preview.
2. Pick a field in every empty picker, including `First Name` and `Last Name`.
3. Click **Use as Default Mappings**.

Then check the **Default Mappings** list: every **Object Field** must be an API name such as `FirstName`. A header that was left with an empty picker can be saved with its own text as the field, and that entry will not work.
{% endstep %}

{% step %}

### Make the fields you cannot do without required

In **Required Fields To Map**, select the fields every file must provide. For Leads, `Last Name` and `Company`, because a Lead cannot be saved without them. Add `Email` if your follow-up campaign depends on it.

The check runs on the final mapping, whatever produced it: a default mapping, an automatic match, or a field the user picked.
{% endstep %}

{% step %}

### Choose how much of the mapping the user sees

These four settings are in the panel on the right, below **Default Mappings**.

| Setting              | Effect on the screen                                                                       | Turn it on when                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| **Hide Mapping**     | No mapping section. Columns are mapped automatically and the user only sees the drop zone. | Your default mappings cover every header, and users should never change them.    |
| **Hide Sample Data** | The three sample values under each header are not shown.                                   | The file holds values users should not read on screen, or the samples add noise. |
| **Hide Clear All**   | Removes the **Clear All** button, which empties every picker at once.                      | Users keep the mapping visible but should not wipe your defaults by accident.    |
| **Show Row Count**   | Shows "Found N rows." under the drop zone.                                                 | Almost always. With the mapping hidden, it is the only sign the file was read.   |

With **Hide Mapping** on, only the required fields are checked. A column that matches nothing is not reported, so add default mappings for every header before you hide the section.
{% endstep %}

{% step %}

### Save and test

1. Run the flow and upload the regular export. Every picker is filled: `First Name` shows First Name, `Booth notes` shows Description, and so on. The screen reads "Found 5 rows."
2. Now test the failure case. Rename `Last Name` to `Last name` in a copy of the file (a different case is enough) and upload it. Press Next.
3. The screen stops with "Required Headers Not Found: LastName. Please add them and try again." With **Hide Mapping** on, the message appears right after the upload, without waiting for Next.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FIDmUDxSFPJJhXktnbO6z%2Fcsv-pre-map-csv-columns-required-error.png?alt=media" alt="The CSV Parser showing the error Required Headers Not Found: LastName. Please add them and try again."><figcaption><p>A required field with no column mapped to it stops the screen.</p></figcaption></figure>

After the message the mapping section is not shown, so the user fixes the file and uploads it again. If a new spelling is legitimate, add it to **Default Mappings**.
{% endstep %}
{% endstepper %}

## Troubleshooting

<details>

<summary>A default mapping is ignored</summary>

The **Column Header** differs from the file's header: a capital letter, a space at the end, or a different word. Copy the header from the file in a text editor and paste it into **Column Header**.

</details>

<details>

<summary>The picker is empty although a default mapping exists for that header</summary>

**Object Field** holds something other than an exact API name, for example `First Name` or `firstname` instead of `FirstName`. Find the API name in Object Manager, under the object's Fields & Relationships, and type it exactly.

</details>

<details>

<summary>"Required Headers Not Found" although the column is in the file</summary>

The column is there but not mapped to the required field. Either its header has spaces and relies on automatic matching (see the warning above), or it is mapped to another field. Add a **Default Mappings** entry from that header to the required field.

</details>

## Related tutorials

* [Import a CSV file in a screen flow](https://docs.avonnicomponents.com/flow/tutorials/components/csv-parser/101-tutorial.md): the base flow this tutorial starts from.
* [Review rows before saving](https://docs.avonnicomponents.com/flow/tutorials/components/csv-parser/review-rows-before-saving.md): with the mapping automatic, give users a table of every row to check before the Create Records runs.
* [Import a file stored in Salesforce](https://docs.avonnicomponents.com/flow/tutorials/components/csv-parser/import-a-file-stored-in-salesforce.md): the same default mappings work when the CSV comes from a file attached to a record.
* [CSV Parser](https://docs.avonnicomponents.com/flow/flow-components/csv-parser.md): every setting of the component, in one place.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/flow/tutorials/components/csv-parser/pre-map-csv-columns.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
