CSV column mapping: auto-mapping and manual mapping

When you import a CSV, CustodyComms maps your columns to the fields it needs (timestamp, message body, sender, receiver) using one of two paths: automatic mapping when CustodyComms recognizes your file's shape, or manual mapping when it doesn't.

Auto-mapping vs manual mapping

Both paths end up at the same data; auto-mapping is just a shortcut when CustodyComms is confident. Manual mapping is the stable interface — auto-mapping behavior evolves as we add platform support.

• Automatic mapping triggers when CustodyComms recognizes your file as one of six named platform formats, or detects timestamp + sender + body columns at high confidence. You see a pre-filled mapping screen with "Use Auto-Mapping" and "Map Manually" buttons. Confirm to proceed.
• Manual mapping triggers when CustodyComms can't auto-detect, or when you click "Map Manually" to override. The full Column Mapping screen opens with drag-and-drop chips for every field.

You can always click "Map Manually" to take over. Auto-mapping is a shortcut, not a black box.

Named formats

These are recognized at 0.95 confidence (very high). If your CSV came from one of these and the column headers are intact, CustodyComms pre-fills the mapping and shows a quick approve / override step.

• Signal Export — required headers: sent_at, type, conversationId, plus a phone column and a full-name column. From third-party Signal export tools.
• Discord Export — required headers: Author name, Message content, plus Attachments or Reactions. From DiscordChatExporter or Discord's "Request my Data".
• WhatsApp Export — required headers: Date and Time, Name, Message. From WhatsApp CSV exporters.
• iMessage Export — required headers: From, To, From Name, To Name. From iMazing or similar Mac/iOS export tools that emit CSV.
• Android SMS / MMS Export — required headers: address, type, threadid, plus date or datesent. From SMS Backup & Restore and similar.
• Universal Message Schema — required headers: source, platform, chatid, messageid, direction. CustodyComms's recommended canonical schema.

If your CSV doesn't match a named format, Generic CSV (Auto-detected) still kicks in at 0.75 confidence when CustodyComms can identify a timestamp column, a sender column, and a message column with at least 70% confidence each. If neither path clears the threshold, you go straight to manual mapping.

How auto-detection works

For each of your column headers, CustodyComms compares the name against keyword banks and assigns a confidence score. Fuzzy matching means small differences (spaces, underscores, casing, hyphens) don't break detection. Common header names that auto-match:

• Timestamp: timestamp, datetime, date, time, sentat, createdat, date_sent, and many variants.
• Message body: text, message, body, content, message_text.
• Sender: from, sender, author, name, username, full_name, phone, email.
• Receiver: to, recipient, receiver, to_name, destination.
• Direction: direction, dir, type, inbound, outbound, in, out.
• Contact (paired with direction): contact, party, phone, address.

If your column header isn't on the list, manual mapping always works. The keyword banks evolve as we add platform support; if you need a stable interface that won't shift between releases, use manual mapping or rename your columns to canonical names like date, sender, message.

Manual mapping screen

When the Column Mapping screen opens — either because auto-detection didn't fire or because you chose to override — your headers appear as draggable chips in "Available to Map" at the top. Drag each chip into the drop zone for the field it represents. When a chip lands, it moves to "Already Mapped". To undo, click the X on the chip.

Required fields:

• Timestamp — either a single datetime column (e.g. 2026-04-15 14:32:01) or two columns, one date and one time. Pick the approach that matches your file.
• Message content — one column with the message text.

Optional participants:

• Sender + Receiver mode — two columns: who sent each message, who received it.
• Contact + Direction mode — one column with the other person's identifier (phone, name, email), plus a column that says whether each row is inbound or outbound. This is how Android SMS and many backup tools structure their data.

If you skip participants, every message imports as "Unknown" → "Unknown" and you can fix it in Participant Mapping later.

A working example CSV

If you're building a CSV by hand, use this layout. Headers go in row 1.

date,sender,message 2026-04-15 09:12:00,Alice,"Pick-up at 5?" 2026-04-15 09:14:22,Bob,"Running 10 min late." 2026-04-15 09:14:55,Alice,"Got it."

Three columns is the minimum: a date/time column, a sender column, and a message column. CustodyComms auto-detects this layout as Generic CSV (Auto-detected) at 0.75 confidence and pre-fills the mapping.

Limits, encoding, and file format

• File size: up to 500 MB per CSV. Larger files may import but will be limited by your computer's available memory.
• Encoding: UTF-8 strongly preferred. Latin-1 and Windows-1252 are tolerated as fallbacks. If your CSV came from Excel and shows odd characters, save it as CSV UTF-8 before importing.
• Delimiters: comma, tab, semicolon, or pipe — auto-detected from the first few lines.
• Header row required: row 1 must be column names. Files without headers import with generic names (Column1, Column2…), which forces manual mapping.
• Quoted fields: messages with commas, line breaks, or quote characters must be wrapped in double quotes, with internal quotes escaped as "". Excel and Google Sheets do this automatically.
• Timezone handling: CSV timestamps are parsed and stored in UTC. The Column Mapping screen does not include a timezone selector. Set the matter's timezone on Matter Setup after import; exports will then render timestamps in that zone.
• Mapping memory: mappings apply only to the import you're running. Each new CSV gets its own mapping.

Accepted direction values

In Contact + Direction mode, CustodyComms reads your direction column to decide whether each row was sent by you or received. Values are case-insensitive.

Sent by you: 2 (Android numeric); sent, send, outgoing, out, outbound; sent folder, sent items, sentbox, sentfolder; abbreviations s, o, t, y; true, yes; fromme, isfromme, self; mo, mobile_originated, originated.

Received from the other person: 1 (Android numeric); received, receive, incoming, in, inbound; inbox, inbox folder, received folder; abbreviations r, i, rec, inc, f, n; false, no; tome, istome, other; mt, mobileterminated, terminated.

Any other value defaults to received in user-facing output.

Non-delivered statuses are filtered out rather than imported as evidence: 3 (draft), 4 (outbox / queued), 5 (failed), 6 (queued). If you need to keep these for completeness, change the value in your CSV before importing — but be aware drafts and failed sends weren't actually transmitted.

What happens if some rows fail

CustodyComms imports CSV files row-by-row. If a row has an unparseable timestamp or other malformed field, that row is skipped and the rest of the import continues. After the import you see a summary like "4,832 messages imported, 12 skipped". Skipped rows are not silently lost — the import log records the row index and reason for each skip on the matter's Chain of Custody. A high skip percentage usually means a date-format mismatch.

Common troubleshooting

• "Required field missing" or mapping won't proceed: the validation alert lists which fields are missing. The most common miss is using Contact + Direction mode but forgetting the Direction column.
• Dates show wrong month or year: your file is likely in a date format CustodyComms guessed wrong (US vs international).
• Garbled characters (’, é, £): file was saved as Latin-1 or Windows-1252. Open in Excel → File → Save As → CSV UTF-8 (Comma delimited) → re-import.
• Messages run together as one big block: quote-escaping is broken. Re-save as CSV (UTF-8).
• Sender shows as "Unknown": sender column has empty cells, or wrong column was mapped. Consider Contact + Direction mode if your data is structured that way.
• Auto-detected format is wrong: your headers happened to match a named format that doesn't fit. Click "Map Manually" to take over, or rename one of the platform-specific headers to break the named-format match.
• Many rows skipped: check the Chain of Custody log for the skip reason. Most often a date-format issue.