Mapping

The Mapping.Config stores all individual Mapping.EventConfig configurations for each entity-action event. The getMappingEvent function returns the matching event mapping while the getMappingValue is used to resolve a Mapping.Value settings for a specific property to return an actual value. The custom property is used by each destination individually.

getMappingEvent

getMappingEvent(event: string, mapping?: Mapping.Config<unknown>): EventMapping returns the matching eventMapping configuration and the used mappingKey for the given entity-action event name. If no mapping is found, it will return an empty object. An explicit key is favored over an asterisk * key. If available a condition will be checked to determine if the EventConfig applies. It's used by the sources.

Configuration

await getMappingEvent(
  { event: 'entity action' },
  {
    entity: {
      action: { name: 'entity_action' },
    },
  }
);

await getMappingEvent( { event: 'entity action' }, { entity: { action: { name: 'entity_action' }, }, } );

Result

{
  eventMapping: {
    name: "entity_action"
  },
  mappingKey: "entity action"
}

{ eventMapping: { name: "entity_action" }, mappingKey: "entity action" }

Specify multiple Mapping.EventConfig as an array and use condition to check which EventConfig should be used. To test uncomment the globals property.

Configuration

await getMappingEvent(
  {
    event: 'order complete',
    // globals: { env: 'prod' },
  },
  {
    order: {
      complete: [
        {
          // EventConfig only for production
          condition: (event) =>
            event.globals?.env === 'prod',
          ignore: true,
        },
        { name: 'purchase' }, // Fallback EventConfig
      ],
    },
  }
);

await getMappingEvent( { event: 'order complete', // globals: { env: 'prod' }, }, { order: { complete: [ { // EventConfig only for production condition: (event) => event.globals?.env === 'prod', ignore: true, }, { name: 'purchase' }, // Fallback EventConfig ], }, } );

Result

{
  eventMapping: {
    name: "purchase"
  },
  mappingKey: "order complete"
}

{ eventMapping: { name: "purchase" }, mappingKey: "order complete" }

getMappingValue

getMappingValue(event: WalkerOS.Event, mapping: Mapping.Value, options?: Mapping.Options): WalkerOS.Property | undefined primarily used by destinations to process values from the original event. This offers flexibility to configure individual tagging setups to standard fields of the destination.

string

Using a string for the mapping is a shortcut for the key option. It will return the value of the property specified by the string key.

Configuration

await getMappingValue(
  { a: 0, b: 1, c: 2 },
  'b',
)

await getMappingValue( { a: 0, b: 1, c: 2 }, 'b', )

Result

1

1

To access items in an array, use the dot notation.

Configuration

await getMappingValue(
  { arr: ['foo', 'bar'] },
  'arr.1',
);

await getMappingValue( { arr: ['foo', 'bar'] }, 'arr.1', );

Result

"bar"

"bar"

key

The key option is used to access a property of an object.

Configuration

await getMappingValue(
  { foo: 'bar' },
  { key: 'foo' },
);

await getMappingValue( { foo: 'bar' }, { key: 'foo' }, );

Result

"bar"

"bar"

value

The value option is used to return a static value. This can be used as a fallback if no other mapping option is applicable.

Configuration

await getMappingValue({}, { value: 'foo' });

await getMappingValue({}, { value: 'foo' });

Result

"foo"

"foo"

fn

The fn option is used to return a value from a function. The function will be called with the event object as the first argument.

Configuration

await getMappingValue(
  { foo: 'bar' },
  { fn: (obj) => obj.foo.toUpperCase() },
);

await getMappingValue( { foo: 'bar' }, { fn: (obj) => obj.foo.toUpperCase() }, );

Result

"BAR"

"BAR"

map

The map option is used to create a new object. The objects keys are defined using the getMappingValue function recursively.

Configuration

await getMappingValue(
  { foo: 'bar' },
  {
    map: {
      foo: 'foo',
      bar: { value: 'baz' },
      obj: { map: { recursive: { value: true } } },
    },
  },
);

await getMappingValue( { foo: 'bar' }, { map: { foo: 'foo', bar: { value: 'baz' }, obj: { map: { recursive: { value: true } } }, }, }, );

Result

{
  foo: "bar",
  bar: "baz",
  obj: {
    recursive: true
  }
}

{ foo: "bar", bar: "baz", obj: { recursive: true } }

loop

The loop option is used to iterate over an array and return a new array. The first parameter is the array to iterate over. The second parameter is again a getMappingValue function to define the value of the new array.

Configuration

await getMappingValue(
  { arr: [{ id: 'foo' }, { id: 'bar' }] },
  { loop: ['arr', 'id'] },
);

await getMappingValue( { arr: [{ id: 'foo' }, { id: 'bar' }] }, { loop: ['arr', 'id'] }, );

Result

[
  "foo",
  "bar"
]

[ "foo", "bar" ]

validate

The validate option is used to validate the value of the property. If the value does not match the validation function, it will be set to undefined or the static fallback value.

Configuration

await getMappingValue(
  { foo: 'bar' },
  {
    key: 'foo',
    validate: (v) => v === 'bar',
  },
);

await getMappingValue( { foo: 'bar' }, { key: 'foo', validate: (v) => v === 'bar', }, );

Result

"bar"

"bar"

consent

The consent option is used to check if the user has given consent to the property. If the user has not given consent, the value will be undefined or the static fallback value.

Configuration

await getMappingValue(
  {
    name: 'foo',
    consent: {
      functional: true,
      // marketing: true // uncomment me
    },
  },
  {
    key: 'name',
    consent: { marketing: true }, // required consent
  },
);

await getMappingValue( { name: 'foo', consent: { functional: true, // marketing: true // uncomment me }, }, { key: 'name', consent: { marketing: true }, // required consent }, );

Result

undefined // no marketing consent

undefined // no marketing consent

First the condition is checked to determine if the ValueConfig should be used. Second, the consent state gets checked if an instance is provided. If no required consent is given, no value will be returned. If a fn is provided, it will be called to define the value, otherwise the key or initial string value will be used with byPath. The current value will be check using the validate function and set to undefined if it fails. Finally, the value will be cast to match the WalkerOS.Property type. An empty ValueType will return undefined.

info

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