Implementation worksheet · 6 min read
A CDP-to-Engagement-Platform Event Mapping Worksheet
Map field by field rather than event by event, and record five things per field: the source name and type, the destination name and type, the transformation applied, what happens when the value is missing, and who owns the field if it changes. Then add the two checks that catch most of the damage — confirm timestamps carry a timezone and are not being reinterpreted as local, and confirm identifiers are the same identifier on both sides rather than two different keys with similar names. An event that arrives with the right name and a subtly wrong field is worse than one that fails, because nothing alerts and the campaigns built on it look fine.
Integrations are usually validated by checking that events arrive. They do arrive. What is not checked is whether the fields mean the same thing on both sides, and the failures that come from that are quiet: a campaign segment that is 8% wrong, a trigger that fires a day late, an audience that silently excludes a region because a country code format differs.
Put it into practice
1. Inventory the fields you actually use, not the whole payload
Most events carry more fields than any campaign references. Map the ones used in segments, triggers or message content, and mark the rest as passthrough. A short accurate map beats a long aspirational one, and the effort saved goes into checking the fields that matter.
2. Record both types, and be suspicious when they differ
String on one side, integer on the other, is a defect waiting for a value that does not coerce. Boolean represented as true/false in one system and 1/0 or yes/no in another is the classic. Write both types down; the mismatches become obvious in a way they never are in a live payload.
3. Check every timestamp for timezone and format
This is the field that causes the most damage per instance. A timestamp sent without a timezone and interpreted as local time shifts by hours, which moves events across day boundaries and silently corrupts any daily cohort or 'within 24 hours' trigger. Require an explicit timezone in transit and verify what the destination does with it.
4. Confirm the identifier is the same identifier
user_id in the CDP and user_id in the engagement platform may be different keys — one internal, one from an auth provider, one an email hash. Matching on the wrong one produces partial matches, which look like a data-quality problem rather than a mapping bug. Test with a known record end to end.
5. Declare missing-value behaviour per field
Absent, null and empty string are three different things and destinations treat them differently — some overwrite with blank, some skip. Decide per field whether missing means 'leave as is' or 'clear it', because the default is usually to overwrite and that silently erases good data.
6. Name an owner per field and re-verify on schema change
Fields get renamed upstream by people who do not know a campaign depends on them. An owner and a re-verification trigger is the only defence. Without it, the first signal is a segment that quietly halves.
The field mapping worksheet
Copy this structure into your review document and record your observed result for each row.
| Source field | Source type | Destination field | Destination type | If missing | Owner |
|---|---|---|---|---|---|
| user_id | string | external_id | string | fail the event | |
| string | string | fail the event | |||
| created_at | ISO8601 + tz | signup_date | date | leave as is | |
| plan | string enum | plan_name | string | leave as is | |
| mrr | decimal | mrr | number | leave as is | |
| country | ISO 3166-1 alpha-2 | country | string | leave as is | |
| last_active_at | ISO8601 + tz | last_seen | datetime | leave as is | |
| is_trial | boolean | trial_flag | boolean | default false | |
| consent_marketing | boolean | subscribed | boolean | most restrictive wins |
A failure worth checking
The timestamp without a timezone. The source sends a naive datetime, the destination assumes its own local timezone, and every event shifts by however many hours separate them. Nothing errors. Daily cohorts are built on the wrong day, a 'within 24 hours of signup' trigger fires on the wrong side of the boundary for a chunk of users, and the reporting looks plausible because it is internally consistent. It is usually found months later by someone comparing two systems' counts for the same day.
Common questions
Should we map everything or only what we use?
Only what you use, plus a passthrough for the rest. A complete map of unused fields is maintenance with no payoff, and it dilutes attention from the fields that drive campaigns.
How do we test a mapping properly?
Push one known record end to end and inspect it in the destination field by field against the worksheet. Comparing aggregate counts is the common approach and it hides exactly the subtle mismatches this worksheet exists to catch.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.