Transformations

Describe what your gateway changes at each checkpoint, in the same terms as the rest of your tracking plan.

A transformation records what a gateway does to events at one checkpoint. Avo applies the transformations in the order an event travels, so it can work out what each checkpoint should receive.

Define and update transformations

You write transformations through the Avo MCP on a branch, yourself or with your agent, and review and merge them like any other change. The branch diff shows each changed rule as before and after. Describe them the way you’d explain your tags to a colleague. For example:

At the Pinterest output, send transaction_id as order_id. Stop sending search_query to every ad platform output. Require tier on product views sent to Meta.

At the gateway, add event_id to every event.

At the GA4 output, stop sending product_id and variant_id inside items.

At the Meta output, send items as contents, with item_id as id and price as item_price.

Our Meta tag now sends content_ids instead of contents. Update the Meta output on a new branch.

Here’s an export of our GTM container. Compare what each tag sends with our tracking plan and add the differences as transformations on a new branch.

See Set up a gateway for the full setup.

Where a transformation can sit

An event’s shape at an output is the result of every transformation on its path: its source, then the input it entered through, then the gateway, then that output. A checkpoint with no transformation passes events through unchanged.

An input transformation doesn’t change what the source sends. It changes the event on the way into the gateway, and the event on the source still says what developers should send. If a source should stop sending a property, change the event on that source instead of adding a transformation at the input.

What a transformation can change

The Transformations tab shows the transformations checkpoint by checkpoint, in the order they run: inputs, then the gateway, then outputs. At each checkpoint, they are grouped by what they touch (events, properties or bundles) and by what they do: Added, Required, Changed or Dropped.

Each checkpoint is set to All sent or Allow list, separately for events and properties. With All sent (the default), everything that arrives passes on, apart from what a rule drops. With Allow list, only what’s on the list passes. See Choose what passes through.

Events

• Changed. The event is sent under a different name from this checkpoint on, for example Order Completed sent to Meta as Purchase.
• Dropped. At a checkpoint set to Allow list, events that aren’t on the list don’t get through from here on. An event on the list keeps all its variants. Renaming an event doesn’t put it on the list.

Properties

A property rule applies to every event at the checkpoint that carries the property.

• Added (enrich in the MCP). The gateway adds the property to every event, not only the ones that already send it. Use it for values the gateway fills in, such as a click id read from a cookie. It’s always sent, unless you mark it sometimes sent.
• Required (require). Every event that reaches this checkpoint must already carry the property. The gateway never adds it, so the sources that feed the checkpoint have to. For example, if a Meta audience is built on tier, requiring tier at the Meta output says that every product view reaching Meta must carry it. If a source doesn’t send tier, that’s the gap to fix at the source.
• Changed (tighten). The property is modified only where it already arrives, and never added. At a checkpoint set to Allow list, a property that’s on the list with no change keeps arriving where it’s already sent. A change can:
  • Rename the property, for example transaction_id sent as order_id.
  • Change its presence by marking it sometimes sent.
  • Constrain its value:
    • Pin it to one value.
    • Refine its allowed values by ruling out values it otherwise allows.
    • Require a regex.
• Dropped. The property doesn’t get through from this checkpoint on. This holds when the property arrives inside a bundle too, and the bundle’s other properties are still sent. Dropping is different from clearing a rule: clearing removes this checkpoint’s rule, so the property goes back to what it inherits from earlier checkpoints.

An Added, Required or Changed rule can rename the property and pin its value as well.

Keys inside an object

A key rule changes one key inside an object property, such as product_id inside items. You name the object and then the key. When the object is a list of objects, the rule applies to every element of the list.

• Changed. The key is sent under a different name from this checkpoint on, for example price inside items sent as item_price.
• Dropped. The key doesn’t get through from this checkpoint on. The object’s other keys are still sent.

A key rule changes that key in that object only. A top-level property with the same name, or the same key inside another object, is unchanged. Keys can sit at any depth, inside an object inside another object.

Key rules work together with the other rules at a checkpoint:

• Renaming the object and its keys. You can rename an object and some of its keys at the same checkpoint, for example items sent as contents, with item_id as id and price as item_price.
• A dropped key stays dropped. A key dropped at one checkpoint can’t come back at a later one, so a later rule on the same key has no effect.
• Dropping the whole object. Dropping the object drops all its keys, so a key rule under it has no effect.
• Allow list. At a checkpoint set to Allow list, an object on the list keeps all its keys, unless a key rule drops one.
• Two keys, one name. Two keys of the same object can’t be sent under the same name at a checkpoint. If a rename would do that, the Avo MCP rejects the change and names both keys.

The Transformations tab shows a key rule by its path, with a dot between the object and the key, such as items.product_id or items.price → items.item_price. Paths use the names in your tracking plan. A key rule that has no effect is shown muted with the reason beneath it, for example “covered by the drop of items”, and so is a key rule at a checkpoint where no event brings the object.

A property that arrives at a checkpoint only inside an object can’t be dropped or renamed at the top level there, because the event doesn’t carry it at the top level. If you or your agent try, the Avo MCP rejects the change and names the key path to use instead, such as items.product_id. A rule that adds the property is the exception, since the gateway then sends it at the top level itself. A top-level rule written before key rules existed stays as it is, and the Transformations tab marks it “no effect here” with the path the property arrives on.

Inspector checks each output against the object as the gateway sends it there. A dropped key is no longer reported missing at that output, and a renamed key is expected under its new name.

Among gateway transformation rules, a key rule can only drop or rename a key. Other transformations, such as pinning a key’s value or requiring a key, apply to top-level properties only.

Property bundles

• Added. This checkpoint adds a property bundle, so all its properties are sent from here on, including ones no rule names.
• Dropped. The bundle’s properties don’t get through from this checkpoint on.

More transformation types are coming. If you’re missing one, let us know at support@avo.app or in the chat bubble in the app.

Describe why a transformation exists

Any transformation can carry a short description: why the gateway does this, in words the next person to read it will understand. Hover a transformation on the Transformations tab to read its description, with who last updated it, when and on which branch. A transformation without one says so.

Descriptions are written through the Avo MCP on a branch, like the transformations themselves, and the branch diff shows a changed description word by word. For example, ask your agent:

At the Meta output, stop sending content_category and describe why: Meta rejects it on server events.

A key rule takes a description like any other transformation:

At the GA4 output, stop sending product_id inside items and describe why: GA4 reads the product from item_id.

A description is most useful on a transformation that drops something, so nobody mistakes a deliberate drop for a mistake and adds the property back. A checkpoint can also carry one description of its own, shown at the top of its card on the Transformations tab, in the branch diff and in what your agent reads.

Avo is the analytics governance platform for product data that lets you define it consistently, implement it correctly and trust it everywhere. Using an AI agent? Connect it to the Avo MCP at https://mcp.avo.app/mcp and it can write these transformations for you on a branch and tell you what an event looks like after them.