Formula Traits Overview

Formula Traits allow you to build custom formulas on various objects. This feature is available for all objects! Formula Traits enable users to perform basic mathematical operations, if/then (ternary) operations, and comparisons, providing greater flexibility and power in data management.

Creating a Formula Trait

How to create a Formula Trait:

Navigate to your Settings (⚙️) by selecting your Account Logo on the top left
Select the object you'd like to create a Formula Trait for (Accounts, Users, Notes, Custom Objects, etc.)
Then select Traits > Create custom trait
Name your trait
Add a description (this will populate when you hover over a trait so staff can see what this trait is)
Select Formula under "Type"
In the Formula Builder, enter the desired formula using other properties (data points on the same object, like other traits and success metrics), operators (mathematical functions), and aggregations (data pulled from related objects). The interface will indicate if your syntax is correct with a green "valid syntax" message or red error message.
In the Formula Builder, you can create your desired formula using three different components: Properties, Operators, and Aggregations.
1. Property: Data points in Vitally that live on the object your are building the formula for. For example, if you are building a Formula Trait at the account level, the Property selector will allow you to select any other Property of the account.
2. Operator: Mathematical expressions that you can add to your formula. This includes simple functions like division and multiplication and more complex ones like ternary and coalesce functions. We cover Operators in much more detail below, but know that you can add as many operators as you would like to your formula.
3. Aggregation: Calculations of properties on related objects (previously known as Calculated Traits). For example, for a given account, you might want to get the count of all its related incomplete tasks or roll up a trait from a related custom object. Aggregations can be used to simply rollup or display the calculated value of something that lives underneath the object, or they can be used within the formula itself. Read more about Aggregations below.
Note: As you add these components the interface will indicate if your syntax is correct with a green "valid syntax" message or provide an error message.
Select the format for the output of your formula (Number, Date, String, etc.)
If applicable, select formatting options for number traits (display as a currency and/or abbreviate large numbers)
Once the syntax is valid, select Create Trait. Values for your new trait will begin calculating immediately, but it may take some time for this to complete and for the trait values to be set on all objects.

Previewing your Formula

Underneath the Formula Builder, you have the option to select or search for an object (such as a specific Account), and the Formula Builder will use that object’s data to produce a preview of your formula and output.

If you update an existing Formula Trait, calculations can take up to an hour.

Data Types

Formula traits support a range of different data types to construct your formulas. Most of the time, the data that you will be adding to a Formula will be from the Property selector, but you are not limited to that. You can also manually type in data points directly in your formula. In either case, it is important to understand how Vitally will translate your Properties into Formulas as well as the correct syntax to use when manually entering data into a Formula. Below are the supported data types that can be used in formulas and examples on how to express them.

