You are reading the documentation for an outdated Corteza release. 2024.9 is the latest stable Corteza release.

Module field expressions

Module field Expressions enables support for arbitrary expressions on module fields for:

  • value(s) expression (formula fields)

  • custom sanitizers

  • custom validators

Introduction of expressions greatly simplifies solutions that required implementation through automation script. It brings execution closer to core and within the same process, reducing overhead and improving stability and performance.

Library gval is used for parsing and evaluation of expression. This allows to reuse validators and sanitizers on front-end in JavaScript environment.

Value expressions

Value expressions allow dynamic calculation of record values from constants and other values. Only constants and values from current objects are supported.

Corteza implements this functionality by allowing value expressions on any field type. Any user input on a field with value expression is ignored.

If an error occurs while executing formula field expression, error is appended to record value error set.

Example expression for numeric field that calculates price with tax:
price * 1.25

This expression assumes there is another field named price in record values and multiplies that field with 1.25.

Example
trim(firstName + " " + lastName)

Expression assumes 2 other fields (firstName and lastName) and concatenates them with space between. Finally, we trim the result to ensure there result is not prefixed or suffixed with a space in case any of the two fields are empty.

Multi-value fields

Value expressions can also be configured on multi-value fields but need to return array of values:

Example
["foo", "bar", "baz"]

Available variables

  • old: record object with old values (this is empty when creating)

  • new: record object with new, changed values

  • <field-name>: String or array of strings with new value(s).

If field name collides with any of reserved variables (old, new) it can be accessed via old.values.<field-name>.

Sanitizers

Sanitizers aid in record value processing and cannot raise errors but can modify value. Each module field can have one or more defined expression with accompanying description or explanation.

Example of length control
length(value) > 5 ? substr(value, 0, 5) + "..." : value

Expressions are ran before built-in sanitizers. Built-in sanitizers cannot be disabled. When multiple sanitization expressions are defined they are all ran sequentially in defined order.

Sanitizer expression evaluation errors are logged.

Available variables

  • value: new value.

Validators

Validators aid in record value processing, can raise errors in case of invalid values but cannot change values. Each module field can have one or more validation groups that consist of validation expression and error message. Built-in field validators can be disabled.

Example of length control
length(title) < 5

When multiple validation expressions are defined they are all ran sequentially in defined order. Custom validators are ran after or instead of built-in field-type validators and before unique value checks. Required and unique-multi-value validators can not be disabled. Note that validation can produce multiple errors from different fields but each value is validated only until first error.

Validation expression is not executed when:

  • value is not changed

  • value is missing (this means you cannot use validator to check if value is empty; required flag on field should be used)

Available variables

  • value: new value.

  • oldValue: old value

  • values: all new values (values.<field-name>)

Available functions

General

Name, signature

Description

Example

Result

coalesce(arg1, arg2, …​argN)

Returns the first non null value

coalesce(null, 0, 1, 2)

0

Number

Name, signature Description Example Result

min(arg1, arg2, …​argN)

Returns item with the lowest value

min(0, 1, 2)

0

max(arg1, arg2, …​argN)

Returns item with the highest value

max(0, 1, 2)

2

round(number, digits)

Rounds a floating point number to the specified number of digits

round(3.14, 1)

3.1

floor(number)

Rounds number down to the nearest integer

floor(3.14)

3

ceil(number)

Rounds number up to the nearest integer

ceil(3.14)

4

String

Name, signature Description Example Result

trim(string)

Removes spaces at the beginning and at the end of the string

trim(" foo ")

"foo"

trimLeft(string, character)

Removes character from the beginning of the string

trim(" foo ", " ")

"foo "

trimRight(string, character)

Removes character from the end of the string

trim(" foo ", " ")

" foo"

toLower(string)

Converts all characters to lowercase

toLower("FOO")

"foo"

toUpper(string)

Converts all characters to uppercase

toUpper("foo")

"FOO"

shortest(arg1, arg2, …​argN)

Returns the shortest string

shortest("foo", "foobar")

"foo"

longest(arg1, arg2, …​argN)

Returns the longest string

longest("foo", "foobar")

"foobar"

Date and Time

Name, signature Description Example Result

strftime(datetime, format)

Returns DateTime string for the specified date and format

strftime(datefield, "%Y-%m-%d")

"1970-01-01"

modTime(datetime, duration)

Returns modified DateTime string

modTime(datefield, "+30m")

"1970-01-01T00:30:00"

parseISOTime(datetime)

Returns parsed ISO DateTime string

parseISOTime(datefield)

"1970-01-01T00:00:00+00:00"

parseDuration(duration)

Returns parsed duration

parseDuration("2h")

"2h0m0s"

earliest(arg1, arg2, …​argN)

Returns earliest DateTime

earliest(datefield1, datefield2)

"1970-01-01T00:00:00"

latest(arg1, arg2, …​argN)

Returns latest DateTime

latest(datefield1, datefield2)

"1970-01-01T00:30:00"