Transformation Functions

Transformation functions are a powerful feature of CX Actions, that allows you to manipulate and transform data within your workflows using JavaScript. These functions can leverage Workflow form data (key-value pairs) or Workflow actions data (dynamic data) to perform complex operations. This document will provide a detailed overview of transformation functions, their types, and how to use them effectively.

Overview

Transformation functions are JavaScript-based functions that allow you to manipulate data within your workflows. These functions can be used to transform data retrieved from Connected Objects, user-selected data, or transient data stored within the transformation namespace. Transformation functions are invoked from a workflow using the Script Node, and the results can be used in various nodes such as Content Node, Email Node, and all other places where CX Actions variable substitutions are allowed.

Types of Transformation Functions

System Functions

System functions are predefined helper functions that allow you to work with data, access data, and update data. These functions are accessible using the ZT namespace. Some of the key system functions include:

1. Logging Messages

Logs a message to the console. The messages logged will be stored in Execution Insights if logging is enabled in the Connected Object.

ZT.log("Transformation started");

2. Setting Response Data

Sets the response data with the given alias.

ZT.setResponseData("customerInfo", { name: "John Doe", age: 30 });

3. Setting View Data

Sets the view data with the given alias.

ZT.setViewData("selectedItem", { id: "123", name: "Laptop" });

4. Setting Transformation Data

Sets the transform data with the given alias.

ZT.setTransformData("processedOrder", { orderId: "456", status: "Completed" });

5. Retrieving a Variable Value

Retrieves the value of a variable if it is defined, otherwise returns a default value.

const currency = ZT.getVariableValue("preferredCurrency", "USD");

User Functions

User functions are custom JavaScript functions that you can define to perform specific data transformations. These functions can leverage the system functions and namespaces to manipulate data as needed. These functions are accessible using the ZT namespace.

Namespaces in Transformation Functions

Namespaces are used to organize and access different types of data within transformation functions. There are three main namespaces:

Actions Namespace

The actions namespace contains data retrieved from connected objects, often referred to as response data. This data is typically the result of an API call or other external data retrieval operation.

View Namespace

The views namespace contains data selected by the user. This data is usually derived from user inputs or selections within the workflow.

log(message: string): void
ZT.log("Transformation started");

setResponseData(alias: string, data: any): void
ZT.setResponseData("customerInfo", { name: "John Doe", age: 30 });

setViewData(alias: string, data: any): void
ZT.setViewData("selectedItem", { id: "123", name: "Laptop" });

setTransformData(alias: string, data: any): void
ZT.setTransformData("processedOrder", { orderId: "456", status: "Completed" });

getVariableValue(name: string, defaultVal: any): any
const currency = ZT.getVariableValue("preferredCurrency", "USD");

Transformation Namespace

The transformations namespace is used as a transient store for data that is being transformed. The results of transformation functions can be persisted into this namespace for later use.

Accessing Data from Namespaces

Content Node & Other UI Elements

Data from these namespaces can be accessed using the ${<namespace>.<alias>} syntax in Content Node and other places.

Example:

• ${actions.customerData.firstName} – Retrieves response data from an external system.
• ${views.customerData.firstName} – Accesses user-selected data.
• ${transformations.processedData} – Retrieves transformed data.

Script Node & Transformation Function

In the Script Node and Transformation Function, data can be accessed using <namespace>.<alias>.xxx. It is advisable to access data from the namespace in the Script Node.

// Accessing data from the actions namespace
const orderAmount = actions.orderInfo.totalAmount;

// Accessing data from the views namespace
const orderId = views.orderInfo.id;

// Accessing data from the transformations namespace
const transformedData = transformations.transformedData;

Necessary Checks While Accessing Data

When accessing data from namespaces, it is important to ensure that the data exists and is in the expected format.

// Basic check
if (actions && actions.orderInfo && actions.orderInfo.totalAmount) {
  const orderValue = actions.orderInfo.totalAmount;
  // ... proceed with logic
}

// Using optional chaining
const orderValue = actions?.orderInfo?.totalAmount;
if (orderValue) {
  // Use orderValue safely
}

