understanding-mapping
Use when transforming events at any point in the flow (source→collector or collector→destination), configuring data/map/loop/condition, or understanding value extraction. Covers all mapping strategies.
When & Why to Use This Skill
This Claude skill provides a comprehensive guide to walkerOS mapping, a universal transformation layer for event data. It enables developers to seamlessly configure data transformations at any point in the flow—from source to collector or collector to destination—using strategies like conditional logic, key extraction, and array processing.
Use Cases
- 1. Data Normalization: Transform raw inputs such as HTTP requests or dataLayer pushes into standardized walkerOS events for consistent tracking.
- 2. Vendor Integration: Map internal walkerOS events into specific vendor formats (e.g., GA4, Facebook Pixel) using custom transformation functions and object structures.
- 3. Complex Data Handling: Process nested data structures and arrays using loops and recursive mapping to ensure all relevant event details are captured.
- 4. Privacy Compliance: Implement consent-gated mapping to automatically filter or include specific data points based on the user's marketing or functional consent status.
| name | understanding-mapping |
|---|
Understanding walkerOS Mapping
Overview
Mapping transforms data at multiple points in the walkerOS flow:
- Source → Collector: Transform raw input (HTTP requests, dataLayer pushes) into walkerOS events
- 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 for implementation.
| Function | Purpose |
|---|---|
getMappingEvent(event, rules) |
Find mapping config for an event |
getMappingValue(value, config) |
Transform a value using mapping config |
Event Mapping
Match events to transformation rules by entity and action.
const mapping = {
// Exact match
product: {
view: { name: 'view_item' },
add: { name: 'add_to_cart' },
},
// Wildcard: any action
foo: {
'*': { name: 'foo_interaction' },
},
// Wildcard: any entity
'*': {
bar: { name: 'generic_bar' },
},
};
Conditional Mapping
Array of conditions, first match wins:
order: {
complete: [
{
condition: (event) => event.data?.value > 100,
name: 'high_value_purchase',
},
{ name: 'purchase' }, // Fallback
],
}
Value Mapping Strategies
Key Extraction (string)
Extract nested property from event:
'user.id'; // → event.user.id
'data.price'; // → event.data.price
'context.stage.0'; // → first element of stage array
Static Value
Fixed value regardless of event:
{
value: 'USD';
}
{
value: 99.99;
}
{
value: true;
}
Function Transform
Custom transformation logic:
{
fn: (event) => event.data.price * 100;
} // cents
{
fn: (event) => event.user.email?.split('@')[1];
} // domain
Object Map
Transform to new structure:
{
map: {
item_id: 'data.id',
item_name: 'data.name',
price: 'data.price',
currency: { value: 'USD' },
category: { fn: (e) => e.nested?.[0]?.data?.name }
}
}
Array Loop
Process arrays (e.g., nested entities):
{
loop: [
'nested', // Source array path
{
map: {
item_id: 'data.id',
quantity: 'data.quantity',
},
},
];
}
Consent-Gated
Only return value if consent granted:
{
key: 'user.email',
consent: { marketing: true }
}
Complete Example
const destinationConfig = {
mapping: {
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',
},
},
],
},
},
},
},
},
},
};
Example-Driven Development
When creating sources or destinations, define mapping examples BEFORE implementation:
1. Create Input/Output Examples First
// src/examples/inputs.ts - What we receive
export const pageViewInput = {
event: 'page_view',
properties: { page_title: 'Home', page_path: '/home' },
};
// src/examples/outputs.ts - What we must produce
export const pageViewOutput = {
method: 'track',
args: ['pageview', { url: '/home', title: 'Home' }],
};
2. Define Mapping to Connect Them
// src/examples/mapping.ts
export const defaultMapping = {
page: {
view: {
name: 'pageview',
data: {
map: {
url: 'data.path',
title: 'data.title',
},
},
},
},
};
3. Test Against Examples
test('produces expected output', () => {
const result = transform(examples.inputs.pageViewInput);
expect(result).toMatchObject(examples.outputs.pageViewOutput);
});
See:
- create-destination skill - Full workflow
- create-source skill - Full workflow
Where Mapping Lives
| Location | Purpose |
|---|---|
| Source config | Transform raw input → walkerOS events |
| Destination config | Transform walkerOS events → vendor format |
src/examples/mapping.ts |
Default mapping examples (example-driven) |
packages/core/src/mapping.ts |
Core mapping functions |
apps/quickstart/src/ |
Validated examples |
Related
Skills:
- understanding-events skill - Event structure to map from/to
- understanding-sources skill - Source-side mapping
- understanding-destinations skill - Destination-side mapping
Source Files:
- packages/core/src/mapping.ts - Implementation
Examples:
- apps/quickstart/src/ - Validated examples
Documentation:
- Website: Mapping - User-facing docs
- walkeros.io/docs/destinations/event-mapping - Public documentation