Data Types	Notes	Examples
Numbers	You can use numbers in your formulas by simply writing them as you would in a calculator, or by inserting another property with the "Number" type. Use standard numerical formats, avoiding commas.	Numbers Examples: Supported 100 ✅ 3.1415 ✅ Not Supported: 1,000,000 🚫 (don't use commas)
Dates and Datetimes	Datetimes are actually represented as numbers in formulas, using a convention known as an “epoch timestamp”. Dates are represented similarly, and use the time at midnight in UTC on the given day. You can enter dates and times in your formulas using the provided date and datetime operators, which will convert text representations of the date or time into a timestamp. Various formats will be recognized and parsed, but we recommend using standard ISO date and datetime formats (e.g., `2020-01-01T12:00:00Z`).	Dates & Datetime examples: `date(’2020-01-01')` → 1577836800000 (January 1, 2020) `datetime(’2020-01-01T14:00:00Z’)` → 1577887200000 (January 1, 2020 2pm UTC) `datetime('2020-01-01T14:00:00-05:00')` → 1577905200000 (January 1, 2020, 2pm New York
String	A string is a data type used for text or a series of characters. Enclose your text in either double or single quotes (`”` or `'`) to create a string. Note that if your text contains `"` you can use `'` as the enclosing character, and vice versa. If your string contains both, use the `\\` escape character.	String examples: `"healthy"` → healthy `'William "Billy the Kid" Bonney'` → Wiliam “Billy the Kid” Bonney `'"Don\\’t step on my blue suede shoes” - Elvis'` → "Don't step on my blue suede shoes" - Elvis `'don't do this'` → 🚫
Array	Arrays can be used to represent lists of values in your formulas, and are written using brackets enclosed in quotes `'[]'` or `"[]"`. When you use a “multiselect” trait in a formula, it will be entered as an array.	Arrays Examples: `'[ “trial”, “enterprise” ]'` → trial, enterprise `”[ 3, 100 ]”` → 3, 100
Boolean	Boolean values are `true` and `false` and can be used to represent and evaluate logic in your formulas.
Null and Undefined	Null and undefined represent the absence of a value (ie. a trait that has never been set will be `undefined` and one that has been set to have no value will be `null`). You can write them in your formulas directly as `null` and `undefined`.

Operators

Vitally supports a range of mathematical expressions (Operators) that can be used in Formulas. From simple simple functions like division and multiplication to more complex ones like ternary and coalesce functions, you are able to combine these together to create really powerful Formulas. Below is a summary of each supported Operator, what it does, and examples of how they function.

Operator	Notes	Examples
Mathematical Operators	Mathematical operators obey normal order-of-operations rules, and parenthesis may also be used for grouping. Division by zero is invalid and may result in errors.	Mathematical operator examples: `1 + 1` → 2 `1 - 1` → 0 `1 * 1` → 1 `1/1` → 1 `1 + 1 / 2` → 1.5 `(1 + 1) / 2` → 1 `10 / (1 - 1)` → Invalid/ may result in errors
Comparators	Comparators use the “equals” (==) and “does not equal” (!=) operators to test if values are the same in your formulas, or “greater than” (>), “less than” (<), “greater than or equal to” >=, and “less than or equal to” (<=) to compare the values of numbers.	Comparator operator examples: `1 == 1` → true `1 != 2` → true `1 > 2` → false `2 <= 100` → true `'at risk' == 'at risk'` → true `’At risk’ == ‘at risk’` → false (string comparisons are case-sensitive) `null == null` → true `null == undefined` → false `undefined == undefined` → true
`max()`	Get the maximum value of the values passed in. Will return the latest value if used with dates/datetimes.	`max(1, 2, 0)` -> 2
`min()`	Get the minimum value of the values passed in. Will return the earliest value if used with dates/datetimes.	`min(4, 8, 2)` -> 2
Boolean operators	Formulas support `and`, `or`, and `not` operators when working with booleans.	Boolean operators examples: `true and true` → true `true and false` → false `false and false` → false `true or true` → true `true or false` → true `false or false` → false `not true` → false `not false` → true `1 + 2 == 3 and 4 > 1` → true `'x' == 'x' and not ('y' == 'z')` → true
If/Then	If/then conditional logic is available in formulas via a ternary operator: `a ? b : c` where “a” is the conditional statement, b is the value to return if the statement is true, and c is the value to return if it is false, so “if a then b, otherwise c”. Ternary statements can be nested to form chains like “if … else if …. else if … else” , for example pulse == 'great' ? 10 : pulse == 'ok' ? 5 : pulse == 'poor' ? 0 : null will return 10 if the pulse is great, 5 if it’s ok, 0 if it’s poor, and nothing if it is anything else.	If Then operator examples: `4 > 3 ? 'yes' : 'no'` → yes `4 < 3 ? 'four less than three' : 4 == 3 ? 'four equal to three' : 4 > 3 ? 'four greater than three' : 'something else'` → four greater than three
`contains()`	To check if an array contains a particular value, use the `contains` operator.	Contains operator examples: `contains("[ 'red', 'green', 'blue' ]", 'green')` → true `not contains("[ 'red', 'green', 'blue' ]", 'yellow')` → true
`coalesce()`	When working with properties that may or may not be set, it is frequently useful to define “fallback” values using the `coalesce` operator, which will return the first value passed to it that is not `null` or `undefined`.	Coalesce operator example: `coalesce(undefined, null, undefined, 4, 'green')` → 4
`dateAdd()`	Advance a date or time by a number of hours, days, months, etc. (learn more about date operators below)	dateAdd ( ) operator example: `dateAdd(date('2020-01-01'), 5, ‘days')` → Jan 6, 2020 `dateAdd(datetime(’2020-01-01T12:00:00-05:00’), 1, 'hour')` → Jan 1, 2020 1pm in New York
`dateSubtract()`	Set a date or time back by a number of hours, days, months, etc. (learn more about date operators below)	dateSubtract ( ) operator example: `dateSubtract(date('2020-01-01'), 1, 'day')` → Dec 31, 2019 `dateSubtract(datetime('2020-01-01T12:00:00-05:00'), 1, 'hour')` → Jan 1, 2020 11am in New York
`dateDifference()`	Get the difference between two dates or times in a given time unit. (learn more about date operators below)	dateDifference ( ) operator example: `dateDifference(date('2024-07-14'), date('2024-07-13'), ‘days’)` → 1
`now()`	Get the current datetime (more info)

Aggregations

Aggregations (previously available as "calculated traits") are calculations using properties of related objects. For example, for a given account, you might want to get the number of related incomplete tasks or roll up a trait from a related custom object. Available aggregations include:

Sum - total sum of values of a property of the related objects
Unique - count of distinct values
Count all - total count of the related objects
Average - mean value of a number property of the related objects
Rollup - a single property value selected from one of the related objects

Aggregations can be used in formulas for Account and Organization traits, and can pull data from Users, Tasks, Active Conversations, Notes, Meetings, and Custom Objects.

To use an aggregation in a trait, select it from the "Aggregation" dropdown in the Formula Builder, and then configure it in the right panel.

When there are no objects included in an aggregation where the operation is sum, average, or rollup, the value will be set to null instead of zero, which allows traits with no values to be excluded from health scores or filters that ignore nulls.

Working with dates and datetimes

We enable several types of date formulas: difference between two dates, adding time to a date, and subtracting time from a date. In each instance, you could either use a property from the property selector to input your date, or you could manually type a date. See more about how to format dates below.

Difference between two dates

dateDifference calculates the difference between two dates or datetimes. For example:

dateDifference(date1, date2, "day")

In this format, the date farther in the past is date1. “Day” specifies the time unit you’d like the output to be calculated in. You could also specify that you want the output in year, month, week, day, hour, minute, or second. You may either add date or datetime properties from the property selector or type in a date manually.

Let’s say that we wanted to calculate the time between the Kickoff Date and the Onboarding Completion Date. I would build the formula as follows, and the correct format for the output will be Number.

In the above example, the formula shows that for Ebay (Slovakia), the difference between Kickoff and Onboarding Completion is 48 days.

When using the dateDifference operator to compare datetimes or a date and a datetime, be aware that the calculation will be done according to the UTC timezone. For example, the following formula returns 0, not -1, because midnight on January 1st in New York is 5AM in UTC (and therefore less than a day away from midnight on January 2nd in UTC).

dateDifference(
 datetime('2025-01-01T00:00:00-05:00'),
 date('2020-01-02'),
 'day'
)

Date Addition

dateAdd allows you to add time to a date or datetime.

For example, let’s say that it’s standard practice for the CSM and the AE to connect 30 days after Kickoff to evaluate the company’s success and provide the AE feedback on the sales process. We could build that formula this way:

dateAdd(Kickoff Date, 30, "days")

Remember to format your output as either date or datetime to get a usable value.

Date Subtraction

dateSubtract allows you to subtract time from a date or datetime.

Let’s say I wanted to build a trait that provides the date 90 days before the renewal. We could build that formula this way:

dateSubtract(Next renewal date, 90, "day")

Remember to format your output as either date or datetime to get a usable value.

`date()` and `datetime()` operators

The date and datetime functions allow you to input dates or datetimes as text and convert them to their numerical values

Formatting dates

In any of the formulas we specified above, you could either use a property from the property selector, or you could type in your own date. For example, we could write the dateAdd formula both of these ways:

dateAdd(Kickoff Date(Account), 30, "days") 
dateAdd('2024-10-03', 30, "days")

We highly encourage using the ISO standard for formatting dates and datetimes, but various other formats may also work:

suggested (date): 2024-10-03
suggested (datetime): 2024-01-03T00:00:00Z
others: Oct 03, 2024, October 3, 2024

Using the `now()` operator

now() allows you to use the current datetime in your formula. Formulas are evaluated periodically throughout the day, so the value of now() will not always be exactly precise, as it will reflect the last time the formula was evaluated and the value updated.

Formula Trait FAQs

Q: What will happen if I build a Formula Trait that uses bad syntax?

A: When building formulas, the formula builder will tell you if your syntax is acceptable or if it requires adjustment. At the bottom of the formula box, you’ll either see a green “valid syntax” or red "invalid syntax" message. Users will be prevented from saving formulas that contain invalid syntax.

Q: What if I use unsupported notation

A: If you use a notation that isn't supported, the formula builder will behave the same way as with bad syntax. You'll get an error message, and the formula can't be saved until you fix it.

Q: How often will Formula Traits be calculated?

A: We re-evaluate formulas hourly for non-churned records and daily for churned records. You can check when a formula was last updated under Trait Settings.

Q: Can you use Formula Traits within Track Rules in Lifecycle Tracking?

A: No, formulas cannot be used for Track Rules within Lifecycle Tracking. Formulas are not calculated for ignored records.

Q: How do I build a formula that returns text?

A: Example: Let’s say you’re trying to identify customers who need retraining and are making this determination by evaluating low product usage. Your formula might pull in different event data; however, you don’t want the CSM to have to know what “too low” means. Further, you might want to tweak the formula over time to hone in on customers who truly need retraining. Therefore, you want the resulting trait value to simply show “retraining candidate”.

In this instance, we’d want to specify the Trait output as string and specify what string should be used in the formula. Ternary is the most helpful formula to use here.

(Count of button clicks + Count of downloads) < 10 ? 'Retraining candidate' : null

In the above formula, we specify that if the sum of button clicks and downloads is less than 10, the text should say “Retraining candidate.” Otherwise, it should not say anything.

Q: How do I check for values in multi select traits?

contains() is helpful if you’re trying to identify if a multi-select trait includes a particular value or set of values.

For example, I might have a multi-select field for Champion Type, and the available values to choose from could include "G2 review" "quote" "reference" "promoter NPS" "beta tester". I could use contains() to pull out customers where “quote” is one of the selected options. The formula is written like this:

contains(Champion Type, 'quote')

Please note that the formula can only recognize exact matches. So you could not use 'G2' you would need to input 'G2 review'

If you wanted to search for a mix of the traits, you could combine them with and or or, like contains(Promoter Type, 'quote') and contains(Promoter Type, 'G2 review').

Examples and Use-cases

Building activity traits like "Upcoming Meeting" or "Recent Meeting"

Most Recent Meeting

Let's say I want to see the date of the most recent meeting that took place with an account, even if the meeting has a recurring cadence. I can create a formula trait to pull this data and surface it on the account! Here's how:

Select Rollup as the Aggregation
Select Meetings as the Object
Select Start as the Property
Select Date > Last as the Select by
Select Start > Is greater than > 0 Days ago for the Where clause
If you want to only surface recurring meetings, you can also add: Is recurring > is true

Note that, in formulas, date filters are evaluated in UTC, so this formula will include all meetings that started before today in that timezone.

Upcoming Meeting

Now let's say I want to see the date of the next upcoming meeting for an account, and the meeting has a recurring cadence. I can create a formula trait to pull this data and surface it on the account! Here's how:

Select Rollup as the Aggregation
Select Meetings as the Object
Select Start as the Property
Select Date > First as the Select by
Select Start > Is greater than > 0 Days from now for the Where clause
If you want to only surface recurring meetings, you can also add: Is recurring > is true

Note that, in formulas, date filters are evaluated in UTC, so this formula will include all meetings that started after today in that timezone.

Today's Meeting

Let's say I want to see Meetings that take place today. I can create a formula trait to pull this data and surface it on the account! Here's how:

Select Rollup as the Aggregation
Select Meetings as the Object
Select Start as the Property
Select Date > Last as the Select by
Select Start > Is less than > 1 Days from now for the Where clause
If you want to only surface recurring meetings, you can also add: Is recurring > is true

Note that, in formulas, date filters are evaluated in UTC, so this formula will show the last start date of a meeting that falls on "today" in that timezone.

REST API: Projects

REST API: Custom Traits

REST API: Custom Objects

Traits

Displaying 0 Instead of Null in Formula Traits in Vitally