Breadcrumbs

Data types & formatting


What are data types

Properties are assigned specific data types, which dictate how incoming data is interpreted and formatted. For instance, dates have a data type of 'date,' requiring you to specify a particular format to ensure accurate interpretation. These data types play a crucial role in ensuring that data is stored, processed, and interpreted consistently and accurately across the system.

Here are some common data types you might encounter within definitions and their formatting capabilities.

Make sure you understand how empty values work per data type.

Numbers

  • Description: A type that only contains numbers

  • Formatting: When selecting type number on event level you need to specify the decimal and thousand separator and what the number is, this can be a plain number or a currency. On object level you only need to select the type of number, so either currency or plain number as the decimal and thousand separator is about how the incoming data should be processed and interpreted.

image-20250307-092549.png

  • Examples: 150, 79.99

  • Use Cases: Prices (currency), measurements, percentages.

 

{
  "id": "P001",
  "stockQuantity": 150,
  "price": 79.99
}

Strings

  • Description: A sequence of characters used to represent text.

  • Formatting: A string can be of type general or URI, you can specify this on event and/or object level.

image-20250307-092646.png

  • Examples: "John Doe", "P001", "Wireless Earbuds", "https://www.google.nl"

  • Use Cases: Names, addresses, products, identifiers, website, URI track


{
  "id": "P001",
  "name": "Wireless Earbuds"
}

Booleans

  • Description: A data type with two possible values: true or false.

  • Formatting: No specific formatting options here

image-20250307-092718.png

  • Examples: true, false

  • Use Cases: Flags, binary states (e.g., isAvailable, hasPaid, hasConsent).


{
  "id": "P001",
  "name": "Wireless Earbuds",
  "isAvailable": true
}


Email

  • Description: A specialized string data type designed to represent and validate email addresses, ensuring a proper format for communication.

  • Formatting: No specific formatting options here

image-20250307-092742.png

  • Examples: "[email protected] ", "[email protected] "

  • Use Cases: Storing unique email addresses for sending promotional, informational, or transactional emails; used as a channel for contacting customers and managing communication preferences.

{
  "email": "[email protected]",
  "name": "Jane",
  "emailVerified": true
}

Phone number

  • Description: A dedicated data type for storing phone numbers in a format suitable for communication and validation, accommodating different country codes and formats.

  • Formatting: Specify the default region. When a phone number without region enters the system we will treat it as a phone number with the region as selected here. If a phone number comes in with a region, we take this region even if it is different from the default region.

image-20250307-092805.png

  • Examples: +31612345678, 0612345678, +4476478457765

  • Use Cases: Storing unique mobile phone numbers for sending SMS or voice campaigns for example; used as a channel for customer engagement, notifications, and two-factor authentication.

{
  "phonenumber": "+31612345678",
  "name": "Jane",
  "verified": true
}


Locale

  • Description : A data type used to define a specific geographical, political, or cultural region's language setting, which can impact language, formatting, and presentation preferences.

  • Formatting: No specific formatting options here

image-20250307-092836.png

  • Examples : "en-US" for English (United States), "nl-NL" for Dutch (Netherlands), "fr-FR" for French (France)

  • Use Cases : Tailoring content, date, and time formatting, currency symbols, number formatting, and language preferences for a user's locale or region

{
  "id": "P001",
  "name": "Wireless Earbuds",
  "price": 79.99,
  "locale": "en-US"
}


Objects

  • Description: A complex data type that can contain multiple properties.
    Complex objects are data structures that contain multiple parts, often combining different types of information. These parts can include basic data like numbers and text, as well as other complex objects, forming a nested structure. They are used to represent detailed real-world entities in a single package. For example, a customer profile might include their name, address, and order history, while a product listing could include details like specifications, reviews, and prices.

  • Formatting: No specific formatting options here

image-20250307-092916.png

  • Examples: Address details with street, number, city and zipcode

  • Use Cases: Representing entities with multiple attributes (e.g., address details, product details).

JSON
{
    "name": "jane",
    "lastname": "doe",
    "email": "[email protected]",
    "adressDetails": {
        "street": "Demo street",
        "number": 4,
        "city": ["Amsterdam"]
    }
}

Arrays

  • Description: A list of values, which can be of any data type.
    Arrays are data structures that store a collection of items, all of the same type, in a specific order. Each item in an array can be accessed by its index, which is its position in the array. Arrays are useful for storing lists of data, such as a list of numbers, names, or other items. For example, you might use an array to store the scores of a game, the names of students in a class, or a series of dates.

  • Formatting: No specific formatting options here, the formatting is based on the selected array type (string, boolean etc.)

image-20250307-093007.png

  • Examples: List of liked products

  • Use Cases: Collections of items, lists of related entities, sequences of values.

JSON
[
  {
    "id": "P001",
    "name": "Wireless Earbuds",
    "price": 79.99,
    "category": "Electronics"
  },
  {
    "id": "P002",
    "name": "Water Bottle",
    "price": 24.99,
    "category": "Home & Kitchen"
  },
  {
    "id": "P003",
    "name": "Yoga Mat",
    "price": 39.99,
    "category": "Sports & Outdoors"
  }
]


Dates

