The Data Activation platform provides a module called Transformer that allows you to transform event data to make it compliant with the data format required by a receiving platform. With the transformer, you collect event data once and share it with multiple partners with different data requirements and formats.
This means you can collect data in a format useful for the Data Activation platform or your own platforms. When data needs to be sent to an external platform, you can transform it accordingly.
The examples in this document focus on Facebook as the destination. Other destinations likely need different transformations, but the principles remain the same.
Available transformations
Below are all available transformations with descriptions of what they do. "Input" means data in the Data Activation platform. "Output" is the resulting data after the transformations.
Transformation | Description | Example |
|---|---|---|
Date format | Transforms dates from one readable (string) date format to another. | Input: |
Date to epoch seconds | Transforms a readable (string) date to epoch seconds. The epoch timestamp is calculated based on GMT by default. You can provide an offset to get the timestamp according to your timezone. | Input: |
Epoch milliseconds to seconds | Transforms a value in milliseconds to seconds by dividing the number by 1000. | Input: |
Epoch seconds to date | Transforms an epoch seconds date to a readable (string) date format. You can provide an offset (+/- hours:minutes) for your timezone. | Input: |
Epoch seconds to milliseconds | Transforms a value in seconds to milliseconds by multiplying the number by 1000. | Input: |
Hashing | Returns the hash of the input field. Currently only SHA-256 hashing is supported. | Input: " |
Country code (2-letter ↔ 3-letter) | Transforms a 2-letter country code to 3 letters or a 3-letter country code to 2 letters. See country codes reference. If the property doesn't match a 2/3 letter code, it results in an error. | NL ↔ NLD |
String to array | Sets a delimiter to split a string value into an array. | Input: " |
String to number | Transforms a string to a number. If the string contains anything other than digits, it results in an error. | Input: " |
String to true/false | Turns a string input into a boolean output. True values: "true", "True", "TRUE", "on", "On", "ON", "y", "Y", "t", "T", "yes", "Yes", "YES", "1". False: anything else. | " |
Value mapping | Maps a specific value to another value type. Input values without a mapping are sent as-is. | Map input "m/f" to partner requirement "male/female". |
Applying transformations
If you need multiple transformations to get the correct output for the destination, the order of transformations is critical.
Follow these steps to get the correct result:
Export the relevant events. See How to use Data Activation exports.
Check the data in the exports
Set up the transformations accordingly
Step 1: Export the relevant events
The Data Activation platform audience and journey engine is flexible with data types. Note that anything collected through the front-end API or TMS is always stored as a string value.
To ensure successful setup, first understand the data you want to send to the event destination. Use the historic event export for this activity. You don't need much data — an export of one day filtered for the specific event is sufficient.
Period: 1 day
Query:
interaction.type=="your engagement or fact name"
Step 2: Check export data
Depending on how data enters the Data Activation platform — either through the browser (TMS, organic endpoints (Data Activation Tracking API endpoints)) or backend (REST API (Data Activation API documentation) ) — data types are handled differently:
Values collected through TMS always become a string, even if sent as a number or boolean.
The REST API leaves data types as they are.
Example export:
{
"eventId": "fa131c70-2f48-11ec-8079-8f9a02405599",
"variables": {
"lastName": "499e6f37da4151a9d477da28dc4758e0fd6ef4a6ef942ed2f5287164132e00fb",
"eventId": "edac9894-2da1-4517-b9bd-a8ea021f3cbc",
"gender": "male",
"origin": "website",
"eventname": "fb",
"email": "2639fbf9feeed895812336318512ca82dcce3f07add5f6e2dc022439cb4e012d",
"timestamp": "1634475102090",
"country": "NLD",
"DateOfBirth": "31-03-1990",
"value": "160"
},
"interactionType": "engagement",
"trackId": "2af27c06-926e-47a1-b169-7e261edc6f2c",
"siteNumber": 1232,
"type": "conversionInfo",
"content": "",
"timestamp": 1634475102135
}Note
Some fields can be sent to the Data Activation platform without hashing. However, email addresses, first names, last names, phone numbers, and similar personal data should always be hashed before sending to the Data Activation platform.
Step 3: Set up transformations
To know which transformations to apply, understand what output the partner platform expects. For Facebook, you can look up the requested formats in their documentation.
Map the properties
On the left side, specify the destination properties as required by the partner platform.
On the right side, select the Data Activation platform engagement or fact properties you want to send to the destination.
Define transformations
After mapping the properties, define the necessary transformations for each field.
Important
Transformations execute in order from top to bottom.
Transformation examples for Facebook
lastName
Data Activation Platform property: lastname
Data Activation Platform data type: string, SHA256 hash
Facebook property: ln
Facebook data type: string, hashed
Transformations needed: none
eventId
Data Activation Platform property: eventId
Data Activation Platform data type: string, unique identifier
Facebook property: event_id
Facebook data type: string, unique identifier for deduplication
Transformations needed: none
gender
Data Activation Platform property: gender
Data Activation Platform data type: string, male/female
Facebook property: ge
Facebook data type: string, m/f, hashed
Transformations needed:
Value mapping: male to m
Hashing: SHA256
origin
Data Activation Platform property: origin
Data Activation Platform data type: string
Facebook property: action_source
Facebook data type: string
Transformations needed: none
eventname
Data Activation Platform property: eventname
Data Activation Platform data type: string
Facebook property: event_name
Facebook data type: string
Transformations needed: none
Data Activation Platform property: email
Data Activation Platform data type: string
Facebook property: em
Facebook data type: string, hashed
Transformations needed: none (already hashed)
timestamp
Data Activation Platform property: timestamp
Data Activation Platform data type: string
Facebook property: event_time
Facebook data type: number, seconds since epoch
Transformations needed:
String to number
Epoch milliseconds to seconds
country
Data Activation Platform property: country
Data Activation Platform data type: string
Facebook property: country
Facebook data type: 2-letter ISO country code
Transformations needed:
2 ↔ 3 letter
Hashing: SHA256
DateOfBirth (db)
Data Activation Platform property: DateOfBirth
Data Activation Platform data type: string
Facebook property: db
Facebook data type: number
Transformations needed:
Date to epoch seconds
Hashing: SHA256
value
Data Activation Platform property: value
Data Activation Platform data type: string
Facebook property: value
Facebook data type: number
Transformations needed:
String to number
Troubleshooting transformations
Errors appear in the statistics when you navigate to Data → Connectors → Event Connectors, click the three dots (…) next to the connector, and select Statistics.
Other_error: Sending was unsuccessful.
Transformation_error: The transformation itself failed. Below the statistics, you can see the last 10 transformation errors. This shows the source property, source value, destination property, applied transformation, and the error message. Use this information to examine your data and understand why the transformation failed so you can adjust the setup or data delivery.
FAQ
What happens if a transformation fails and the field is marked as mandatory?
The entire event is ignored and results in a transformation error in statistics reporting.
What happens if a transformation fails and the field is not marked as mandatory?
The specific property is ignored, removed, and not sent to the destination. Sending continues as normal. There's currently no reporting on this.
Can I use the Data Activation platform event timestamp?
Yes. Under "source property," you'll find a list of "standard properties" at the bottom. These are properties that are part of each Data Activation platform event.
How do transformations work on an array?
Value transformations apply to a single value. The only exception is transformations specifically designed to split a single value into multiple values, such as STRING_TO_ARRAY. When applying multiple value transformations to a single property where the result needs to be a collection or array, first apply the transformation that splits the value into multiple values, then specify any following transformations. Each value then gets those transformations applied.
Can I add custom data fields?
Yes, you can add a custom property. These are properties not predefined by Facebook. All custom properties are added to the custom_data object in the request. See the Facebook custom data documentation. To set up a custom property in the destination field, type the desired name and press Enter. Then select the Data Activation platform property and add any transformations if needed.
What does it mean when I set a field as mandatory?
Setting a field as mandatory ensures the event is only sent if that field is available and successfully transformed. This option gives you control over the data quality of events entering the destination platform.
What is epoch or Unix epoch?
This is a moment in time often used by applications. It counts seconds from January 1, 1970, 00:00 GMT.