Connection property mappings

property mappings let you rename, move, or inject properties on events before they reach a destination — without writing code mappings are configured per connection and work for both device mode (client side) and cloud mode (server side) destinations how it works each mapping defines a transformation that copies a value from one path on the event to another, or injects a static string value mappings run in order and each one sees the result of the previous mapping processing order for cloud mode destinations incoming event → filters → property mappings → destination function → destination api processing order for device mode destinations incoming event → property mappings → destination plugin → third party sdk mappings are applied before destination functions, so any mapped values are available on the event when your function code runs configuring mappings in the hub, click on menu icon for the destination then click view connected streams to open the edit connections page for that destination then click the edit icon and expand the property mappings section edit connections page each mapping has the following fields field description enabled toggle to enable or disable the mapping without deleting it event scope which events the mapping applies to all events, track, page, or identify for track events, you can optionally specify an event name (e g , "order completed") source either a property path on the event, or a static value string destination path the path where the value will be written on the event path syntax use dot notation to reference nested properties properties sku — the sku field inside properties context device type — deeply nested path properties products 0 name — array index access use \[] to iterate over arrays properties products \[] name — collects name from every element, producing an array of values properties orders \[] items \[] sku — nested array iteration static value mappings instead of copying from a source path, you can inject a fixed string value toggle the source type to static value and enter the value this is useful for tagging events with metadata like a source system identifier examples renaming a property map properties sku to properties product id event from site { "type" "track", "event" "product viewed", "properties" { "sku" "abc 123", "name" "blue widget" } } transformed event { "type" "track", "event" "product viewed", "properties" { "sku" "abc 123", "name" "blue widget", "product id" "abc 123" } } note that the original sku field is preserved mappings copy values — they do not remove the source array iteration map properties products \[] name to properties products \[] title event from site { "type" "track", "event" "order completed", "properties" { "products" \[ { "name" "widget", "price" 9 99 }, { "name" "gadget", "price" 24 99 } ] } } transformed event { "type" "track", "event" "order completed", "properties" { "products" \[ { "name" "widget", "price" 9 99, "title" "widget" }, { "name" "gadget", "price" 24 99, "title" "gadget" } ] } } static value injection map static value "my ad platform" to properties source system event from site { "type" "track", "event" "product viewed", "properties" { "sku" "abc 123" } } transformed event { "type" "track", "event" "product viewed", "properties" { "sku" "abc 123", "source system" "my ad platform" } } scoped mapping a mapping with event scope set to track and event name set to order completed will only apply to order completed track events all other events pass through unchanged error handling missing source path if a source path does not exist on the incoming event, the mapping fails and the event is dropped — it will not be sent to the destination this is intentional a missing path usually indicates the event does not match the expected schema, so sending a partially mapped event could cause data quality issues downstream in the live events log cloud mode an error is logged with the message property mapping failed mapping "\<id>" source path "\<path>" does not exist on event and the event appears as dropped device mode a console error is logged and the event is silently excluded to avoid dropped events, use event scope to restrict mappings to only the event types and names where the source path is guaranteed to exist validation errors mappings are validated when you save the connection the following conditions will prevent saving a mapping has neither a source path nor a static value a mapping has both a source path and a static value the destination path is blank the destination path targets a protected field (see below) two enabled mappings write to the same destination path within the same event scope more than 50 mappings on a single connection mappings and functions mappings run before destination functions in the processing chain this means your destination function receives the event with all mappings already applied mapped properties are available for the function to read and use if a mapping fails, the function is never called — the event is dropped before it reaches the function this is useful when a destination function expects properties in a specific shape instead of modifying the function to handle different source schemas, you can use mappings to normalize the event first connections table connections with active mappings display badges in the mappings column on the connections list page each badge shows the mapping number, and hovering reveals the source to destination path connections table showing mapping details limitations constraint detail maximum mappings 50 per connection protected fields cannot write to type , messageid , writekey , receivedat , or sentat static values are strings static value mappings always inject a string; no type coercion is performed no value removal mappings copy values to new paths but do not delete the original source path no conditional logic mappings cannot branch based on values; use event scope to filter by event type/name, or write a function for complex logic ordering matters mappings run sequentially; a later mapping can read a path written by an earlier one, but reordering may change results shallow clone the mapping engine creates a shallow clone of the event; deeply nested reference types are shared with the original