40

Use objects in liquid

Learn how to reference objects and relationships using liquid.

Try generating liquid with AI

We know that liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}. is complicated, even moreso when you need to reference objects, relationships, and people in the same message. To make things easier, we built a tool that uses AI to generate your message and liquid for you.

This is an experimental feature. You can enable by going to the icon in the upper right corner of your workspace and clicking Experimental Features. Then you can click Generate with AI in campaigns triggered by changes to objects or relationships to generate your message and associated liquid tags.

We’ll use the object name and relationship attribute names to try and generate your message. You can copy the output into your message and continue refining it to better fit your needs.

Like other AI-based chat tools, you can refine your prompt to get the results you want. For instance, if you want to reference a specific attribute in the subject line of an email, you might modify the prompt with “add attribute_name to the subject line.” You can continue to refine your message after you copy the results into your message.

Reference trigger data

You can trigger campaigns based on changes to objects and relationships, so we made it possible for you to use liquid that targets the trigger object or relationship data. You can reference trigger data for object and relationship-triggered campaigns using {{trigger.<object_type>.<attribute_name>}}.

For instance, if you have an object type of “Online Classes” and set up a campaign to trigger when you update a class, you could craft an email like the following:

See the liquid examples below for more use cases.

Relationship-triggered campaigns

You can use the following liquid when a relationship triggers a campaign:

• {{trigger.relationship.<attribute_name>}}
• {{trigger.<object_type>.<attribute_name>}}
• {{trigger.customer.<attribute_name>}}

Recall that a relationship-triggered campaign can have an audience that is different from the person with the relationship that triggered a campaign. You have the ability to reference both people using liquid. For instance:

{{customer.first_name}} refers to the audience/recipient of the message, and {{trigger.customer.first_name}} refers to the person with the relationship that triggered the campaign.

Object-triggered campaigns

You can use the following liquid when an object triggers a campaign:

{{trigger.<object_type>.<attribute_name>}}

Reference non-trigger data

If you’ve read the above, you may be wondering how to reference object data when an object or relationship is NOT the trigger for a campaign. For instance, you may want to:

• check if someone is related to an object
• list values for the same attribute across multiple objects

Let’s imagine you have an object type of online classes and these classes have an attribute of name. You could reference non-trigger data for classes with the following liquid:

