This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

35

Objects and relationships in automations

You can trigger automations based on changes to objects and relationships. You can target trigger data in messages and specify who should enter an automation based on the relationship they have to objects.

Trigger automations based on objects or relationships

You can trigger automations based on changes to objects or relationships. You can trigger an automation when:

• an object is updated (like an Account’s name was changed).
• a relationship between an object and profile is added.
• a relationship is changed (like a profile is no longer associated with an Account).

You can also narrow in on the audience for these automations. For both object and relationship-triggered automations, you can choose to send to:

• every profile in the object or
• certain profiles in the object

For relationship-triggered automations, you can also choose to send only to the profile that triggered the automation.

Visit Automation Triggers for more on object-triggered automations or relationship-triggered automations.

Per-trigger fan-out limit of 1,000

When an object or relationship changes, the automation runs for every profile related to that object. A single trigger event can’t fan out to more than 1,000 profiles. If a trigger includes more than 1,000 profiles, none of them start a journey.

This limit is per trigger event, not per automation. Your automation can have far more than 1,000 total recipients—the limit only applies to how many profiles a single object or relationship update can reach at once.

Why the limit exists

A single object update can trigger messages for every related profile simultaneously. Without a cap, one property change on a popular object could kick off thousands of simultaneous journeys, slowing down your workspace. The 1,000-profile limit is a backstop to prevent this kind of problem.

Working within the limit

If an object or relationship update would fan out to more than 1,000 profiles, you might want to:

• Narrow your audience. Switch from “Every profile in the object” to “Certain profiles in the object” and add conditions to reduce the total number of profiles per trigger.
• Restructure your objects. Break large objects into smaller ones with fewer relationships. For example, split a single “auction” object into regional auction objects so each update affects fewer profiles.

Performance considerations

Imagine you have a few Account objects with 10 profiles related to each of them. Each Account has a lifetime_value attribute, and you have five segments and five automations that send messages based on an Account’s lifetime_value. Each time an Account’s lifetime_value gets updated, our system checks each of the 10 profiles related to that account to see if they should still belong to any of the segments or automations.

One little change - to a single Account’s attribute, in this case - caused us to check 100 things (5 segments x 10 profiles, 5 automations x 10 profiles). At this scale, that’s no problem.

But imagine you have hundreds of thousands of Accounts and most of them change every day. That can pretty quickly become hundreds of millions, even billions, of things for us to process. We know how to handle this - it’s our job! But if you ever get to an extreme enough scale, we’ll send you warning messages so you know well in advance if your account could be impacted. In very extreme situations, we might need to throttle the data we process from you - but again, we’ll always warn you long before we get to that.

Bottom line, the more segments and automations you have based on objects, the more you should make sure you’re targeting and updating the correct objects and relationships. For instance, instead of sending us your entire database every hour, send us only the object data we need. Of course, if you have any concerns, reach out to us and we’ll be happy to help!

Workflow actions for objects and relationships

You can use object or relationship data in any workflow item, including Create or update profile, Send event, Send and receive data, Wait Until blocks, and Batch update.

How else would you like to manipulate object and relationship data in your automations? Let us know at product@customer.io. We’d love to hear your use cases!

Random Cohort Branch

While random cohorts typically send profiles down different paths, you can use the Cohort by setting to send profiles related to the same custom objectAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course. down the same path. This ensures that profiles related to the same object all have the same automation experience.

True/false branch

In true/false branches, you can send profiles down different paths based on the their relationships to objects.

All automations, except those with webhook triggers

Drag a true/false branch onto your workflow. Click the branch, then click Add condition > Relationship to define a branch based on relationships to objects in your workspace. For instance, you could trigger an automation when profiles open a page explaining a certain feature (event-triggered automations). Then you could branch them based on whether they’re related to any premium account to personalize messaging.

You can add other conditions to refine the path further - conditions are only joined by AND statements, not OR.

Object or relationship-triggered automations

