Classic expressions can not be directly connected to next-gen features, please consider using next-gen actions if you wish to use value calculations for your application.
Read this reference if you would like to know what kinds of expressions there are.
Use expressions in your actions to get specific and complex results you can not get from static data model properties.
Consider carefully when you use a property expression since an expression is triggered on every create and update. When there are too many expressions or the expression is triggered a lot of times, then it will hurt its performance. Furthermore, the expression’s output will not instantly be generated. If your actions rely on the expression’s output (for example in a PDF template), you might get some unexpected or blank results.
Good to know: every time an expression has to be calculated, the background jobs will be automatically paused. After finishing all the expressions, the background jobs will be continued.
Best practice
To get better performance and more flexibility, use one of the properties (without expression):
-
CHECKBOX
-
DATE
-
DATETIME
-
MINUTES
-
NUMBER
-
NUMBER WITH DECIMAL
-
PRICE
-
TEXT
Create an action with the trigger BEFORE SAVE or AFTER SAVE (dependent on which case). The action can calculate the expression and save the desired output every time a record is saved.
Note: We advise creating expressions in your action and assigning the value to your model object instead of creating expressions within your data model to keep the calculation speed to a minimum.
Basic operators
All basic mathematical operators can be used in expressions. Take a look below! If you want to use a variable in an expression, you can use var: followed by the name of the variable. In this example, we're using the variables a and b.
You can also use the words and - or instead of the operators & and |.
Also, you can use brackets ( ) in the same way you use brackets in mathematics. Note: The different results as between 2 + 2 * 2 = 6 and (2 + 2) * 2 = 8. This is the same for `var:a + var:a * var:a = 6 and (var:a + var:a) * var:a = 8`.
You can also use the words and - or instead of the operators & and |.
Also, you can use brackets ( ) in the same way you use brackets in mathematics. Note: The different results as between 2 + 2 * 2 = 6 and (2 + 2) * 2 = 8. This is the same for `var:a + var:a * var:a = 6 and (var:a + var:a) * var:a = 8`.
any_blank? (array)
Checks if there are blank values in the collection.
Returns true or false.
any_nil?(collection)
Checks if there are nil values in the collection. Returns true or false.
Note: There's a difference between nil and "" (blank).
any_not_blank?(collection)
Checks if there are non-blank values in the collection.
Returns true or false.
any_not_nil? (collection)
Checks if there are non-nil values in the collection.
Returns true or false.
any_starts_with? (collection, value)
Checks if there's any objects starting with the value entered in the expression.
array[number]
Returns the object/record corresponding to the number in an array/collection, where 0 is the first.
Note: Text values need to be quoted when used in variables, numeric values don't. Note the difference in [1, 2, 3] and ["a", "b", "c"]. Double or single quotes both suffice.
avg (array)
Returns the average of an array of numbers.
base64_decode (value, format, extension)
You can use this to decode a base64 text or a base64 file.
To assign to a file property, you'll need to do the decode expression in an URL expression.
The third parameter is considered to be a file with extension, when the name contains a ..
When decoding with the "file" option, a temporary file is generated. At the end of the action, this file is discarded. Make sure to assign it this file is required.
base64_encode (text/file)
base64_encode() lets you encode a file or text in base64 format. Base64 encoding is used in several web services, but is also a good way to transfer files.
Warning: We recommend the use of the base64 expression for the transfer of files. Be careful not to save files while encoded, as this may harm the load on your application.
beginning_of_month (date)
Returns the date of the first of the month from the given date.
blank? (record)
blank?(var:record) is the direct opposite of present?(var:record)
Checks if a record or variable exists. Returns false if the record or variable exists.
boolean_match (value, regex)
Checks if a value matches a Regex. Returns true or false.
business_days_offset (date, number_of_days)
Returns a date which is the date + the given business days (/weekdays).
capitalize (string)
Changes the first letter of a string to a capital.
ceil (number)
Returns the next highest integer value by rounding up value if necessary.
concat (array, string)
Combines the values of an array. The second parameter defines the addition between the values.
count (array)
Array
Hash
String
Returns the number of items in an array and hash, or returns the number of characters in a string.
count_full_collection (collection)
Count the number of records in a collection, ignoring the set limit, without rendering the full collection.
day (date/datetime)
Returns the day from a specific date as a number expression.
days (amount)
Use an amount of days in a calculation.
days_offset (date, number)
Returns a date, which is the date + the given days.
decode_jwt(algorithm, secret, jwt)
Decodes a JSON Web Token.
downcase(string)
Transforms all characters of a string to lowercase.
end_of_month(date/datetime)
Returns a new date representing the end of the month.
errors!(object)
Executes validations and returns the errors (if any) as a hash, in one go.
exclamation
! is the logical NOT Operator. Use to inverse the logical state of its operand. If a condition is true, then logical NOT operator will make false.
extname(file)
Returns the extension of a file.
fetch(hash, key, default)
Returns the value for a given hash and key, with an optional default in case the key does not exist for the hash.
float(string)
var:text = "2.5"
float(var:text) >>> 2.5
float("2,39") >>> 2.0
Transforms a string to a float (decimal number). Only accepts . as a decimal delimiter.
floor(number)
Returns the largest integer less than or equal to the given (decimal) value.
generate_jwt(algorithm, secret, payload)
Generate a JSON Web Token.
generate_uuid()
Generate a unique identifier following the UUID format. An example of when to use a UUID is when calling an external API via HTTP Request events, where the receiving API expects each request to have a unique identifier.
gethostbyname(domain)
Returns an IP address based on the given domain.
hash?(variable)
Checks if a variable can be parsed as a hash. Returns true or false.
hmac_sha256(text, secret)
Creates a hmac_sha256 hash and requires two arguments: the string for which you want to calculate the digest and a secret key that must be included in the calculation. It is mainly used for authentication with external API connections. You can use it to create an encrypted password.
hmac_sha384(text, secret)
Creates a hmac_sha384 hash and requires two arguments: the string for which you want to calculate the digest and a secret key that must be included in the calculation. It is mainly used for authentication with external API connections. You can use it to create an encrypted password.
hmac_sha512(text, secret)
Creates a hmac_sha512 hash and requires two arguments: the string for which you want to calculate the digest and a secret key that must be included in the calculation. It is mainly used for authentication with external API connections. You can use it to create an encrypted password.
hours(amount)
Use an amount of hours in a calculation.
ifelse
A boolean expression replacement for IF ELSE.
ifnil(value, default)
A conditional statement constructor. ifnil evaluates its argument and branches and checks on nil values. If a nil value applies, the default value is rendered instead.
include?(array, object)
Returns true if the given object is present in self.
int(value)
Converts a text to an integer.
keys(hash)
Returns an array of all keys in the hash.
ljust(text, number_of_characters)
Adds a specific number of whitespaces right of a text value, so the width matches the number given in the expression.
localize(date)
Returns a date value in the given format, based the application's locale.
math_sqr(number)
Returns the square of the variable in the brackets.
math_sqrt(number)
Returns the squareroot of the variable in the brackets.
math_sin(number)
Returns the sine of the variable in the brackets.
math_cos(number)
Returns the cosine of the variable in the brackets.
math_tan(number)
Returns the tangent of the variable in the brackets.
math_asin(number)
Returns the arcsine of the variable in the brackets.
math_acos(number)
Returns the arcosine of the variable in the brackets.
math_atan(number)
Returns the arctangent of the variable in the brackets.
math_atan2(number, number)
Returns the arctangent of the two variables in the brackets.
math_log(number)
Returns the logarithm of the variable in the brackets.
math_log2(number)
Returns the logarithm with base 2 of the variable in the brackets.
math_log10(number)
Returns the logarithm with base 10 of the variable in the brackets.
math_abs(number)
Returns the absolute of the variable in the brackets.
math_deg_to_rad(number)
Returns the radian number of the variable in the brackets.
math_rad_to_deg(number)
Returns the degrees of the variable in the brackets.
math_pi()
Returns pi.
math_exp(number)
Returns the output of Euler by the power of given value(x) in the brackets. (e^x)
math_e()
Returns Euler.
max(array)
Returns the highest number of an array of numbers.
md5(text)
Creates an md5 hash of text.
Note: We do not recommend using this expression for encryption of sensitive data. It can still be used for other, none-cryptographic purposes, though. See MD5 for more information.
min(array)
Returns the lowest number of an array of numbers.
minutes(amount)
Use an amount of minutes in a calculation.
mmatch(value, regex, index_of_matched_value)
Returns the result of matching a text value against a regex, divided in groups ( ).
Modulo(number, divider)
Returns the remainder after division of one number by another.
modulo_round(number, divider)
Rounds up the first value, so the modulus returns 0.
monday_of_week_number(year, weeknumber)
Returns the date of the monday of the given week and year
month(date/datetime)
Returns the month from a specific date as a number expression.
months(amount)
Use a number of months in a calculation.
newline
Inserts a \n, resulting in continuing on a new line.
nil?(record)
Checks if a fields value is empty. Returns true or false.
now
Returns the current date and time as a date time expression.
num_weeks_between_dates(date, date)
Returns the difference between given dates, in weeks.
num_weeks(year)
Returns the number of weeks in the given year.
only_numbers(string)
Returns all numeric characters from a string.
parameterize(string)
parameterize("betty blocks") >>> betty-blocks
Transforms a string to a parameter, making it a URL-friendly value.
pow (value, power)
Returns the outcome of var:a raised to the power of var:b
present? (variable)
present?(var:record) is exactly the same as !(blank?(var:record))
Checks if a record or variable exists. Returns true if the record or variable exists, returns false if not.
random (number)
Returns a random number between 0 and the given number.
random_hex (number)
Generates a random hexadecimal string. The number argument defines the number of characters used for the string.
random_hex (number)
Generates a random hexadecimal string. The number argument defines the number of characters used for the string.
read_file (text_based_file)
Returns the content of a text-based file.
regex_replace (value, what_to_replace, replace_with_what)
Replace a certain value with a different value. You'll need this one to perform a replace on "unreadable characters" and anything with a backslash. These include newlines (\n), tabs (\t) and carriage returns (\r).
replace(value, what_to_replace, replace_with_what)
Replace a certain value with a different value.
rjust(text, number_of_characters)
Adds a specific number of whitespaces left of a text value, so the width matches the number given in the expression.
round(number with decimal, number)
Rounds a number with decimal to a whole number, or to a precision equal to the number given as second parameter.
rsa_decrypt (encrypted_text, private_rsa_key)
Decrypts encrypted values into plain text through a private RSA-key.
rsa_encrypt (values, public_rsa_key)
Encrypts values into an RSA Message through a public RSA-key.
The text to encrypt must be shorter than the RSA-key.
The maximum size for an RSA-key of 2048 bits is 2048 / 8 => 256 characters
sample (collection)
Returns a random object from the collection.
seconds (number)
Use an amount of seconds in a calculation.
sha1 (text)
Creates a sha1 hash of text, using the SHA-1 encryption method.
sha256(text)
Creates a sha256 hash of text, using the SHA-2 encryption method, using a 256-bit sized digest.
sha384 (text)
Creates a sha384 hash of text, using the SHA-2 encryption method, using a 384-bit sized digest.
sha512 (text)
Creates a sha512 hash of text, using the SHA-2 encryption method. using a 512-bit sized digest.
shuffle(collection)
Returns the collection in a random order.
slice (array, start, length)
Slices an array/collection from the given start value, for the given length.
split(string, argument)
Returns an array after splitting a string on an argument/value.
squeeze (string)
Removes double whitespaces from a string.
starts_with? (string, string)
Checks if a text value starts with the second given text value. Returns true or false.
str(value)
Converts a value to a string.
strftime (datetime, format)
Creates a string based on a format applied to a datetime. Use this as a text expression.
Note: The return value of strftime with parameter %U (week of the year) returns the value 00 as the first week of the year and increases by 1 for every new week of the year.
Click here for all date formats.
string operators
Some basic operators also work on strings. You can use a plus ( + ) to concatenate two strings and an asterisk/times ( * ) to repeat a string a number of times.
string_to_hash (string)
Transforms a string to a hash.
strip (string)
Removes all trailing whitespaces of a string.
substring (value, start, end)
Returns characters from a selection of a string.
sum (array)
Returns the sum of all the values in an array.
time_in_timezone (datetime, timezone)
Returns the given timestamp in a different timezone.
to_json (text)
Transforms text to JSON format.
today
Returns the current date as a date expression. If used as a date time expression, the time will be set to 00:00:00.
Warning: this expression is no longer functional in the data model expressions. this expression can only be used in action steps for the time being and will be phased out with the "today" time selecter in action expressions in the future.
transliterate (value)
Transliterates UTF-8 characters to ASCII.
truncate (string, number_of_characters, trailing_text)
Shortens a string, closed by trailing text, based on the maximum number of characters. Maximum number includes the trailing text. By default, "..." is used as trailing text. By including a third parameter, you can choose your own trailing text.
uniq(array)
Removes all double values in an array, returning only unique values.
upcase(string)
Transforms all the letters of a string to uppercase.
valid?(object)
Checks if the record or custom model is valid.
values(hash)
Returns a collection of all values in a hash.
working_days(date, date)
Calculates all working days between two days. Returns an array of dates.
weeks (amount)
Use an amount of weeks in a calculation.
xml_to_json (xml)
Transforms XML formatted text to JSON formatted text.
xpath (xml, path)
Returns the element(s) and their values of an XML formatted text. If you only want the value, append /text() to your path.
Add true to the expression to ignore any other attributes (like xmlns="value").
Note: Use tools like this xpath generator if you don't want to search for the precise path you need yourself.
year (date/datetime)
Returns the year from a specific date as a number expression.
years (amount)
Give an amount of years for usage in a calculation.