This article assumes you already know how to open a mapper and select columns. If you are building your first one, start with Data Mapper Overview and Creating a new Data Mapper, then come back here when something does not behave as you expect.

Overview

Most Data Mapper problems come from five facts about how mapping works. None of them produce an error message, which is why the symptoms are so often "the data is just gone" — a zero, a blank, an empty list. Those five facts are explained in How it works, the everyday procedures are in How to, and Troubleshooting maps each symptom to its cause and fix.

Quick answers

If you are troubleshooting a specific symptom, start here.

How it works: five facts

1. The mapper belongs to the table, not to the filebox

You open a mapper from a filebox, so it feels like it lives there. It does not. A mapper is an object on the table it feeds, and that is where you manage it. Finding, reusing, unlinking and deleting a mapper all happen in the same place:

Setup → Tables → your table → click the number under Connected Fileboxes

This also explains why a mapper name stays "in use" after you think you deleted it, and why unticking fileboxes inside the mapper screen does not detach them.

2. One mapper can serve many fileboxes, and it applies to every version

When you reuse a mapper, the copies stay linked. An edit you make for this year's file is applied to every filebox bound to that mapper and re-scans every version in each one. If last year's files do not have the tab or column you just added, they will start reporting mapping errors.

This is the single most common mistake customers make. Before editing a shared mapper, check the Connected Fileboxes list to see what else is bound to it. Changes are not reliably reversible: Restore Previous Version does not always undo them, and a deleted mapper cannot be recovered at all.

3. An unmapped field is null, and anything filtering on it drops the row

If a report, formula, dashboard widget or Excel table filters on a field, and that field is not mapped in the filebox supplying the data, every row gets a null value for it and the filter excludes all of them. The result is an empty report, a zero, or a table you cannot even add to a workbook.

Nothing errors, and the mapper itself looks perfectly healthy — which is why this is worth checking first whenever data "disappears" between the mapper and the output.

4. A field's data type is set on the table by whatever mapped it first

Type is a property of the table field, not of each mapper. A field typed as Number will silently drop any row whose value contains text; a field typed as Date over numeric values comes through blank. Changing the type inside a mapper does not stick — it reverts on the next sync, because the table is the authority. See Data Mapper: Field Types.

5. Lookups add attributes to rows; they do not bring amounts

A lookup enriches your rows by matching on a key field. If that key is not mapped, or is blank on some rows, the lookup columns come back empty for those rows. A lookup never supplies amounts or periods — those must be mapped in the filebox's own mapper. See Lookups Overview.

How to: the common tasks

Find the mapper behind a table

1. Go to Setup → Tables.
2. Find your table and click the number in the Connected Fileboxes column.
3. You will see every filebox feeding that table and the mapper applied to each.

You can also open a mapper directly from a filebox's three-dot menu in the Workspace, or view the relationships in Dataflow. Note that Viewer-level users cannot open the Tables area at all.

Reuse one mapper across several files

Use this when you have several files with an identical layout.

1. Open the mapper from one filebox.
2. Click the arrow next to Publish & Scan Latest Version.
3. Choose Publish & apply to, tick the target fileboxes and save.

The mappers stay connected afterwards. Every later edit to one of them applies to all of them. If you want them to diverge, unlink them first.

Unlink a mapper from a filebox

1. Go to Setup → Tables → your table → Connected Fileboxes.
2. Click the three dots next to the mapper and choose Apply to.
3. Untick the filebox you want to detach and save.

Unlink from the table, not from the mapper. Unticking fileboxes from inside the mapper's own publish dialog will appear to save, but will not detach them.

Delete a mapper

1. Go to Setup → Tables → your table → Connected Fileboxes.
2. Click the three dots next to the mapper and choose Delete.

Deleting a mapper is permanent, and it also removes the data that mapper loaded. Before deleting, confirm that no reports, DR formulas, dashboards or Planning content depend on data only that mapper supplied — and write down its settings, because it cannot be restored.

Apply a mapper change to historical data

A plain Publish & Scan applies your change to new versions only. To backfill data already loaded, use the arrow next to Publish & Scan, choose Publish & apply to, and select the option to re-scan all versions.

Troubleshooting

Start from what you can see. Most of these failures are silent — the product returns a zero, a blank or an empty list rather than an error — so the symptom is usually the only clue you have.

Best practices

Treat a shared mapper as shared infrastructure

Before editing one, open Connected Fileboxes and see what else is bound to it. If a new file has a different layout, give it its own mapper pointing at the same table rather than bending the shared one. Editing in place has broken hundreds of historical fileboxes in a single action, and it is not reliably reversible.

Keep every version in a filebox structurally identical

A mapper applies to all versions. Name tabs generically rather than by year (Input, not Budget 2027), keep column order consistent, and when you add a tab to this year's file, add the empty tab with matching headers to the older versions too. No data is needed — the structure is what the mapper checks.

Prefer Location Match Type for anything positional

If a file's headers are renamed by the source system, or columns get inserted, name and pattern matching will break every time. Location matching survives both.

Set date formats explicitly, and fix the source first

Leaving a date field on "infer" means the day/month order is a guess that can change between syncs. Set the format on the field, and check the source system's locale — a sheet saved under a US locale has already swapped the values before Datarails sees them.

Decide field types deliberately the first time

The first mapping fixes the type on the table, and changing it later means deleting the field and re-mapping it. Anything that may ever contain text — account codes, IDs with leading zeros, system-generated account names — should be Text from the start.

Do not archive a filebox that is still bound to a mapper

Detach it first, or the mapper will fail to save with an unhelpful "Not found".

Write down a mapper's configuration before deleting it

Deletion is permanent, removes the data that mapper loaded, and there is no change history on mappers to fall back on.

Related articles

• Data Mapper Overview — what a mapper is and how it fits together.
• Creating a new Data Mapper — building your first mapper step by step.
• Data Mapper: Field Types — how types are set on the table, and what each one accepts.
• Data Mapper: Filters — restricting which rows and sheets a mapper reads.
• Data Mapper: System Fields — the reserved fields a mapper header must not collide with.
• Data Mapper: Custom Columns, Custom Column Functions and AI Assistant for Custom Columns — deriving values the source file does not contain.
• Lookups Overview, Filebox Lookup, Table Lookup and Unmapped Items — enriching mapped rows with attributes.

Updated October 06, 2026 15:21