Event Mapping

Mapping is used to configure and translate walkerOS events for destinations. It defines if and how to process events, by renaming, structuring, bundling, or ignoring them. It's also checking for consent and validate values.

Config

Besides the destinations general configuration, a mapping config is set to process events individually. The EventConfig is defined as { [entity]: { [action]: EventConfig }}.

A generic "*" can be used to match all entities and/or actions that are not explicitly matched.

{
  // Config
  [entity]: {
    [action]: {
      // EventConfig
      name: "event name",
      data: {
        // ValueConfig
      }
    }
  }
}

Example

Event

{
  event: "order complete",
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  },
  context: {
    shopping: [
      "complete",
      0
    ]
  },
  globals: {
    pagegroup: "shop"
  },
  custom: {
    completely: "random"
  },
  user: {
    id: "us3r",
    device: "c00k13",
    session: "s3ss10n"
  },
  nested: [
    {
      type: "product",
      data: {
        id: "ers",
        name: "Everyday Ruck Snack",
        color: "black",
        size: "l",
        price: 420
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "product",
      data: {
        id: "cc",
        name: "Cool Cap",
        size: "one size",
        price: 42
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "gift",
      data: {
        name: "Surprise"
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    }
  ],
  consent: {
    functional: true
  },
  id: "1741911217000-gr0up-1",
  trigger: "load",
  entity: "order",
  action: "complete",
  timestamp: 1741911217000,
  timing: 3.14,
  group: "gr0up",
  count: 1,
  version: {
    source: "0.0.7",
    tagging: 1
  },
  source: {
    type: "web",
    id: "https://localhost:80",
    previous_id: "http://remotehost:9001"
  }
}

{ event: "order complete", data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 }, context: { shopping: [ "complete", 0 ] }, globals: { pagegroup: "shop" }, custom: { completely: "random" }, user: { id: "us3r", device: "c00k13", session: "s3ss10n" }, nested: [ { type: "product", data: { id: "ers", name: "Everyday Ruck Snack", color: "black", size: "l", price: 420 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "product", data: { id: "cc", name: "Cool Cap", size: "one size", price: 42 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "gift", data: { name: "Surprise" }, context: { shopping: [ "complete", 0 ] }, nested: [] } ], consent: { functional: true }, id: "1741911217000-gr0up-1", trigger: "load", entity: "order", action: "complete", timestamp: 1741911217000, timing: 3.14, group: "gr0up", count: 1, version: { source: "0.0.7", tagging: 1 }, source: { type: "web", id: "https://localhost:80", previous_id: "http://remotehost:9001" } }

Custom Config

{
  order: { // Entity
    complete: { // Action
      // EventConfig
      name: "purchase",
      data: {
        // ValueConfig
        map: {
          event: "event",
          id: 'data.id',
          pageGroup: 'globals.pagegroup',
          quantity: { fn: (e) => e.nested.length },
          products: {
          loop: ['nested', 'data.name']
          },
          user_id: {
            consent: { marketing: true },
            key: "user.id",
            value: "anonymous",
          },
          vip: {
            condition: (e) => e.data.total > 500,
            value: true,
          },
          journeyShopping: {
            key: 'context.shopping.0',
            validate: (value) => typeof value == "string",
          },
          timings: {
            set: ['timestamp', 'timing']
          }
        }
      }
    },
    visible: { batch: 1000, data: "event" },
  },
  '*' : { // Match all other entities
    '*' : { // Match all other actions
      ignore: true
    }
  }
}

{ order: { // Entity complete: { // Action // EventConfig name: "purchase", data: { // ValueConfig map: { event: "event", id: 'data.id', pageGroup: 'globals.pagegroup', quantity: { fn: (e) => e.nested.length }, products: { loop: ['nested', 'data.name'] }, user_id: { consent: { marketing: true }, key: "user.id", value: "anonymous", }, vip: { condition: (e) => e.data.total > 500, value: true, }, journeyShopping: { key: 'context.shopping.0', validate: (value) => typeof value == "string", }, timings: { set: ['timestamp', 'timing'] } } } }, visible: { batch: 1000, data: "event" }, }, '*' : { // Match all other entities '*' : { // Match all other actions ignore: true } } }

Result

Event ignored

Event ignored

Change the event name to order visible and see how the batched mapping is applied after 1 second.

EventConfig

The Destination.Event mapping for each event supports standardized default options. The custom option can be used to set up custom properties for the event and destination's individual settings.

Property	Value	Description
name	string	Renaming of the event (e.g. product add to add_to_cart)
data	object	How to transform the event data.
ignore	boolean	If set to true the event won't get pushed to the destination.
condition	function	A function to check if the mapping should be used.
consent	object	Required states to process the event.
custom	object	Individual settings for a custom destination.
batch	number	Time in ms to bundle the events before calling pushBatch if available.

To disable processing of other events, add {'*': {'*': { ignore: true }}} to the mapping.

The destination event mapping technically uses the mapping utils to create the desired event structure. And the getByPath dot notation to access event properties (e.g. event.data.total).

name

The name property is used to rename the event. It overrides the original event name.

Event

{
  event: "order complete"
}

{ event: "order complete" }

Custom Config

{
  name: "purchase",
  data: "event"
}

{ name: "purchase", data: "event" }

Result

No event yet.

No event yet.

Example: A walkerOS order complete usually becomes a purchase event in GA4 or an order event in Piwik PRO.

data

The data property is used to transform the event data. It fully describes the data structure for the destination. See ValueConfig for detailed usage.

Event

{
  event: "order complete"
}

{ event: "order complete" }

Custom Config

{
  data: {
    map: {
      event: 'event',
      for: { value: 'more info' },
      read: { value: 'ValueConfig' },
    },
  },
}

{ data: { map: { event: 'event', for: { value: 'more info' }, read: { value: 'ValueConfig' }, }, }, }

Result

No event yet.

No event yet.

ignore

Event

{
  event: "order complete"
}

{ event: "order complete" }

Custom Config

{
  ignore: true, // Comment me
  data: 'event',
}

{ ignore: true, // Comment me data: 'event', }

Result

No event yet.

No event yet.

The ignore property is used to ignore the event. If set to true, the event won't get pushed to the destination.

consent

The consent property is used to require a specific state to process the event.

custom

The custom property is used for individual destination settings. In most cases the data property is enough. But in special cases a custom mapping might simplify the configuration.

batch

The batch property is used to bundle the events before pushing them to the destination. A destination must offer a pushBatch method to use this feature. The pushed event(s) are an object with the following properties:

• key: Name of the used mapping rule
• events: An array of the actual events
• data: The transformed event data

Event

{
  event: "order complete"
}

{ event: "order complete" }

Custom Config

{
  batch: 1000,
  data: 'event'
}

{ batch: 1000, data: 'event' }

Result

No event yet.

No event yet.

ValueConfig

The data property is used to transform the event data. It is used to create the required data structure for the destination.

It can create any structure of data. With support for recursive data structures.

key

A key accesses a property from the event context.

Event

{
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  }
}

{ data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 } }

Data config

{
  key: 'data.id'
}

{ key: 'data.id' }

Result

No event yet.

No event yet.

string

A simple string is short for {key: 'value'}. And accesses a property from the event context.

Event

{
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  }
}

{ data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 } }

Data config

'data.total'

'data.total'

Result

No event yet.

No event yet.

value

Used for creating a static value. Can also be used as a fallback if no other mapping resolves a value.

Event

{
  event: "order complete"
}

{ event: "order complete" }

Data config

{
  value: 'static'
}

{ value: 'static' }

Result

No event yet.

No event yet.

map

Used to create an object. The keys are the property names and the values are again a ValueConfig resolving to a value.

Event

{
  globals: {
    pagegroup: "shop"
  },
  context: {
    shopping: [
      "complete",
      0
    ]
  }
}

{ globals: { pagegroup: "shop" }, context: { shopping: [ "complete", 0 ] } }

Data config

{
  map: {
    pageGroup: 'globals.pagegroup',
    shoppingStage: 'context.shopping.0',
  }
}

{ map: { pageGroup: 'globals.pagegroup', shoppingStage: 'context.shopping.0', } }

Result

No event yet.

No event yet.

set

Used to create an array of fixed values. Each item is a ValueConfig resolving to a WalkerOS.Property.

Event

{
  trigger: "load",
  entity: "order",
  action: "complete"
}

{ trigger: "load", entity: "order", action: "complete" }

Data config

{
  set: [
    'trigger',
    'entity',
    'action'
  ]
}

{ set: [ 'trigger', 'entity', 'action' ] }

Result

No event yet.

No event yet.

loop

Loops over the first parameter and maps the second to the current value. It is used for creating an array of dynamic length. Use this to loop over the current event.

Event

{
  nested: [
    {
      type: "product",
      data: {
        id: "ers",
        name: "Everyday Ruck Snack",
        color: "black",
        size: "l",
        price: 420
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "product",
      data: {
        id: "cc",
        name: "Cool Cap",
        size: "one size",
        price: 42
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "gift",
      data: {
        name: "Surprise"
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    }
  ]
}

{ nested: [ { type: "product", data: { id: "ers", name: "Everyday Ruck Snack", color: "black", size: "l", price: 420 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "product", data: { id: "cc", name: "Cool Cap", size: "one size", price: 42 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "gift", data: { name: "Surprise" }, context: { shopping: [ "complete", 0 ] }, nested: [] } ] }

Data config

{
  loop: [
    'nested',
    'data.name'
  ]
}

{ loop: [ 'nested', 'data.name' ] }

Result

No event yet.

No event yet.

condition

Is a function to check if the mapping should be used. It returns a boolean, if it's true the mapping will be used.

Event

{
  event: "order complete",
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  }
}

{ event: "order complete", data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 } }

Data config

{
  condition: (e) => {
    return e.data.total > 100
  },
  key: "event"
}

{ condition: (e) => { return e.data.total > 100 }, key: "event" }

Result

No event yet.

No event yet.

consent

Some values may require an explicit consent state. It can be used to redact values and protect a users privacy by hiding information.

Event

{
  consent: {
    marketing: true
  },
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  }
}

{ consent: { marketing: true }, data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 } }

Data config

{
  consent: {
    marketing: true
  },
  key: 'data.id',
  value: 'redacted',
}

{ consent: { marketing: true }, key: 'data.id', value: 'redacted', }

Result

No event yet.

No event yet.

This can be used to e.g. redact PII like clickIds from a session start event.

fn

A function that returns the value. It receives the current event context, the mapping configuration and the options about the current instance with additional properties as parameters.

Event

{
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  }
}

{ data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 } }

Data config

{
  fn: (event) => {
    return "id is " + event.data.id;
  }
}

{ fn: (event) => { return "id is " + event.data.id; } }

Result

No event yet.

No event yet.

validate

A final check to validate the value. After key, loop, map or set resolved the value, it will be validated with the validate function.

Event

{
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  }
}

{ data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 } }

Data config

{
  validate: (value) => {
    return typeof value == "string"
  },
  key: "data.id",
  value: "fallback"
}

{ validate: (value) => { return typeof value == "string" }, key: "data.id", value: "fallback" }

Result

No event yet.

No event yet.

Execution order

If the data property is an array, the mappings will be executed in the order until a first value is resolved. Usually, a condition is used to check if the mapping should be used. If permission is denied, the static default value would be returned. Then the consent checks if the user granted permission to process the event or value. First, value is used to set the static/default value. Next, fn gets executed. Then a given key or string. If set, either loop, map or loop, map or set is processed. After that, the value gets checked with the validate function. Finally, the value is casted to the correct type. If the validation or casting fails, the value will be either the static default value or the next mapping would be used or ultimately undefined.

tip

Use hooks to modify events before processing.

info

If you need professional support with your walkerOS implementation, check out our services.