OpenParable
Skip to content
← Back to skills

Walkeros Mapping Configuration

Apps & Automation
walkeros-mapping-configuration

Walkeros Mapping Configuration is an Agent Skill for apps & automation published in the elbwalker/walkerOS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when configuring walkerOS event mappings for specific use cases. Provides recipes for GA4, Meta, custom APIs, and common transformation patterns.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/elbwalker/walkerOS/blob/HEAD/skills/walkeros-mapping-configuration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/walkeros-mapping-configuration, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Mapping Configuration Recipes

Prerequisites

Read understanding-mapping first for core concepts.

Quick Reference

I want to...Use this pattern
Rename event{ name: 'new_name' }
Extract nested value'data.nested.value'
Set static value{ value: 'USD' }
Transform value{ fn: (e) => transform(e) }
Build object{ map: { key: 'source' } }
Process array{ loop: ['source', { map: {...} }] }
Gate by consent{ key: 'data.email', consent: { marketing: true } }
First defined value (fallback)[{ key: 'data.sku' }, { key: 'data.id' }]
Add a field to a default rule{ extend: { data: { map: { x: 'path' } } } }
Drop a field from output{ remove: ['field.path'] }

Common Recipes

GA4 / gtag

Product view → view_item:

product: {
  view: {
    name: 'view_item',
    data: {
      map: {
        currency: { value: 'USD' },
        value: 'data.price',
        items: {
          loop: [
            'nested',
            {
              map: {
                item_id: 'data.id',
                item_name: 'data.name',
                item_category: 'data.category',
                price: 'data.price',
                quantity: { value: 1 },
              },
            },
          ],
        },
      },
    },
  },
}

Order complete → purchase:

order: {
  complete: {
    name: 'purchase',
    data: {
      map: {
        transaction_id: 'data.orderId',
        value: 'data.total',
        currency: 'data.currency',
        items: {
          loop: [
            'nested',
            {
              map: {
                item_id: 'data.id',
                item_name: 'data.name',
                price: 'data.price',
                quantity: 'data.quantity',
              },
            },
          ],
        },
      },
    },
  },
}

Meta Pixel

Product view → ViewContent:

product: {
  view: {
    name: 'ViewContent',
    data: {
      map: {
        content_ids: { fn: (e) => [e.data.id] },
        content_type: { value: 'product' },
        content_name: 'data.name',
        value: 'data.price',
        currency: { value: 'USD' },
      },
    },
  },
}

Order complete → Purchase:

order: {
  complete: {
    name: 'Purchase',
    data: {
      map: {
        content_ids: { fn: (e) => e.nested?.map((n) => n.data.id) ?? [] },
        content_type: { value: 'product' },
        value: 'data.total',
        currency: 'data.currency',
        num_items: { fn: (e) => e.nested?.length ?? 0 },
      },
    },
  },
}

Custom API Destination

Transform to REST API format:

'*': {
  '*': {
    name: { fn: (e) => `${e.entity}_${e.action}` }, // page_view
    data: {
      map: {
        eventName: 'name',
        eventData: 'data',
        userId: 'user.id',
        sessionId: 'user.session',
        timestamp: 'timestamp',
        metadata: {
          map: {
            consent: 'consent',
            globals: 'globals',
          },
        },
      },
    },
  },
}

Conditional Mapping

Different mapping based on event data:

order: {
  complete: [
    // High-value orders get extra tracking
    {
      condition: (e) => (e.data?.total ?? 0) > 500,
      name: 'high_value_purchase',
      data: {
        map: {
          value: 'data.total',
          priority: { value: 'high' },
          notify: { value: true },
        },
      },
    },
    // Standard orders
    {
      name: 'purchase',
      data: { map: { value: 'data.total' } },
    },
  ],
}

Patching Package-Shipped Rules (extend / remove)

Some packages (such as @walkeros/transformer-ga4) ship default mapping rules. Normally a user rule at the same key replaces the default in full. Use extend or remove to patch instead.

Two layers, two keywords:

  • extend runs at init (config layer): deep-merges a partial rule onto the shipped default. A null value clears an inherited field.
  • remove runs after evaluation (output layer): strips dotted paths from the final data payload. Applied last, always wins.

A rule with neither keyword keeps the existing replace behavior.

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

This keeps all fields the package ships for purchase, adds affiliation, and strips currency from the output.

For the full reference and the two-layer model, see Mapping.Rule docs.

Value[] Fallback Chains

At any value position, an array of values is a fallback chain: the first entry that resolves to a defined value wins.

{
  "item_id": [
    { "key": "data.sku" },
    { "key": "data.id" },
    { "value": "unknown" }
  ]
}

Use this to try multiple source fields before falling back to a constant.

Consent-Gated Fields

Only include PII if consent granted:

user: {
  login: {
    name: 'login',
    data: {
      map: {
        method: 'data.method',
        // Only include email if marketing consent
        email: {
          key: 'user.email',
          consent: { marketing: true },
        },
        // Only include user ID if functional consent
        userId: {
          key: 'user.id',
          consent: { functional: true },
        },
      },
    },
  },
}

Wildcard Patterns

Catch-all for unmatched events:

// Any product action
product: {
  '*': {
    name: { fn: (e) => `product_${e.action}` },
    data: 'data',
  },
}

// Any click on any entity
'*': {
  click: {
    name: 'element_click',
    data: {
      map: {
        element_type: 'entity',
        element_id: 'data.id',
      },
    },
  },
}

Source-Side Mapping

Transform HTTP input to walkerOS event:

// In source config
{
  mapping: {
    // Map incoming field names to walkerOS structure
    name: { fn: (input) => `${input.entity} ${input.action}` },
    data: 'payload',
    user: {
      map: {
        id: 'userId',
        session: 'sessionId',
      },
    },
  },
}

Debugging Tips

  1. Event not mapping? Check entity/action match exactly (case-sensitive)
  2. Data missing? Verify source path exists: 'data.nested.field'
  3. Function errors? Add null checks: e.data?.price ?? 0
  4. Array empty? Confirm nested array exists and has items

Related Skills

Reference: