Connection property mappings

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 (rotor) incoming event → filters → property mappings → destination function → destination api processing order for device mode destinations (jitsu js) 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 open a connection in the console and expand the property mappings section 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 input { "type" "track", "event" "product viewed", "properties" { "sku" "abc 123", "name" "blue widget" } } output { "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 input { "type" "track", "event" "order completed", "properties" { "products" \[ { "name" "widget", "price" 9 99 }, { "name" "gadget", "price" 24 99 } ] } } output { "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 "jitsu cdp" to properties source system input { "type" "track", "event" "product viewed", "properties" { "sku" "abc 123" } } output { "type" "track", "event" "product viewed", "properties" { "sku" "abc 123", "source system" "jitsu cdp" } } 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 testing mappings the mapping editor includes a test panel where you can paste a sample json event and preview the transformed output before saving error handling missing source path if a source path does not exist on the incoming event, that mapping is skipped and a warning is logged — the event continues to the destination with all other mappings applied this means a misconfigured or overly broad mapping will not silently block event delivery where the warning appears depends on the destination mode cloud mode (rotor) a warning is logged in live events mapping "\<id>" source path "\<path>" does not exist on event — mapping skipped device mode (browser sdk) a console warn is emitted in the browser console — this does not appear in live events use event scope to restrict mappings to only the event types and names where the source path is guaranteed to exist this avoids spurious warnings and keeps your mapping configuration intentional 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's source path is missing, that mapping is skipped and a warning is logged — the function is still called with the partially mapped event 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 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