1. {{objects.online_classes}}
2. {{objects.online_classes[#]}}
3. {{objects.online_classes[#].name}}

You could reference relationships to these classes, as well. Below, we reference the relationship attributes role and name.

1. {{objects.online_classes[#].relationship.role}}
2. {{customer._relationship.name}}

When using this liquid, just remember to replace the object type and attribute names to match your data!

You can use most of this liquid across any of our automation workflows - campaigns, newsletters, API-triggered broadcasts, and transactional messages. This liquid {{customer._relationship.<attribute_name>}}, however, is only available in object and relationship-triggered campaigns (see below).

We’ll get into examples below, but make sure you understand the following limitations before using non-trigger liquid in your campaigns.

Before you begin

The following examples imagine that you relate people to online classes.

Object attribute

If you wanted to reference just an attribute, you’d use {{objects.online_classes[0].<attribute_name>}}.

Keep in mind: {{objects.online_classes[0].name}} is not necessarily the same class across all people who receive a message. That is, if Matthew were related to English Literature only and Clarice were related to Calculus 1A only, then {{objects.online_classes[0].name}} would render the data for each class name respectively.

Relationship attribute

If you wanted to reference relationship data for an object, you’d use {{objects.online_classes[#].relationship.<attribute_name>}}.

Keep in mind: {{objects.online_classes[#].relationship.<attribute_name>}} is not necessarily the same class across all people who receive a message. That is, if Matthew were related to English Literature only and Clarice were related to Calculus 1A only, then {{objects.online_classes[0].relationship.<attribute_name>}} would render the data for each class respectively.

Audience attribute

In object or relationship-triggered campaigns, you choose an audience - the people who start a journey. For instance, if you triggered a campaign based on a person being added to an account, you could specify that you want people who are account admins to enter the campaign and receive messages. You’d reference the audience using {{customer._relationship.<attribute_name>}} in messages. (To target the person who triggered the campaign, you’d use trigger liquid).

Here’s an example of how to message admins when people subscribe to their account:

1. Create a campaign triggered by a person added to an account.
2. Set the relationship trigger condition to role is equal to subscriber.
3. Set the audience to “certain people in the account,” choose relationship from the dropdown, then enter role is equal to admin.
4. Create a message to inform the admin(s) that a person was added to the account:

Hi {{customer._relationship.admin}}!

{{trigger.customer.name}} at {{trigger.account.name}} started using {{trigger.relationship.feature}}.

Examples

Check if a person is related to objects

{% if objects.online_classes | size == 0 %}
    Time to sign up for a class! Review our catalog. // recipient is not signed up for any class
{% else %}
    Check out related courses! // recipient has signed up for at least one class
{% endif %}

List objects related to a person

{% for class in objects.online_classes %}
    {% if class.relationship.status == "not_started" %}
        - {{class.name}}
    {% endif %}
{% endfor %}

Message an audience member who did not trigger the journey

This is only useable in object or relationship-triggered campaigns when the audience is “Certain people related to the object!” Check out Audience attribute for an example of a campaign you could use this in.

Hi {{customer._relationship.admin}}!

{{trigger.customer.name}} at {{trigger.account.name}} started using {{trigger.relationship.feature}}.

Show all object data for up to 10 objects

Use {{objects.<object_type>}} to show all attributes related to each object a person is related to. For instance, if a person were related to two classes, then {{objects.online_classes}} could render the following:

{
    "_created_in_customerio_at"=>1685030419,
    "cio_object_id"=>"oba886080104",
    "created_at"=>1685030405,
    "name"=>"English Literature",
    "object_id"=>"ae3000-145"
}
{
    "_created_in_customerio_at"=>1681491863,
    "cio_object_id"=>"oba886080102",
    "created_at"=>1681491859,
    "name"=>"Calculus 1A",
    "object_id"=>1
}

You likely don’t want to surface all object data to your customers, especially in this format! Consider using a for loop instead.

Keep in mind, you cannot reference more than 10 objects related to a person of a single object type.

Show all object data for an object

Imagine that you created two classes as objects. First you added English Literature then you added Calculus 1A. If a person enrolled in both classes, which related them to the objects, you’d reference the person’s Calculus enrollment with {{objects.online_classes[0]}} and the person’s English class with {{objects.online_classes[1]}}.

{{objects.online_classes[0]}} would show all of the attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. for the Calculus class! For example:

{
    "_created_in_customerio_at"=>1685030419, "cio_object_id"=>"oba886080104", 
    "created_at"=>1685030405, 
    "name"=>"Calculus 1A", "object_id"=>"ae3000-145"
}

Keep in mind: {{objects.online_classes[0]}} is not necessarily the same class across all people who receive a message. That is, if Matthew were related to English Literature only and Clarice were related to Calculus 1A only, then {{objects.online_classes[0].name}} would render the data for each class respectively.

If you want more control over the format of the object data, reference attributes like this instead: {{objects.online_classes[0].name}}.

Object liquid in workflow actions

You can use object and relationship liquid in any campaign type to set attributes through workflow actions like Send event, Create or update person, Send and receive data, and Batch update.

If the campaign is triggered by an object or relationship, you can also set attributes equal to trigger data like {{trigger.account.name}} or {{trigger.relationship.status}}.

Create or update person

Use Create or update person actions to update people’s attributes.

For instance, let’s say you schedule appointments and each appointment is an object. You could loop through all of a customer’s upcoming appointments and set next_appointment to the earliest date.

{% assign next_appointment = appt %}
{% for appt in objects.appointments %}
    {% if next_appointment == blank or next_appointment < appt.date %}
        {% assign next_appointment = appt.date %}
    {% endif %}
{% endfor %}
{{next_appointment}}

Send event

Use Send event actions to create events that trigger campaigns. In many cases, you may not need a Send event workflow action; you could create an object or relationship-triggered campaign instead to accomplish the same goal. But perhaps you want to separate actions into distinct campaigns to track multiple goals or simply separate parts of a campaign for ease of maintenance or understanding. Then a Send event can help.

Send and receive data

Use Send and receive data actions to trigger webhooks with object or relationship data.

For instance, perhaps you need to send an account’s ID to reconcile billing in Stripe; you’d use this action to send your object’s data. You could also pass object data to your analytics platform like Mixpanel.

Batch update

Use Batch update actions to send events or update people in bulk.

In object or relationship triggered campaigns, under “Which attributes do you want to add, change, or remove?” you can choose “Trigger object attribute” or “Trigger relationship attribute” from the dropdown as we populate the available attributes so you don’t have to write liquid. If this doesn’t fit your use case, you can also specify a profile attribute, choose “Liquid,” then include object or relationship liquid.