Back

This article provides details on the data transformation functions, custom trigger rules, the event parameter, and the flatten library. For examples of data transformation functions, see Functions Example Code.

Data transformation functions are invoked after an event is collected from the data source and before the event is processed and can be used for a variety of purposes, including the following:

  • Flattening the event object passed to the function.
  • Removing sensitive data, such as a phone number or an email address.
  • Modifying variables in the event object. For example, you can change variables to lower-case.
  • Populating variables in the event object based on other values.
  • Renaming variables, which is done by assigning the value to a different variable and deleting the original variable.

File import events are not currently supported for data transformation functions.

In this article:

How it Works

Data transformation functions are invoked after an event is collected from the data source and before the event is processed. A function is executed for an event when the trigger conditions are met.

The transformation function runs transform(event), where the event parameter is a metadata object for the incoming event. You will add code to the function to modify the event attributes found in the event.data.udo object.

When you save and publish after creating a data transformation function, it can take up to 300 seconds for the change to take effect.

Function Code

The default function code imports the flatten library and flattens the incoming event data object and assigns the result back to event.data.udo. Use the code editor to customize the function for your needs.

import flatten from "tealium/util/flatten";

// "transform" function allows you to access event and apply changes
transform((event) => {
    // changes are applied via mutation of the original event
    event.data.udo = flatten(event.data.udo);
    console.log(JSON.stringify(event, null, 2));
})

Custom Triggers

Data transformation functions execute based on custom triggers. Custom triggers are rules you create to specify when to execute a function. The conditions can be based on any property of the event parameter, but are commonly based on the data source key, data source platform, and the tealium_event attribute. Data transformation functions execute after the event is collected from the data source and before the event is processed by EventStream.

For more information, see Custom Triggers.

Event Parameter

The transformation function has one parameter named event. The event parameter is a metadata object that contains several properties and nested objects describing the event. The actual event data is referenced in the event.data.udo object.

The event parameter object is read-only, except for the custom event data in event.data.udo and some tealium_ properties.

For more information, see Event Data Object.

Event Parameter Object

The event parameter object contains the following properties:

Property Type Description Writable
account String Account information. No
client_ip String Client IP address. No
data Object See Event Data Object. No
dataSourcePlatform String Name of the data source platform. See Data Source Platform Values. No
enrichmentOnly Boolean Always false for live events. If false DataAccess is enabled, the event can be sent to DataAccess. May be true for bulk import events (when event.type="BULK_IMPORT"). If true, event data can be used only for enrichment. File import events are not currently supported for data transformation functions. No
env String Specifies the execution environment (dev or prod). No
event_id String Event ID. No
new_visitor Boolean True if this is the first visit for the user, otherwise false. No
page_url Object An object of URL properties. See URL Object.
Omitted for mobile events.
No
post_time Number Time stamp for the event. No
profile String Profile for the account. No
referrer_url Object An object of URL properties. See URL Object.
Omitted for mobile events.
No
type String Specifies whether the event is from a live visit or a bulk import event. Values are LIVE or BULK_IMPORTFile import events are not currently supported for data transformation functions. No
useragent String Specifies the software the user is using, such as the web browser. No
visitor_id String Visitor ID. No
_forwarding_visitor_ids String[] Contains the IDs of the visitor(s) forwarding this event. Used in the visitor stitching process. No

 

Data Source Platform Values

The value of the dataSourcePlatform property can be one of the following:

default
adobe_launch
affirm
android
braze
cordova
cSharp
fileImport*
googleAMP
google_tag_manager
http_api_flattened
hubspot_wf
intercom
iOS
iterable
java
javascript
mailchimp
python
RES
roku
salesforce
sendgrid
slack
swift
tiqJavascript
tvOS
watchOS
zapier

* File import events are not currently support for data transformation functions.

Event Data Object

The event.data object represents the incoming event and contains the event.data.udo object that can be transformed:

Property Type Description Writable
dom Object Contains information about the page on which the event occurred (domain, query string, etc.) Omitted for mobile events. For more information, see Data Layer. No
firstparty_tealium_cookies Object Object contains cookie properties specified in your data layer.
Omitted for mobile events.
No
js Object Object contains JavaScript variable properties specified in your data layer.
Omitted for mobile events.
No
meta Object Object contains metadata properties specified in your data layer.
Omitted for mobile events.
No
udo Object Object contains the properties of the incoming event. Some properties are read-only. See Writable Properties. Yes

 

