The definition, precisely
An STTM (also: data mapping document, field mapping, crosswalk) commits to a relationship between two systems, field by field. For every in-scope target field it answers four questions: where does the value come from; what rule or transformation produces it; what is the evidence that this pairing is right; and — when nothing fits — what decision is still open, and whose it is. It is a design artifact, not a pipeline: the document tells a developer what to build and tells a reviewer what to check. Coverage is measured against the target system’s fields, never against how much of the source was used.
One real row
From a published, unedited mapping of QuickBooks Online’s customer entity onto NetSuite’s customer record:
Target: isInactive · Source: Active · Type: conditional
CASE WHEN Active IS NULL THEN NULL ELSE NOT Active END
Evidence: “If true, this entity is currently enabled for use by QuickBooks.” — Intuit’s API reference for the source field
Why the row earns its place: it is a polarity flip. Copied across without the inversion, every active customer arrives in the target system switched off — and the quoted line is what lets a reviewer confirm the inversion in seconds.
What a complete STTM contains
- Target field and object — one row each, the completeness yardstick.
- Source field, or an explicit statement that none fits.
- Mapping type: direct, transformation, lookup, conditional, constant, generated — or unknown, which is a finding, not a failure.
- The transformation rule, precise enough to implement.
- Evidence — the verbatim specification line each derived rule rests on.
- Assumptions and open questions, each with an owner.
- Review status and sign-off: who accepted, edited or rejected what.
Three things an STTM is not
- Not a data dictionary — a dictionary describes one system; a mapping commits to a relationship between two.
- Not the ETL job — the document is the design the job implements; conflating them is how undocumented pipelines happen.
- Not finished when full — a sheet with every cell filled and no open questions usually means the hard rows were guessed. The uncertain rows should look uncertain.
Questions, answered straight
Who writes and owns the STTM?
Usually whoever bridges the two systems — an integration consultant, a business analyst, or a data engineer. Ownership matters more than authorship: a named person accepts each row, because a mapping nobody signed is a draft. The implementer should not be the only reviewer of their own guesses.
How detailed does it need to be?
Precise enough that a developer can implement any row without asking what it means, and no more — “direct copy” is a complete rule. What can’t be abbreviated is the uncertainty: every assumption and open question written down, each with an owner.
When in the project is it written?
After both systems’ field inventories exist and before any pipeline code. Written earlier, it references fields nobody has confirmed; written later, it documents the pipeline instead of designing it. It then stays live through review and sign-off — not frozen at kickoff.
Is Excel enough, or do you need a tool?
Excel is where reviews actually happen, and a disciplined team can run a migration on a well-kept workbook. What a spreadsheet won’t do on its own is preserve row identity through sorts and copies, detect stale versions, or keep reviewer notes alive in transit — the failure modes covered in source-to-target mapping in Excel.