Who this is for: CRM administrators and integration builders connecting customer records.
A mapping workbook should say more than “email maps to email.” It needs to explain which system owns the value, how records match, and what the integration should do when the available data is incomplete.
The synthetic example below maps a CRM account into a billing customer. It deliberately leaves a field unchanged when it is absent from the incoming event. That decision prevents a partial update from erasing a verified address.
Agree identity before field mapping
Persist the destination customer ID after a verified match or creation. Use that reference on later updates. If an incoming record has no persistent match, define the approved search inputs and the number of acceptable results.
Zero matches and multiple matches are different situations. A new customer may be appropriate for zero verified matches. Multiple plausible matches need resolution. Don't choose the first search result simply because the API returned one.
| Condition | Action |
|---|---|
| Stored billing ID exists | Update that customer after verifying association |
| No ID; one verified match | Persist the matched ID |
| No ID; several candidates | Hold for review |
| No ID; no verified match | Follow approved creation policy |
| Stored ID points to deleted customer | Review; don't silently recreate |
Specify ownership for every field
Field ownership can differ within the same record. Sales owns the account manager. Finance owns verified billing details. The integration carries those decisions; it shouldn't invent a last-write-wins policy.
Document transformations with examples. Trim surrounding whitespace in a code if that is permitted, but don't remove characters from an identifier without knowing their meaning. Record the source timezone before converting a timestamp.
| Source | Destination | Authority | Transformation | Blank / conflict rule |
|---|---|---|---|---|
| account.id | metadata.crm_account_id | CRM | Preserve exact ID | Reject if absent |
| billing_customer_id | customer.id | Verified match register | No fuzzy rematch | Review if absent |
| account.owner | metadata.account_owner | CRM | Approved owner ID | Review inactive owner |
| billing.email | Finance-verified CRM field | Trim whitespace | No overwrite when omitted | |
| event.address | address | Billing after verification | None | Preserve when omitted; review explicit change |
Treat clearing and deletion as their own operations
An omitted field often means “not included in this event.” An empty string may mean “clear this value,” or it may be a data-quality error. Decide which meanings the source can express and how the destination represents them.
A deleted CRM record doesn't automatically authorize deleting billing history. Specify archive, unlink, retain, or review behavior for each system. Put the responsible business owner's decision in the sheet.
Reconcile values, not just record counts
Test initial creation, replay, partial updates, conflicting edits, and deletion using synthetic data. Compare IDs and selected field values in both systems after each test. Save rejected records with their reasons.
Add a test where an older event arrives after a newer one. If events carry a reliable version or timestamp, define how you reject stale changes. Otherwise reconcile against current source state before writing. The mapping sheet is finished when another builder can implement these decisions without guessing.
- Persistent IDs identify both sides.
- Every mapped field has an authority.
- Transformations have input/output examples.
- Blank, omitted, and explicit clear behavior are documented.
- Stale events and deleted records have tests.
Free download · No email required
CRM field-mapping workbook
Replace illustrative names with actual API field names. Record source and destination IDs before mapping values. Test omitted fields, explicit clears, conflicts, and stale events.
Open the CSV in Excel, Google Sheets, or another spreadsheet tool. The Markdown brief is editable in a text editor.
Common questions
- Should all fields synchronize both ways?
- Only when the process needs it and conflict handling is explicit. One-way ownership for each field is often easier to reason about than allowing both systems to overwrite it.
