Understanding Cargo's expression template

Introduction

In Cargo, expressions allow users to manipulate data within their workflows using 'single-line JavaScript'. This guide aims to deepen your understanding of expressions and their role in crafting effective GTM workflows.

It is helpful to think of workflows in Cargo as layers of various data objects stacked on top of each other and threaded together with expressions. In other words, expressions allow interaction with and between data objects.

Expressions are also found across other parts of the platform, for instance for filtering data in data models. This gives the user a high degree of composability in dealing with data, differentiating Cargo from other orchestration tools.

The expressions template

Although most of the notation in Cargo's expressions resembles what you would expect from any JavaScript environment, there is a Cargo-specific template to follow. This allows for quick, one-line commands to handle data.

Whereas in pure JavaScript an equivalent action would span an entire function, a Cargo function would typically pack that logic into one line of code.

This permits users to merge the versatility of a programming language while placing enough restrictions to prevent users from getting lost in a sea of syntax.

Curly brackets

In Cargo, everything contained inside curly brackets is an expression. This is where you can leverage the power of Javacript to access data objects, perform data operations, and more.

Most data objects will be contained inside JSON or array structures from databases or APIs. The expression template in Cargo is designed to make it really easy to perform routine actions such as extracting specific fields from a JSON object or mapping over arrays.

{
  "user": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street": "123 Main St",
      "city": "Anytown"
    },
    "emails": ["john.doe@example.com", "johndoe@anotherexample.com"],
    "balance": 150
  }
}

The example above represents a 'JSON object', containing the details of a user. To access the first name of the user, you would use curly brackets to frame the following expression:

{
  {
    nodes.start.user.firstName;
  }
}

JSON objects

The dot notation inside an expression is the universal way to access nested fields inside a data object.

{
  {
    nodes.start.user.address.city;
  }
}

Using the example start node above, the expression above will return the city of the user, i.e. 'Anytown'.

Data operations

JavaScript is a powerful language with a lot of utilities available to transform data.

The expression builder in Cargo provides a simplified space to perform tasks like converting the case of a string or performing calculations on a number.

{
  {
    nodes.start.user.name.toLowerCase();
  }
}

The expression above would retrieve the converts the name field in the start node to lowercase: i.e. 'john doe'.

{
  {
    nodes.start.user.balance + 100;
  }
}

The second expression adds '100' to the balance of the user. If the initial balance was '150', the result would be '250'.