Date

  • Description: Represents a specific date.

  • Formatting: Specify how dates are going to enter the system on event level, this so we can process it accordingly. If your date format is not in one of the pre-defined formats, you can add a custom format.

        ["dd/MM/yyyy", "E.g. 14/01/2025, European and British format"],
        ["MM/dd/yyyy", "E.g. 01/14/2025, United States format"],
        [this.defaultValue, "E.g. 2025-01-14, ISO format"],
        ["dd-MM-yyyy", "E.g. 14-01-2025"],
        ["dd.MM.yyyy", "E.g. 14.01.2025"],
        ["MM-dd-yyyy", "E.g. 01-14-2025"],
        ["dd MMM yyyy", "E.g. 14 Jan 2025"],
        ["MMMM dd, yyyy", "E.g. January 14, 2025"],
        ["yyyyMMdd", "E.g. 20250114"]
image-20250307-093052.png

  • Examples: "2023-07-16", "2024-01-01"

  • Use Cases: Birthdates, transaction dates, event dates.

JSON
{
  "id": "U123",
  "name": "John Doe",
  "birthday": "1990-05-20"
}

Date time

  • Description: Represents a specific date and time.

  • Formatting: Specify how date time values are going to enter the system on event level, this so we can process it accordingly. If your date format is not in one of the pre-defined formats, you can add a custom format.

        [this.defaultValue, "E.g. 2025-01-14T13:45:30.1234567+00:00, ISO 8601"],
        ["dd/MM/yyyy HH:mm:ss", "E.g. 14/01/2025 13:45:30, European and British format"],
        ["MM/dd/yyyy HH:mm:ss", "E.g. 01/14/2025 13:45:30, United States format"],
        ["dd-MM-yyyy HH:mm:ss", "E.g. 14-01-2025 13:45:30"],
        ["dd.MM.yyyy HH:mm:ss", "E.g. 14.01.2025 13:45:30"],
        ["MM-dd-yyyy HH:mm:ss", "E.g. 01-14-2025 13:45:30"],
        ["dd MMM yyyy HH:mm:ss", "E.g. 14 Jan 2025 13:45:30"],
        ["MMMM dd, yyyy HH:mm:ss", "E.g. January 14, 2025 13:45:30"],
        ["yyyyMMdd HH:mm:ss", "E.g. 20250114 13:45:30"],
        ["dd/MM/yyyy hh:mm:ss tt", "E.g. 14/01/2025 01:45:30 PM, 12-hour format"]
image-20250307-093115.png

  • Examples: "2023-07-16T14:30:00Z", "2024-01-01T00:00:00"

  • Use Cases: Timestamps, event logs, schedule times.

JSON
{
  "id": "P001",
  "name": "Wireless Earbuds",
  "releaseDate": "2023-10-15T00:00:00Z"
}

Calculations

Sum

  • Description: Represents the total sum of a numerical field, can only be chosen on an object definition.

  • Formatting: On object level you only need to select the type of number, so either currency or plain number as the decimal and thousand separator is about how the incoming data should be processed and interpreted.

image-20250307-100920.png

  • JSON Examples: Sum of product prices. In the script, sumOfPrice.addValue(product.price) adds each product's price to calculate the total.

    JSON
    {
  "ID": "1701234567",
  "Email": "[email protected]",
  "Products": [
    { "Price": 29.99, "Name": "Wireless Mouse" },
    { "Price": 49.99, "Name": "Bluetooth Headphones" },
    { "Price": 1009.99, "Name": "USB-C Charging Cable" }
  ]
}

  • Script example

    JavaScript
    // Initialize the sum calculation
// The sumOfPrice property will track the total of all product prices
for (const product of input.Products) {
    // Add each product price to the running sum
    customer.sumOfPrice.addValue(product.Price);
}
// After processing all products, sumOfPrice will contain 1089.97


  • Use Cases: Calculating total sales, aggregating financial data, determining total quantities.

Average

  • Description: Represents the average value of a numerical field.

  • Formatting: On object level you only need to select the type of number, so either currency or plain number as the decimal and thousand separator is about how the incoming data should be processed and interpreted.

image-20250307-101633.png

  • Examples: Product prices are averaged using averagePrice.includeValue(product.price) in the script.

    JSON
    {
  "ID": "1701234567",
  "Email": "[email protected]",
  "Products": [
    { "Price": 29.99, "Name": "Wireless Mouse" },
    { "Price": 49.99, "Name": "Bluetooth Headphones" },
    { "Price": 1009.99, "Name": "USB-C Charging Cable" }
  ]
}


  • Script example

JavaScript
    // The averagePrice property will automatically track the 
    // average of all values included in the calculation
    for (const product of input.Products) {
        // Include each product price in the average calculation
        customer.averagePrice.includeValue(product.Price);
    }
    // After processing all products, averagePrice will contain 363.32
    // (the system automatically divides the sum by the number of values)

  • Use Cases: Average order value, average customer rating, average time spent.


Count

  • Description: A numerical type used to count the number of events of a specific event or property

  • Formatting: No specific formatting options here

image-20250307-102111.png

  • Examples: In the script, count.incrementValue() increments a counter for each product processed.

    JSON
    {
  "ID": "1701234567",
  "Email": "[email protected]",
  "Products": [
    { "Price": 29.99, "Name": "Wireless Mouse" },
    { "Price": 49.99, "Name": "Bluetooth Headphones" },
    { "Price": 1009.99, "Name": "USB-C Charging Cable" }
  ]
}

  • Script example

    // Initialize the product counter
// The count property will track the number of products
for (const product of input.Products) {
    // Increment the counter for each product processed
    customer.productCount.incrementValue();
}
// After processing all products, productCount will contain 3


  • Use Cases: Tracking frequency of certain events or properties within an event.