Field Mapping Is the Real Work

People hire me expecting the engagement to be mostly code. It isn't. Most of it is a spreadsheet.

Every integration starts the same way: your system has a field, their system has a field, and someone has to decide whether those two fields mean the same thing. Sometimes they do. Often they almost do, which is worse, because "almost" is where data corruption lives.

What the mapping spreadsheet actually contains

• Their field, your field, and the transform between them — not just "customer_id maps to account_number," but what happens when their ID has a prefix yours doesn't, or theirs allows nulls and yours doesn't.
• The exceptions — the eleven accounts that were set up wrong three years ago and still don't follow the rule everything else follows. There are always eleven accounts.
• What "no value" means in each system — an empty string, a null, a zero, and a missing field are four different things, and vendors are never consistent about which one they use.
• Who's authoritative when both systems disagree — this is a business decision, not a technical one, and it needs an actual answer before I write a line of code.

Why this takes longer than the code

Writing the transform, once the mapping is settled, is often the fastest part of the week. Getting to a settled mapping means:

• Reading the vendor's docs, which are usually wrong or out of date in at least one place.
• Talking to the people who actually use the third-party system, because the docs never mention the workaround everyone's been doing by hand for two years.
• Talking to your team, because "what does this field mean to us" turns out to have a different answer in sales than it does in accounting.
• Pulling a sample of real records and finding out the theory doesn't survive contact with actual data.

That last one always finds something. Always.

Why I don't skip it

Skipping straight to code and "figuring out the edge cases as they come up" is how you get silent data corruption — the kind that doesn't throw an error, doesn't show up in a log, and just quietly makes your reports wrong for six months until someone notices the numbers don't add up. By then nobody remembers which system is telling the truth.

The mapping spreadsheet is slow because it's where all of that gets found before it's live, instead of after. It's not the boring prelude to the real work. It is the real work. The code is just the part that's easy to explain to people who aren't doing it.