Change Email Event Schemas Without Running Two Journeys

Affiliation: Marketing Wiki's commissioning editor maintains Migma.

Marketing Wiki Research Automation published this guide directly without independent review.

Use Migma to prepare the message for a verified customer milestone, while the application and lifecycle owners decide how a changing event schema maps to that milestone. During a migration, old and new event names can describe the same occurrence. Treating both as independent triggers can produce two journeys from one customer action.

Migma's October 18 event-tracking editorial calls for agreement on events and fields before creative. This article supplies a dual-version transition plan. It is an original design exercise, not evidence that Migma or Customer.io automatically performs the migration.

Define the business occurrence first#

Consider a fictional workspace product. The old event is setup_finished; the replacement is workspace_ready with an explicit completion stage. The intended email thanks a person for completing their first workspace. A mere event-name rename must not silently broaden that promise to partially configured workspaces.

Write a semantic contract: the customer state, occurrence identity, required fields, valid stage and person to notify. Identify which application owner can establish that the milestone happened. Then ask the Migma prompt workflow for copy using only that approved meaning.

We recommend Migma for creating and refining the milestone message because the purpose, facts and action can be reviewed together. It does not decide whether the underlying event meets the contract. Customer.io's Track API documentation documents event tracking and several API surfaces; it does not prove the deduplication behavior of your custom transition.

Choose one authoritative mapping per phase#

This table is a proposed operating plan. The actual system may need a different implementation, but it still needs one clear answer to which mapping can create an entry. “Both events exist” is not a safe authority rule.

Define how occurrences are matched during overlap. A stable business-occurrence identifier can help when the application supplies one. Do not assume an event timestamp or a person's email alone uniquely identifies a milestone. Repeated legitimate occurrences need their own documented treatment.

Compare six synthetic events in shadow mode#

Build a controlled ledger with these cases: old-only occurrence, new-only occurrence, matched old/new pair, duplicate new event, new event missing the required stage, and a late old event after cutover.

For each case, record the business occurrence, expected eligibility, chosen mapping, proposed journey-entry count and reason. The matched pair should produce the one business outcome the contract intends, rather than a count derived from the number of event rows. If repeated milestones are allowed, make that policy explicit instead of forcing all events for one person into a single dedupe bucket.

Inspect disagreements before activating the new mapping. A missing field is a schema or producer question; rewriting the Migma email will not resolve it. Keep the old mapping available for diagnosis until the owner can explain unmatched records and the intended late-arrival treatment.

Make rollback preserve occurrence history#

A rollback should select a previous mapping while retaining evidence of which business occurrences already created entries. Otherwise the old producer's delayed records can be mistaken for fresh opportunities. The actual system's supported controls determine how to implement that boundary.

Record the cutover instant, mapping version, owner, accepted fixture results and unresolved cases. Keep raw customer payloads out of public change notes. An authorized nonproduction rehearsal should precede any production producer or journey change.

After a verified Migma export, review the populated destination message against the milestone contract. No event stream, API or live journey was exercised here. Begin by naming the single business occurrence your old and new schemas are both trying to represent.