/walkeros-understanding-mapping

name: walkeros-understanding-mapping
description: Use when transforming walkerOS events in the flow (source→collector or collector→destination), configuring data/map/loop/set/condition/policy, or using $code: syntax in JSON configs.

Understanding walkerOS Mapping

Overview

Mapping transforms data at multiple points in the walkerOS flow:

1. **Source → Collector**: Transform raw input (HTTP requests, dataLayer pushes) into walkerOS events 2. **Collector → Destination**: Transform walkerOS events into vendor-specific formats

**Core principle:** Mapping is the universal transformation layer. Same strategies work everywhere in the flow.

Core Functions

See [packages/core/src/mapping.ts](../../packages/core/src/mapping.ts) for implementation.

| Function | Purpose | | ----------------------------------------------- | ------------------------------------------- | | `getMappingEvent(event, rules)` | Find mapping rule for an event | | `getMappingValue(value, data, { collector })` | Transform a value using mapping config | | `processEventMapping(event, config, collector)` | Unified processing for sources/destinations |

processEventMapping Flow

1. Apply config.policy (modifies event)
2. Find matching rule via getMappingEvent()
3. Apply rule.policy (modifies event)
4. Transform config.data (global)
5. Check rule.ignore (short-circuits if true)
5b. Read rule.silent (informational - destination honors it)
6. Override event.name if rule.name
7. Transform rule.data (event-specific)

---

Configuration Hierarchy

Mapping.Config (Top Level)

interface Config {
  consent?: Consent; // Required consent for ALL events
  data?: Value; // Global data transformation
  include?: string[]; // Event sections to flatten into context.data
  policy?: Policy; // Pre-processing for ALL events
  mapping?: Rules; // Event-specific rules
}

Mapping.Config.include

`include` lists event sections to **flatten** into the destination's `PushContext.data` before the rule runs. Sections are top-level keys of the event (`globals`, `user`, `consent`, `data`, `context`, `nested`, `source`, `custom`). The runtime helper `flattenIncludeSections` (in `packages/core/src/include.ts`) handles the merge.

Use this when your mapping needs values from multiple event sections without plumbing each path through a `key:`/`map:` config. `include` is also available on `Mapping.Rule` (rule-level overrides config-level).

{
  include: ['globals', 'user'],
  mapping: {
    page: {
      view: {
        // user.id and globals.* are now reachable via top-level paths in
        // data/key/map values, e.g. `key: 'id'` for user.id.
        data: { map: { user_id: 'id', site: 'language' } },
      },
    },
  },
}

Mapping.Rule (Per Event)

interface Rule {
  name?: string; // Override event name
  data?: Value; // Event-specific data transformation
  include?: string[]; // Event sections to flatten into context.data (rule-level)
  ignore?: boolean; // Skip this event entirely (no processing, no push)
  silent?: boolean; // Process settings side effects, skip destination default push
  policy?: Policy; // Event-specific pre-processing
  condition?: Function; // Match condition (for arrays)
  consent?: Consent; // Not enforced yet; config.consent gates a destination
  settings?: unknown; // Custom event configuration
  batch?: number; // Batch size for grouping
  extend?: RulePatch; // Config-layer merge onto a package-shipped default rule
  remove?: string[]; // Output-layer: dotted paths stripped from the final payload
}

`extend` and `remove` (patching package-shipped rules)

Some packages ship their own default mapping rules. A user rule at the same key normally replaces the default in full. Two keywords change that:

• **`extend`** (config layer): a partial rule deep-merged onto the

package-shipped default at init, before any event is evaluated. A `null` value clears an inherited field. Lets you add or override one field while keeping the rest.

• **`remove`** (output layer): dotted paths stripped from the produced payload

after evaluation, applied last. Useful for dropping PII or vendor-reserved fields without rewriting the full rule.

A rule with **neither** keyword keeps the standard replace behavior.

See the [website mapping docs](/docs/mapping/rule#patching-package-shipped-rules) for the authoritative reference and the GA4 example.

{
  "purchase": {
    "extend": {
      "data": { "map": { "affiliation": "params.ep.affiliation" } }
    },
    "remove": ["currency"]
  }
}

Silent vs Ignore

Both flags control rule behavior but have different semantics:

• `ignore: true` - the rule matched but **nothing happens**. No data transform,

no destination call, no side effects. Use for suppression.

• `silent: true` - the rule matched and the destination `push()` **is** called.

`settings.identify`, `settings.revenue`, `settings.group`, etc. still run. Only the destination's default forwarding call (e.g. `track()`, `capture()`, `event()`) is suppressed. Use for "identify without an event" style flows.

If both flags are set on the same rule, `ignore` wins.

Common use case: a `user login` event that should call `amplitude.identify()` but should not create a separate `track("user login")` event in Amplitude.

Mapping.ValueConfig (Value Extraction)

interface ValueConfig {
  key?: string; // Extract from path
  value?: Primitive; // Static fallback value
  fn?: Function; // Compute the value from the source
  map?: Record; // Object transformation
  loop?: [path, config]; // Array transformation
  set?: Value[]; // Create array from values
  condition?: Function; // Conditional extraction
  consent?: Consent; // Consent-gated extraction
  validate?: Function; // Value validation