Using Transformation Functions in Workflows

Transformation functions are invoked from a workflow using the Script Node.

// Example Transformation Function
function transformData(responseData) {
  if (responseData.length === 0) {
    ZT.log('No response data found.');
    return [];
  }

  const transformedData = responseData.map(item => {
    return {
      ...item,
      newField: item.oldField * 2
    };
  });

  ZT.log('Data transformation completed successfully.');
}

// Access data and invoke transformation
const responseData = actions.responseAlias || [];
const transformedData = ZT.transformData(responseData);
ZT.setTransformData('transformedData', transformedData);

Script Node

The Script Node allows users to write and execute JavaScript code snippets within workflows.

Key Features of Script Node

1. JavaScript Execution: Write and execute JavaScript directly.
2. Access to Namespaces: Access actions and views data.
3. Data Updates: Update or set data across namespaces.
4. Transformation Function Invocation: Perform complex data operations.
5. Seamless Integration: Works with nodes like Data Connected Node, Content Node, and Email Node.

Use Cases for Transformation Functions

Data Enrichment

Use Case 1: Enriching Product Data

Scenario: Enrich product data with discounted price and availability.

function enrichProductData(products) {
  if (products.length === 0) {
    ZT.log('No product data found.');
    return [];
  }

  const enrichedProducts = products.map(product => {
    const discountedPrice = product.price * 0.9;
    const availability = product.stock > 0 ? 'In Stock' : 'Out of Stock';
    return { ...product, discountedPrice, availability };
  });

  ZT.log('Product data enrichment completed.');
}

Use Case 2: Adding Customer Segmentation

Scenario: Segment customers by purchase history.

function segmentCustomers(customers) {
  if (customers.length === 0) {
    ZT.log('No customer data found.');
    return [];
  }

  const segmentedCustomers = customers.map(customer => {
    const totalPurchases = customer.purchases.reduce((sum, p) => sum + p.amount, 0);
    let segment = 'Low Value';
    if (totalPurchases > 1000) segment = 'High Value';
    else if (totalPurchases > 500) segment = 'Medium Value';
    return { ...customer, totalPurchases, segment };
  });

  ZT.log('Customer segmentation completed.');
}

Use Case 3: Enriching Order Data with Shipping Information

function enrichOrderData(orders) {
  if (orders.length === 0) {
    ZT.log('No order data found.');
    return [];
  }

  const enrichedOrders = orders.map(order => {
    const shippingInfo = {
      estimatedDeliveryDate: new Date(new Date().setDate(new Date().getDate() + 7)).toISOString().split('T')[0],
      shippingCarrier: 'Standard Shipping'
    };
    return { ...order, ...shippingInfo };
  });

  ZT.log('Order data enrichment completed.');
}

Data Filtering

Use Case 4: Filtering Outdated Submissions

function filterSubmissions(submissions) {
  const currentDate = new Date();
  const thirtyDaysAgo = new Date(currentDate.setDate(currentDate.getDate() - 30));

  if (submissions.length === 0) {
    ZT.log('No submissions found.');
    return[];
  }

  const filteredSubmissions = submissions.filter(sub => new Date(sub.date) > thirtyDaysAgo);
  ZT.log('Submissions filtered successfully.');
}

Data Aggregation

Use Case 5: Aggregating Sales by Category

function aggregateSalesByCategory(sales) {
  if (sales.length === 0) {
    ZT.log('No sales data found.');
    return[];
  }

  const aggregatedSales = sales.reduce((acc, sale) => {
    const category = sale.category;
    if (!acc[category]) acc[category] = 0;
    acc[category] += sale.amount;
    return acc;
  }, {});

  ZT.log('Sales aggregated by category.');
}

Conclusion

Transformation functions are a versatile tool for manipulating and transforming data within your workflows. By leveraging system functions and namespaces, you can perform complex data operations with ease. Whether you need to enrich, filter, or aggregate data, transformation functions provide the flexibility and power to meet your needs.

For Data Enrichment and Merging data from different sources, use cases in CX Actions, create a Connected Object with sample data, and generate a schema. A Dynamic View can be created to effectively utilize the transformed data.