Writable Properties

All custom event attributes in event.data.udo are writable, but only some of the tealium_ properties can be modified.

The following tealium_ properties can be modified, but not deleted:

  • event.data.udo.tealium_datasource
  • event.data.udo.tealium_environment
  • event.data.udo.tealium_event
  • event.data.udo.tealium_firstparty_visitor_id
  • event.data.udo.tealium_thirdparty_visitor_id
  • event.data.udo.tealium_library_name
  • event.data.udo.tealium_library_version
  • event.data.udo.tealium_random
  • event.data.udo.tealium_timestamp_epoch
  • event.data.udo.tealium_timestamp_local
  • event.data.udo.tealium_timestamp_utc
  • event.data.udo.tealium_session_number

Read-Only Properties

The following object properties are read-only and cannot be modified:

  • event.data.udo.tealium_cf_ttl
  • event.data.udo._dc_ttl_
  • event.data.udo.platform
  • event.data.udo.tealium_visitor_id
  • event.data.udo.tealium_account
  • event.data.udo.tealium_profile
  • event.data.udo.tealium_session_id

URL Object

The URL object contains the following standard URL properties:

PROPERTY TYPE DESCRIPTION WRITABLE
domain String Domain of the URL. No
full_url String Full URL. No
path String Path from the URL. May be empty. No
query_params Object An Object that contains one or more key.value pairs. Each key/value pair specifies a query string in the URL. For example:
"query_params": {
"utm_medium": "PPC",
"utm_source": "LinkedIn"
}
No
querystring String Query string from the URL. No
scheme String Specifies the protocol to use for the web site, such as HTTP or HTTPS. No

Example Event Parameter Object

The following shows an example event parameter object:

{
    "account": "XYZ_admin_acct",
    "profile": "main",
    "env": "prod",
    "data": {
        "dom": {
            "url": "https://www.example.com",
            "pathname": "/",
            "domain": "example.com",
            "hash": "",
            "query_string": "",
            "title": "Homepage"
        },
	"js": {},
	"meta": {},
	"udo": {
            "page_view": "view",
            "tealium_account": "XYZ_admin_acct",
            "tealium_profile": "main",
            "page_name": "Homepage",
            "page_type": "main",
            "tealium_event": "page_view",
            "user": {
                "browser_lang": "en-us",
                "ipcinfo": "en-us",
                "signedin": false,
                "city": "san diego",
                "country": "us",
                "country_name": "united states",
                "registry_city": "san diego",
                "registry_country_code": "us",
                "registry_state": "ca",
                "state": "ca"
            }
        },
        "firstparty_tealium_cookies": {
             "trace_id": ""
        }
    },
    "type": "LIVE",
    "enrichmentOnly": false,
    "event_id": "example-event-id",
    "visitor_id": "example-visitor-id",
    "post_time": 1655410928993,
    "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.0.0 Safari/537.36",
    "client_ip": "",
    "new_visitor": false
}

Custom Triggers

Data transformation functions support custom triggers, which are rules that specify when to execute the function. Custom trigger rules are similar to load rules and use boolean logic to combine conditions in a rule.

For example, in the following rule, the function is triggered when a purchase event comes from a specific data source (r2rbm8).

transfm-conditions-example.png

A condition is based on a selector that specifies a property in the event parameter object, a comparison operator, and a comparison value. A selector is a JSONPath expression (see JsonPath) and can reference any property in event.

An event can trigger only one function. If an event matches more than one function trigger, the function with the oldest Date Modified is the only function that is triggered.

For information on creating a data transformation function and a custom trigger, see Managing Functions.

Rule Limitations

  • Selector and Value fields are limited to 128 characters.
  • The regular expression operator is not available.
  • The size of a rule is limited to 10 KB.
  • The number of OR blocks is limited to 10.
  • The number of conditions in an AND block is limited to 10.

Converting Existing Functions to Custom Triggers

