Validate the incoming structure, identity rules, and meaning of blanks before mapping it into the working table. Reconcile adds, updates, rejected records, and exceptions after the import.
In this guide
Write down what the routine expects
List required columns, their business meanings, allowed types, the match key, and the intended update behavior. Include the source system and file version when available. Treat a changed header as a mapping question even when the new wording looks similar.
Define missing, blank, unchanged, and delete separately. Grist documents that blank incoming fields are skipped in its update behavior; other applications may differ. Confirm the receiving system's semantics before interpreting an empty cell as an instruction to clear a working value.
- Keep the source unchanged and record its row count, headers, file date, and origin.
- Compare headers and required columns with the saved contract. Stop for review when a required column disappears or changes meaning.
- Check identifiers, duplicate keys, dates, currencies, and numeric units using representative and boundary rows.
- Preview the receiving application's mapping and classify which records should be added, updated, or rejected.
- Try the routine in a separate working copy using known examples before applying it to the main table.
- Reconcile the resulting counts and values with the expected changes. Keep failed records and unresolved mapping choices in a separate review file.
What should the import preview stop?
Use this authored preview before updating a live table. Matching column names are insufficient when the meaning or units changed. Save the agreed map with the source schema and sample rows. Reuse it only while those assumptions remain true; a new currency column should reopen the review.
| Incoming field or row | Old mapping | Review decision |
|---|---|---|
| price=18; currency=EUR | price_usd | Block mapping until currency handling is agreed |
| sku=00127 | Numeric parsing enabled | Import as text; compare exact string |
| Existing price=18; incoming price blank | Automatic replace | Choose blank behavior explicitly in the receiving tool |
Count outcomes rather than assuming every row updated
Record the expected additions, updates, unchanged records, and rejected rows before the run. Compare those expectations with the result. If several incoming rows share one key, resolve that conflict rather than relying on whichever record the software happens to use.
Save a versioned operation history after review, together with the input contract. An operation history is valuable when its assumptions remain true; it should not silently authorize a new mapping when the supplier changes its export.
Turn the contract into a preflight report
Review an incoming import without changing records. SAVED CONTRACT: [headers, types, identity, blank/update rules] INCOMING HEADERS AND SAMPLE ROWS: [paste] RECEIVING TABLE REQUIREMENTS: [state] Report missing/renamed columns, type changes, duplicate keys, ambiguous blanks, and incompatible units or currencies. Separate valid rows from exceptions. Propose mapping questions and a small preview test. Do not equate an empty value with deletion or invent a missing source field. Return a preflight checklist and a reviewer decision log.
Use the same check before the next file
The repeatable asset is the contract, sample rows, mapping, exception handling, and reconciliation record together. Keep them beside the cleanup routine so another operator can decide whether a new file belongs in the same process.