Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Message Translator

Two systems describe the same fact in different shapes, and a Message Translator converts each message from the sender's format into the receiver's so that neither has to change its own model. The syntax is the easy part; the hard part is the decisions hidden in the mapping.

What HR sends, what payroll expects

A company keeps its employees in an HR system and pays them through an outside payroll provider. When a salary or a contract changes, HR publishes an event. This is the one it published for a new hire starting in November:

  • HR sends: { "employeeId": "E-20417", "annualSalary": 54000, "currency": "EUR", "effectiveFrom": "2026-11-01T00:00:00+01:00", "status": "ACTIVE" }
  • Payroll expects: { "worker_ref": "20417", "gross_monthly_cents": 450000, "start_date": "2026-11-01", "emp_status": "A" }

It is the same fact, said two ways. The names differ, the salary is a yearly amount in euros on one side and a monthly amount in cents on the other, one side sends a moment in time and the other wants a calendar date, and the status vocabularies do not match. Neither side is wrong. HR models people and contracts; the provider models pay runs for hundreds of client companies, and it will not change its format for one of them.

Neither side has to move

You could teach the HR system to write the provider's format. Then HR's code knows a vendor's field names, and switching providers means changing the HR system. Writing the conversion into the provider is not on offer at all. So the conversion becomes a step of its own, between the two: a Message Translator takes each message in the sender's format and emits the same content in the receiver's format, so each side keeps its own model. It is the messaging form of the Adapter pattern: the Adapter wraps a class so its interface fits the caller, and the translator does the same for a message travelling on a channel.

HR event in, payroll change out

The translator is the only place that knows both formats. HR publishes in its own shape, and the provider receives only its own.

More than renaming fields

The example looks like renaming fields. It touches more than that, and each part can be wrong on its own:

  • Field names: employeeId becomes worker_ref, and the E- prefix goes.
  • Structure: HR could just as well nest the salary inside a contract object; the provider wants one flat record.
  • Data types and units: a yearly amount in euros becomes a monthly amount in integer cents; a timestamp with an offset becomes a plain date.

Had the provider wanted XML or a CSV line, the syntax would change as well, and a name like Zoë Müller would have to survive a change of character encoding; those conversions are mechanical. The types and units are where the decisions are.

Decisions hiding in the mapping

Take the salary. The provider's record has no currency because this company's pay runs are in euros only, so the translator checks that currency is EUR and rejects anything else. 54,000 divides cleanly into 4,500 a month, or 450,000 cents. A salary of 50,000 does not: 5,000,000 cents over twelve months is 416,666 cents with 8 cents left over. Rounding down underpays by 8 cents a year; spreading the remainder needs a rule across months that a translator seeing one message at a time cannot keep alone. Before rounding there is a harder question: twelfths of what? In the Netherlands, for instance, employers generally pay a holiday allowance on top of the monthly wage, and an annual figure may be quoted with or without it. Nothing in the message says which; somebody has to decide and write it into the mapping.

The date is harder to spot. HR's timestamp is midnight on 1 November in Amsterdam, which is 23:00 on 31 October in UTC. A translator that converts every timestamp to UTC and then keeps the date part sends 2026-10-31, and the employee starts a day early, possibly in the previous pay period. The fix is a decision, not a library call: agree that an effective date is a calendar date in the employer's time zone, and translate it as one.

Then a status with no equivalent. HR has ON_NOTICE for someone who has resigned and is still employed until a known date; the provider knows only A, S and T (active, on leave without pay, terminated). Mapping it to T stops pay early. Mapping it to A is right for now, as long as HR later sends the termination with its effective date. A default branch that turns any unknown code into A means that when HR adds SECONDMENT next year, every seconded employee is filed as ordinary active staff without a word. An unknown value is better rejected: the message goes aside with the reason attached, for someone to fix, and the rest keep flowing.

Fields travel badly in both directions. Suppose HR's event also carried a manager and a preferred name, which the provider has no use for. If the translator copies across whatever it does not recognise, those fields reach the provider unannounced, in HR's shape, and the provider may start reading them. Build the output from the receiver's fields and leave everything else out on purpose. The provider also requires a tax code that HR does not send. A constant would be wrong for some employees, and looking the code up before translating is the job of a Content Enricher.

Some information does not survive the trip back: 416,666 cents times twelve returns as 4,999,992, not 5,000,000, and HR's UNPAID_LEAVE and SABBATICAL, both sent as S, cannot be told apart again. When the provider reports what it has on file for HR to reconcile, the reverse side has to know what was lost: amounts are compared with a tolerance for the rounding, and a status only against the original value kept next to the translated one.

Your translator in the Challenge

In the Message Transformation challenge, the Message Translator is the step that maps between two systems' schemas. Place it on the path into the system that receives, and label its incoming and outgoing edges with the two shapes it converts between, so the diagram says which side owns which format and no system reads the other's native shape. The Challenge also asks for a Normalizer, a Content Enricher and a Content Filter; decide which of them runs before your translator and which after.

Beyond one pair

A translator whose real purpose is to keep a foreign model out of your own domain model, not only to change a format, is part of an Anti-Corruption Layer. When HR changes its own event shape over time, the translator may have to read old and new versions side by side while both are still in flight; how to make that change safely is the business of Schema evolution: event formats & compatibility.

One translator per pair of systems is fine for one pair. The same HR system soon feeds a pension provider, a benefits platform and the badge system, each with its own format, and each new sender or receiver adds translators to write and to keep in step. Past a handful of systems, a shared canonical format in the middle can cost less, depending on how many pairs actually exchange messages, and that is what the Normalizer article builds.

Practice this