Skip to content

Translate events between modules and applications

A translation lets one area react to another without either reaching into the other. They share only a fact. In Acme Commerce, Catalog publishes ProductPriceChanged as a public event, and Storefront and Sales bring it in. For why modules and applications stay separate, read Automations and translations.

A translation is a Translator slice. It goes one of two ways:

  • An output translation sends events out to others, by publishing a public event.
  • An input translation brings events in from outside.

You can change the direction later with Make this an input translation or Make this an output translation. Studio warns you about the configuration the change invalidates.

  1. In a feature header, select Add, then Add Slice.

  2. Choose Translator: Translates external events into internal commands.

  3. Name the slice and choose its direction.

Publish a public event (output translation)

Section titled “Publish a public event (output translation)”
  1. On the output translation, add the private event the application records and wants to publish.

  2. Select Add projection. It maps the private event onto the public contract.

  3. Choose Publish as this translation’s public event. In Acme Catalog this is how ProductPriceChanged is published. The event is now Public: the contract this application publishes.

A public event is a promise to others, so keep its properties stable. Only an output translation publishes. You can see an event’s visibility in the event editor.

The PublishPriceChange slice on the Catalog board: the events ProductDrafted and ProductPriceSet on the left, the PriceChangePublisher projection of 2 events beside them, and the ProductPriceChanged event marked PUBLIC below; the PublishRetirement slice sits to its right
In Acme Catalog, the projection card PriceChangePublisher (a projection of 2 events) turns ProductDrafted and ProductPriceSet into ProductPriceChanged. The PUBLIC tag under the event name shows it is published. PublishRetirement next to it does the same for retirements.
The Warehouse board zoomed out, with the PublishDispatch output translation in the middle publishing ShipmentDispatched
Acme Warehouse publishes ShipmentDispatched with an output translation, PublishDispatch, in the Dispatch feature. Its event is tagged public.
  1. On the input translation, select Add external event to translate from.

  2. Search with Search external events… and pick the public event, such as ProductPriceChanged from Acme Catalog.

  3. Say what to do with it:

    • Add command: a reactor carries out a command in your area. Read about commands in Commands and rules.
    • Add CDC: capture outside data as your own facts.

Besides another application’s public events, an input translation can capture records from outside, such as an API polled on a schedule, a Webhook or a message Topic. The translation editor opens from the capture or projection card. It has three columns:

  • Outside: what the source delivers, in its own words.
  • Captured record: your shape of it, keyed by the field that tells one record from another. Steps rename fields, build values from templates, translate values through a table or split a value.
  • Our events: what the capture records, each with a when (the first time a key is seen, when fields change, and so on).
The UpdateAvailability slice on the Storefront board: the outside event StockLevelChangedAtStorefront on the left, the AvailabilityFeed card marked CDC with 1 event, and the AvailabilityChanged event it records below; the RetirementFeed capture is to the left of it
A capture appears as a card marked CDC with the number of events it captures. Here AvailabilityFeed takes the outside event StockLevelChangedAtStorefront and records AvailabilityChanged.

Drag an outside field onto a field of the record, and a field of the record onto an event or onto its when. Try it runs the capture on the canvas with example input, and Save as specification keeps the run on the slice, to be run again whenever the design changes.

The output translation shows its public event. The input translation shows the external event and what it leads to. Open the public event in the event editor: its visibility says Public.