In object or relationship-triggered automations, you can also refine true/false branches by the trigger object. Drag a true/false branch onto your workflow. Click the branch then click Add condition > Object-type-name (Trigger) to define a branch based on the object triggering the automation.

For instance, imagine you trigger an onboarding automation when a profile is added as an admin to any account. The onboarding flow for accounts on legacy plans is different from those on newer plans. So you add a true/false branch to your workflow and split users based on whether the account they were added to has a legacy plan type.

Or maybe you trigger an automation when an account’s plan type is upgraded to a modern one. This impacts admins of your accounts differently from all other roles so you add a true/false branch based on whether their relationship attribute role is equal to admin. For this, you’ll click Add condition > Relationship.

Multi-split branch

You can send profiles down different paths based on object and relationship conditions in multi-split branches. Unlike true/false branches, multi-split branches allow you to split profiles into more than two paths.

All automations, except those with webhook triggers

Drag a multi-split branch onto your workflow. Click the branch then click Data Type > Relationship. You can define profiles related to any object in your workspace.

For instance, imagine you want to encourage profiles to use your app after being inactive for 30 days. You could trigger an automation when they join a segment based on inactivity then branch these users based on their plan type to personalize messaging.

Object or relationship-triggered automations

With object and relationship-automations, you can also refine branch conditions based on the trigger object. Drag a multi-split branch onto your workflow. Click the branch then click Data Type > Object-type-name (Trigger).

For instance, imagine you trigger an onboarding automation when a profile is added as an admin to any account. The onboarding flow for accounts on legacy plans is different from those on newer plans. So you add a multi-split branch to your workflow and split users based on plan_type. You create different messaging for those on a legacy plan, premium plan, and all others.

Or maybe you trigger an automation when an account’s plan type is upgraded to Enterprise. This impacts profiles differently based on their role on the account, so you add a multi-split branch based on the relationship attribute role. You create different messaging for admins, managers, and anyone without those roles. For this, you’ll click Data Type > Relationship.

Trigger an automation with a relationship-based segment

Profiles enter segment-triggered automations when they join (or leave) a segment. But when you create a relationship-based segment, a profile only joins the segment for their FIRST relationship to an object matching your criteria. Their segment membership won’t change on subsequent relationships. This means that a profile will only trigger an automation for the first relationship matching your segment criteria. To trigger an automation for each relationship change, create a relationship-triggered automation.

For example, imagine that you have a segment of profiles related to online classes, and you use that segment to trigger an automation:

• When a person signs up for their first online class, their profile will join the segment and enter the automation.
• When they sign up for another online class, they won’t trigger the automation again because their segment membership didn’t change!

In this example, a profile would only re-join the segment if they unenrolled from all their classes, causing them to leave the segment, and then re-enrolled in a class later.

Exit Conditions follow these same principles: a profile won’t leave a segment (causing them to exit an automation) until they’re no longer related to any objects matching your segment criteria.

Use an object in a segment

You can create object-oriented segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. on the Segments page, or when you create automations and one-time sends. Learn more about how relationship-based segments work in automations.

1. Go to Segments and click Create Segment.
2. Give your segment a Name and a Description, and click Create Data-Driven Segment.
3. Under Add condition or group, select Relationship and set a condition to Relationship to your object type exists.

   

   
4. (Optional) you can refine your selection by clicking Refine and selecting an object-based attribute condition. For example, you might want to limit a segment based on a country or plan_name attribute.
5. When you’re done, click Save Changes.

Now you can use your segment in one-time sends or to trigger automations.

You cannot backfill relationships

We don’t have a concept of historical relationships in Customer.io—at least not yet. For example, a profile might have joined a company several years ago, but it will appear that they only recently joined the company when you set their relationship in Customer.io.

Because you can’t backfill relationships, you should be careful when using relationship-based segments to trigger your automations. For example, if you want to send a welcome automation for new employees of a company, and you relate profiles to the company after you set up your automation, you may inadvertently trigger a welcome automation for those profiles.