--- title: Connection property mappings slug: connection-property-mappings docTags: createdAt: 2026-02-26T20:42:29.393Z --- # 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):** ```javascript Incoming Event → Filters → Property Mappings → Destination Function → Destination API ``` **Processing order for device-mode destinations (jitsu-js):** ```javascript 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:** ```json { "type": "track", "event": "Product Viewed", "properties": { "sku": "ABC-123", "name": "Blue Widget" } } ``` **Output:** ```json { "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:** ```json { "type": "track", "event": "Order Completed", "properties": { "products": [ { "name": "Widget", "price": 9.99 }, { "name": "Gadget", "price": 24.99 } ] } } ``` **Output:** ```json { "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:** ```json { "type": "track", "event": "Product Viewed", "properties": { "sku": "ABC-123" } } ``` **Output:** ```json { "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 "": source 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: 1. Your destination function receives the event with all mappings already applied 2. Mapped properties are available for the function to read and use 3. 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 |