Set up an Import File Mapping

Use this guide when you see the same file layout more than once.

Before you start #

Run at least one preview first so you can see which columns or values need consistent mapping.

What you will do #

Create the mapping, test it on a preview, refine anything that still looks wrong, and save it for later imports from the same source.

1. Start with a real sample, not an imaginary one #

The best time to build a mapping is after you have already looked at at least one import preview from the real source file.

That gives you the information you actually need:

• whether the file has headers
• where the real data starts
• which columns matter
• which values need cleanup or extraction

2. Copy realistic sample rows to the clipboard #

The mapping manager creates new mappings from clipboard data.

Copy a realistic set of rows from the source file, ideally including:

• the real header row when one exists
• a few ordinary transaction rows
• enough variation to expose date, amount, or text quirks

If the clipboard data is not valid CSV or tab-delimited text, Common Cents cannot open the mapping editor from this flow.

3. Open the Import Mappings manager #

Go to Settings > Features > Mass Transaction Entry and open the Import Mappings manager.

This manager is only available when Mass Transaction Entry is enabled.

4. Create the new mapping from clipboard #

Choose Create Mapping from Clipboard.

This is the step where Common Cents reads the sample layout and opens the mapping editor.

If the sample is unrealistic or incomplete, stop and copy better source rows instead of building a weak mapping you will have to fight later.

5. Set the header row and the real data start row correctly #

Many exports have clutter before the real table, such as report titles, generated-on lines, or blanks.

Set both of these carefully:

• which row should be treated as the header row
• which row the real transaction data starts on

This is one of the most important mapping choices because a wrong header or start row can ruin everything else downstream.

6. Assign the source columns to the target fields you actually need #

Map the useful source columns into the Common Cents target fields, such as:

• date
• account
• payee
• category
• label when Labels are enabled
• amount
• note

Ignore columns that do not help the import.

The goal is not to preserve every source column. The goal is to land the fields Common Cents actually needs.

7. Use Teach It for cleanup and extraction work #

When a column needs normalization or extraction instead of a direct one-to-one copy, use Teach It.

This is useful when the source data needs help turning into the clean field values you want later.

Build only the rules you actually need for repeated imports. Do not turn the mapping into a theoretical parser for every possible bad row.

8. Test the mapping on a real preview before you trust it #

After saving the mapping, run an import preview using the same source layout.

Look closely at the landed draft rows and ask:

• did the right columns populate the right fields?
• are signs, dates, and notes correct?
• did any important column get skipped or misread?

If the preview still needs the same cleanup every time, the mapping is not finished yet.

9. Refine or replace weak mappings instead of working around them forever #

A good mapping should save repeated cleanup, not become another source of repeated cleanup.

If the mapping keeps failing in the same way:

• edit it
• improve the header or data-start choices
• adjust the field assignments
• refine the Teach It rules

Do not keep a weak mapping just because it exists.

See also: Import Mappings, Teach It, and Import Transactions.