Automated CSV: File & Column Naming Consistency

Explains how Clarity recognizes an incoming Automated CSV report as the "same" report each time, what it automatically overlooks (like dates in the file name), and what needs to stay consistent so processing doesn't break.

Overview

When you send a report to Clarity through the Automated CSV method, Clarity has to figure out — every time a file arrives — whether it's looking at a new upload of a report it already knows how to process, or a report it's never seen before.

It makes that determination automatically, based on three things:

1. The file name

2. The column headers in the file

3. Which application the file was uploaded for

If all three match a report Clarity has processed before, your new upload continues on exactly like every prior one — same processing, same mapping, no extra steps. If any of them come out different, Clarity treats the file as a brand-new report layout, and the transformation that was built for your original file won't automatically apply to it.

This article explains what Clarity automatically forgives (so you don't need to worry about it) and what needs to stay consistent (so you don't run into processing issues).

Dates and timestamps in the file name are automatically ignored

Most reports are exported with a date or timestamp baked into the file name — UserData_2025-12-07.csv, AppUsers20251207.csv, VendorReport_20251109064444.csv, and so on. Clarity expects this and strips these patterns out before it ever compares file names, so your export tool is free to keep stamping every file with today's date (or a full timestamp) without ever breaking the recognition process.

The file extension (.csv, .tsv, .xlsx, .json, .xml) is also ignored — so switching your export from .csv to .xlsx between uploads is safe on its own, as long as everything else stays the same.

Note: Switching formats only stays safe if the new format extracts the exact same column headers as the old one — same spelling, same capitalization, no stray whitespace. Different file formats are read by different parsers, so it's worth double-checking headers after a format change (for example, some spreadsheet exports can introduce a trailing space on a header that a CSV export didn't have).

The table below lists every date/timestamp style Clarity currently recognizes and removes automatically:

Clarity checks for these from most specific to least specific, so a full timestamp like 2025-11-09_06-44-44 is removed as a single unit rather than getting only partially cleaned up.

A few things worth knowing about how this cleanup works:

• Whatever is left after the date/timestamp and extension are removed is trimmed of any leftover leading or trailing underscores, hyphens, periods, or spaces — so Report-20251207-final.xlsx becomes Report-final, not -Report-final-.

• The rest of the file name is compared as-is. Only the date/timestamp patterns above are removed — nothing else is assumed to be a date. If your export tool ever changes the non-date part of the name (for example Report-final.csv becoming Report_final.csv, or AppUsers becoming Users), Clarity will treat that as a different file.

• If a file name is nothing but a date or timestamp once the extension is removed, Clarity falls back to a generic internal label rather than a blank name. This works, but we recommend every export always includes a descriptive prefix (like AppUsers or VendorReport) so recognition never has to rely on that fallback.

Column headers need to match — but Clarity forgives some formatting differences

Along with the file name, Clarity looks at the full set of column headers in the file. This is the part customers most often trip up on, so it's worth being precise about what counts as "the same" and what doesn't.

Column order doesn't matter. Clarity compares the full set of headers, not the sequence they appear in — so reordering columns between exports is always safe.

Spelling and capitalization do matter. Clarity does not correct for typos or case differences. Email, email, and EMAIL are three different column names as far as recognition is concerned — if your source system's export ever changes casing on a header, it will register as a change even though nothing meaningful about the data changed.

Minor punctuation is cleaned up automatically. Periods, spaces, and other characters that aren't valid in a database column name are automatically normalized (for example, a period becomes an underscore). Practically, this means small formatting differences in punctuation alone usually don't break recognition — but don't rely on this for anything beyond incidental symbols, since letter-for-letter spelling and case still have to match.

Blank/unnamed column headers are positional. If your file has one or more columns with no header text, Clarity assigns each one a placeholder name based on where it falls in the file. If the number of blank-header columns changes, or a blank column shifts to a different position, that counts as a layout change — even if every named column is untouched. If your report regularly has unnamed columns, try to keep them in a consistent position (or name them) between uploads.

Adding, removing, or renaming any column is always a layout change. There's no partial-match — every header in the file has to match what Clarity has seen before.

Uploads are always scoped to a single application

The file name and column comparison only ever happens within the specific application (Integration) the file is uploaded to. A Users.csv uploaded to one Automated CSV app is never compared against, or confused with, a Users.csv uploaded to a different app — so identical file names and layouts across two unrelated applications are completely safe and expected.

What happens if something changes

If Clarity sees a file name/column combination it hasn't processed before for that application, it treats the upload as a new, distinct report — not as a continuation of your existing one. The transformation that was originally built for your report won't automatically apply, which can mean the sync doesn't produce the results you expect.

If you know a change is coming — new columns being added, columns being removed, a header getting renamed, or your export tool changing its file-naming convention beyond just the date — reach out to your Clarity Support representative before the change goes live so the mapping can be updated to match.

Quick checklist

Safe to change, no action needed:

• The date or timestamp anywhere in the file name

• The file extension (.csv ↔ .xlsx, etc.)

• The order columns appear in

• Minor punctuation-only differences in a column header (e.g. a period vs. an underscore)

Keep consistent, or check with Clarity Support first:

• The non-date portion of the file name

• The exact spelling and capitalization of every column header

• The number and position of any blank/unnamed column headers

• Adding, removing, or renaming any column

Need Help?