AppointmentBooked, as it arrives
When a patient books a check-up at any of a dental chain's 40 clinics in Portugal and Spain, the booking system publishes one event. This is all of it:
type:AppointmentBookedappointmentId:88412patientId:20931clinicId:14slot:2026-11-12T09:30:00Z
The SMS reminder service subscribes to these events. Its job is a text the day before the visit, in the patient's language, with the clinic's name and street address. There is no phone number, no language, no clinic name, no address. The SMS service cannot write a word of the reminder from what it got.
The event is not badly designed. The booking system publishes what it decided: who, where, when. The patient's phone number and preferred language live in the patient records; the clinic's name and address live in the clinic directory. The question is who brings them together.
Look it up once, on the way
One answer is to let the SMS service call both systems for every event. That holds until a second consumer, the confirmation e-mail, needs the same language and clinic details. When every consumer calls back to the source systems for the missing fields, the load on those systems multiplies by the number of consumers, and each consumer depends on two systems it has no other business with.
A Content Enricher moves the lookup into one step on the channel, ahead of the consumers. It receives the event, looks up the missing data in a reference source (a database, another service, a cache), adds what it found and forwards a richer message. Consumers get everything they need without calling back to the source.
The enricher keeps every field it received and adds the patient's phone and language and the clinic's name and address. The SMS service reads only the enriched message.
The enriched message keeps the original fields, so appointmentId still identifies the booking, and adds the new ones beside them: phone, language set to es, clinicName and clinicAddress. The SMS service can now write the whole text from the message alone.
The booking system could carry all of this in the event itself, but then it has to know what every consumer will ever need. The opposite move, taking fields out of a message before it reaches a consumer, is a Content Filter.
Patient 20931 is not in the records
On a Monday morning the enricher receives an event for a patient who booked online four minutes earlier. The patient records answer: no such patient. Booking and patient records are separate systems, and the new record has not reached the second one yet. A few events later, the patient service does not answer at all for eight seconds.
Those are two different answers, and the first decision is to keep them apart. A timeout says nothing about the patient. An enricher that treats it as "no language on file" and falls back to the clinic's language sends every patient of clinic 14, in Seville, a Spanish text for as long as the service is slow, and nothing in its output says why.
For each case the enricher has four moves, and each one moves the problem somewhere else:
- Fail. Reject the event and let the error show; no reminder goes out. On many brokers a rejected message is delivered again, so failing turns into retrying unless something limits it.
- Retry later. Right for the timeout and for the record that has not arrived yet: a reminder due the day before can wait a few minutes. Retries need a limit and growing gaps between attempts, and Retry explains how to set both; past the limit the event takes one of the other moves instead of retrying forever.
- Forward with a marker. Send the event on without the missing fields and with a field that says so, such as
enrichmentset topartial. When only the language is missing, the reminder can still go out in a default language, but every consumer must now handle the partial shape, and when the clinic fields are the ones missing, one that ignores the marker sends a text with a blank where the clinic's name should be. - Hand it to people. A patient with no phone number on file is unlikely to have one a few minutes later, so send the event to a channel the front-desk staff work through, and someone reaches the patient another way. An event whose retries all failed goes to a Dead Letter Channel, with the reason attached.
The choice is made per field, not once for the enricher. A missing address makes the reminder useless; a missing language makes it awkward but still useful.
Which address, and as of when
Clinic 14 moves on 1 December, from its old street to a larger building across the river. A patient books on 20 November for a visit on 9 December. The enricher runs within seconds of the booking and adds the address the directory holds that day, the old one. If the SMS service keeps that message and sends its reminder on 8 December, the patient goes to an empty building.
A lookup returns the reference data as it is when the enricher runs, which is not always the moment that matters. For the reminder, the address that matters is the one valid on the day of the visit. Running the enricher late, just before the reminder is sent, narrows the gap. Asking a directory that keeps dated addresses for clinic 14's address on the date in slot closes it, as long as the move is already recorded there with its effective date.
Other messages need the opposite. If November's events are replayed in January to rebuild November's booking history, an enricher that looks up today's values writes January's addresses into November. When a message must carry the value as it was when the event happened, either the reference source keeps its history and is asked for the value at the event's timestamp, or the producer, if it can read the value, puts it in the event.
Two lookups for every booking
Two lookups for each of the 6,000 bookings the chain takes on a weekday put both reference sources on the path of every message, adding their latency, and when the patient service is down, reminders stop with it. The 40-row clinic directory changes a few times a year, so a cache with reads on a miss, as in Cache-Aside, takes most of that load away; how long an entry lives bounds how long a moved clinic can keep its old address. Patients rarely repeat, so when a backlog of several thousand events arrives together after an outage, fetch the patients for a batch of ids at a time rather than one query per event, the shape N+1 queries: lazy loading, joins & batching warns about. Fetching a payload a sender stored earlier, by a reference in the message, looks like enrichment but is the receiving half of Claim-Check.
The enricher in Message Transformation
In the Message Transformation Challenge, the enricher adds data the target needs from a reference source, and its part takes two nodes, the enricher and a Data Store for the reference data. Place the enricher once, before the handler that needs the fields, rather than a lookup from every handler, and label the lookup edge with what comes back, such as "phone, language, address". The Challenge also asks for a Normalizer, a Message Translator and a Content Filter. Before you submit, look at that lookup edge and ask what your design does when the Data Store does not answer.