Custom triggers were introduced after the initial release of data transformation functions. For any data transformation functions that existed before custom triggers were introduced, a condition similar to the following is automatically created:

transfm-conversion-edit-cond.png

This new condition specifies the data source ID, which is set to the ID of the data source associated with the function. The function is triggered for every event from the data source. You can edit this condition to trigger the function for more specific events.

Flattening Nested Objects

The flatten library is a standard library that is imported in the default code for a data transformation function. This library provides the flatten() utility, which converts a nested Object into an Object that is not nested. flatten() returns an Object that contains strings and arrays of strings.

flatten() accepts two parameters, as follows:

flatten(target[, options])
  • target is the event Object passed to the data transformation function.
  • options is an Object that specifies how nested keys are handled during the conversion.

The options parameter contains the following properties:

PROPERTY DATA TYPE DESCRIPTION
delimiter string, default is ".". Specifies the character used to combine parent and child property names.
prefix string, default is "".

The prefix is concatenated at the beginning of the new key name followed by the delimiter.

ignoreKeys string[], default is []. Specifies keys that should be omitted from the output.
replaceKeys Object {string}, default is {}. Specifies new names for keys using key/value pairs, where the key is the existing key in the object, and

The following examples show how the options properties are used. These examples use the following nested Object as the target to be flattened:

const object = {
  page: {
    id: 1
  },
  user: {
    id: 1
  },
  util: ["1", "2", "3"]
};

delimiter

If delimiter is "_", the following object is returned:

{
  page_id: 1,
  util: ["1", "2", "3"]
}

prefix

If prefix is "fl", the following object is returned:

{
  "fl.user.id": 1,
  "fl.page.id": 1,
  "fl.util": ["1", "2", "3"]
}

ignoreKeys

If ignoreKeys is ["page", "util"], the following object is returned:

{
  "user.id": 1
}

replaceKeys

if replaceKeys is defined as follows:

const replaceKeys = {
  "user": "",
  "page": "p"
}

The following object is returned:

{
  "id": 1,
  "p.id": 1,
  "util": ["1", "2", "3"]
}Data Transformation Function Examples

Example of Flattening a Complex Object

import flatten from 'tealium/util/flatten';

const options = {
  delimiter: "_",
  ignoreKeys: ["array_of_strings"],
  replaceKeys: {
    "number": "float",
    "array_of_objects": "modified_array_of_strings",
    "ordinal": ""
  },
  prefix: "t"
}

const output = flatten({
  "boolean": true,
  "number": 12.34,
  "string": "value",
  "date": new Date(1631009413904),
  "array_of_strings": ["first", "second"],
  "array_of_arrays": [
    [1, 2],
    [3, 4]
  ],
  "array_of_objects": [{
    "ordinal": "first"
  }, {
    "ordinal": "second"
  }],
  "object": {
    "child_boolean": true,
    "child_number": 12.34,
    "child_string": "value",
    "child_array_of_strings": ["first", "second"],
    "child_array_of_arrays": [
      [1, 2],
      [3, 4]
    ],
    "child_object": {
      "gchild_boolean": true,
      "gchild_number": 12.34,
      "gchild_string": "value",
      "gchild_array_of_strings": ["first", "second"],
      "gchild_array_of_arrays": [
        [1, 2],
        [3, 4]
      ]
    }
  }
}, options);

The following object is returned by flatten():

{
  "t_boolean": "true",
  "t_float": "12.34",
  "t_string": "value",
  "t_date": "2021-09-07T10:10:13.904Z",
  "t_array_of_arrays": ["1","2","3","4"],
  "t_modified_array_of_strings": ["first","second"],
  "t_object_child_boolean": "true",
  "t_object_child_number": "12.34",
  "t_object_child_string": "value",
  "t_object_child_array_of_strings": ["first","second"],
  "t_object_child_array_of_arrays": ["1","2","3","4"],
  "t_object_child_object_gchild_boolean": "true",
  "t_object_child_object_gchild_number": "12.34",
  "t_object_child_object_gchild_string": "value",
  "t_object_child_object_gchild_array_of_strings": ["first","second"],
  "t_object_child_object_gchild_array_of_arrays": ["1","2","3","4"]
}

Additional Information

Public