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_IMPORT . File 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 ).
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:
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
About Functions
Managing Functions
Writing Functions
Event and Visitor Functions
Adding an Authentication to a Function
Using Tealium Functions to Generate a UID2.0 Token
Functions Example Code
... View more