Documentation

Namespace

formula

kiss.formula

Formula module

Handle specific formulae that can be used inside computed fields.

View Source common/formula.js, line 9

Methods

# static ABS(number) → {number}

Returns the absolute value of a number

Parameters:
Name Type Description
number number

View Source common/formula.js, line 304

number
Example
ABS(-42) // 42

# static ADJUST_DATE(date, yearsopt, monthsopt, daysopt, hoursopt, minutesopt, secondsopt, formatopt) → {string}

Adjust a date to a new date, passing the number of years, months, days, hours, minutes and seconds to add or subtract. If the hours, minutes and seconds are not specified, they are set to 0.

Parameters:
Name Type Attributes Description
date date | string

Date or ISO date string like "2023-12-01"
years number <optional>
months number <optional>
days number <optional>
hours number <optional>
minutes number <optional>
seconds number <optional>
format string <optional>

"ISO" to return an ISO date string (default). Anything else to return a standard date object.

View Source common/formula.js, line 633

The adjusted date, as an ISO string like "2023-01-01"

string
Example
ADJUST_DATE("2023-01-01", 0, 1, 0) // "2023-02-01"
ADJUST_DATE("2023-01-01", 0, 0, 0, 48, 0, 0) // "2023-01-03"

# static ADJUST_DATE_AND_TIME(date, yearsopt, monthsopt, daysopt, hoursopt, minutesopt, secondsopt, formatopt) → {string|date}

Adjust a date to a new date and time, passing the number of years, months, days, hours, minutes and seconds to add or subtract. If the hours, minutes and seconds are not specified, they are set to 0.

Parameters:
Name Type Attributes Description
date date | string

Date or ISO date string like "2023-12-01"
years number <optional>
months number <optional>
days number <optional>
hours number <optional>
minutes number <optional>
seconds number <optional>
format string <optional>

"string" (default) or "date" to return a date object

View Source common/formula.js, line 675

The adjusted date and time, as an ISO string like "2023-01-01 12:34:56" or a date object

string | date
Example
ADJUST_DATE_AND_TIME("2023-01-01", 0, 1, 0) // "2023-02-01 00:00:00"
ADJUST_DATE_AND_TIME("2023-01-01", 0, 1, 0, 3, 0, 0) // "2023-02-01 03:00:00"
ADJUST_DATE_AND_TIME("2023-01-01 03:45:00", 0, 1, 0, 3, 0, 0) // "2023-02-01 06:45:00"
ADJUST_DATE_AND_TIME(new Date(), 0, 1, 0, 3, 0, 0) // "2023-01-01 06:45:00"

# static ARRAY(values) → {Array.<string>|Array.<number>|Array.<date>}

Converts a list of values into an array, to feed MULTI-VALUE fields.

Parameters:
Name Type Description
values *

View Source common/formula.js, line 821

The resulting array

Array.<string> | Array.<number> | Array.<date>
Example
ARRAY( "a", "b", "c" ) // [ "a", "b", "c" ]

# static AVERAGE(…numbers) → {number}

AVERAGE

Parameters:
Name Type Attributes Description
numbers any <repeatable>

View Source common/formula.js, line 275

number
Example
AVERAGE(10, 20, 30) // 20

# static CEILING(number, significanceopt) → {number}

Returns the nearest integer multiple of significance that is greater than or equal to the value. If no significance is provided, a significance of 1 is assumed.

Parameters:
Name Type Attributes Description
number number
significance number <optional>

View Source common/formula.js, line 321

number
Example
CEILING(1.01, 0.1) // 1.1
CEILING(1.01) // 2

# static CONCATENATE(…strings) → {string}

Concatenate any number of strings

Parameters:
Name Type Attributes Description
strings any <repeatable>

View Source common/formula.js, line 195

string
Example
CONCATENATE("Bob", " ", "Wilson") // "Bob Wilson"

# static CONTAINS(string, value) → {boolean}

Check if a string contains a value

Parameters:
Name Type Description
string string
value string

View Source common/formula.js, line 211

boolean
Example
CONTAINS("San Francisco", "San") // true
CONTAINS("Paris", "San") // false

# static COS(number) → {number}

Returns the COSINUS of a number

Parameters:
Name Type Description
number number

View Source common/formula.js, line 427

number
Example
COS(2 * PI()) // 1

# static COUNT(…items) → {number}

COUNT the number of items passed as parameters

Parameters:
Name Type Attributes Description
items any <repeatable>

View Source common/formula.js, line 1092

number
Example
COUNT(1, "B", "C", 7) // 4

# static COUNT_EMPTY(…items) → {number}

COUNT the number of empty items passed as parameters

Parameters:
Name Type Attributes Description
items any <repeatable>

View Source common/formula.js, line 1105

number
Example
COUNT_EMPTY(1, "B", "C", 7, "", []) // 2

# static COUNT_NON_EMPTY(…items) → {number}

COUNT the number of non-empty items passed as parameters

Parameters:
Name Type Attributes Description
items any <repeatable>

View Source common/formula.js, line 1121

number
Example
COUNT_NON_EMPTY(1, "B", "C", 7, "", []) // 4

# static DAY(strDateISO) → {string}

Get the DAY of an ISO date

Parameters:
Name Type Description
strDateISO string

View Source common/formula.js, line 519

string
Example
DAY("2022-12-24") // "24"

# static DAYS_DIFFERENCE(fromISODate, toISODate) → {integer}

Compute the number of days between 2 dates

Parameters:
Name Type Description
fromISODate string

As an ISO date string like "2023-02-14T15:44:05.886Z" or "2023-02-14"
toISODate string

As an ISO date string like "2023-02-14T15:44:05.886Z" or "2023-02-14"

View Source common/formula.js, line 591

Number of days

integer
Example
DAYS_DIFFERENCE("2023-01-01T15:44:05.886Z", "2023-01-15T18:44:26.316Z") // 14
DAYS_DIFFERENCE("2023-01-01", "2023-01-10") // 9

# static ELEMENT(array, index) → {*}

Get the nth element of an array

Parameters:
Name Type Description
array array
index number

View Source common/formula.js, line 838

The nth element, or false if the index is out of range or the array is not an array

*
Example
ELEMENT( ARRAY( "a", "b", "c" ), 1 ) // "b"
ELEMENT( ARRAY( "a", "b", "c" ), 5 ) // false
ELEMENT( "a", 1 ) // false

# static FLOOR(number, significanceopt) → {number}

Returns the nearest integer multiple of significance that is less than or equal to the value. If no significance is provided, a significance of 1 is assumed.

Parameters:
Name Type Attributes Description
number number
significance number <optional>

View Source common/formula.js, line 338

number
Example
FLOOR(1.01, 0.1) // 1
FLOOR(1.01) // 1

# static FORMAT_DATE(date, format) → {string}

Convert a date to a formatted string

Parameters:
Name Type Description
date date | string

Date or ISO date string like "2023-12-01"
format string

Ex: "yyyy-mm-dd", "yyyy-mm-dd hh:MM:ss", "yyyy-mm-dd hh:MM", "yy-mm-dd hh:MM"

View Source common/formula.js, line 707

string
Example
FORMAT_DATE(new Date(), "yyyy-mm-dd") // "2023-01-01"
FORMAT_DATE(new Date(), "yyyy-mm-dd hh:MM:ss") // "2023-01-01 00:00:00"
FORMAT_DATE("2023-12-31", "yy-mm-dd") // "23-12-31"

# static HOURS_DIFFERENCE(fromISODate, toISODate) → {integer}

Compute the number of hours between 2 dates

Parameters:
Name Type Description
fromISODate string
toISODate string

View Source common/formula.js, line 608

Number of hours

integer
Example
HOURS_DIFFERENCE("2023-01-01T15:00:00.000Z", "2023-01-02T16:00:00.000Z") // 25

# static IF(…params) → {any}

Test a set of conditions, and returns the value of the first expression that matches the test. If no condition matches, returns the value of the last (default) expression. Always has an odd number of parameters:

 IF(<condition 1>, <expression 1>, ..., ..., <condition N>, <expression N>, <expression Else>)
Parameters:
Name Type Attributes Description
params any <repeatable>

View Source common/formula.js, line 962

Value of the first expression that matches the condition, or the last expression if none matches, or false if the syntax is incorrect

any
Example
// Returns "Good" if the field "amount" = 65, or "Poor" if the field "amount" = 20
IF({{amount}} > 80, "Great", {{amount}} > 60, "Good", {{amount}} > 40, "Not bad", "Poor")

# static IF_EMPTY_USE(value, valueIfEmpty) → {*}

Check if a value is empty, and returns a default value if it is. An empty value can be an empty string, an empty array, an empty object, or a falsy value.

Parameters:
Name Type Description
value *

The value to check
valueIfEmpty *

The default value to return if the value is empty

View Source common/formula.js, line 931

The value or the default value

*
Example
IF_EMPTY_USE("", "No value") // "No value"
IF_EMPTY_USE("Paris", "No value") // "Paris"
IF_EMPTY_USE([], "No value") // "No value"
IF_EMPTY_USE([1, 2, 3], "No value") // [1, 2, 3]
IF_EMPTY_USE(0, "No value") // 0
IF_EMPTY_USE({ name: "Paris" }, "No value") // { name: "Paris" }
IF_EMPTY_USE({}, "No value") // "No value"

# static INDEX_OF(array, item) → {number}

Get the index of an item in an array

Parameters:
Name Type Description
array array
item *

View Source common/formula.js, line 857

The index of the item in the array. Returns -1 if not found.

number
Example
INDEX_OF( ARRAY( "a", "b", "c" ), "c" ) // 2

# static IS_EMPTY(value) → {boolean}

Check if a field value is empty

Parameters:
Name Type Description
value *

View Source common/formula.js, line 882

boolean
Example
IS_EMPTY([0, 1, 2, 3]) // false
IS_EMPTY([]) // true
IS_EMPTY("abc") // false
IS_EMPTY("") // true
IS_EMPTY(123) // false
IS_EMPTY(0) // false

# static IS_NOT_EMPTY(value) → {boolean}

Check if a field value is not empty

Parameters:
Name Type Description
value *

View Source common/formula.js, line 907

boolean
Example
IS_NOT_EMPTY([0, 1, 2, 3]) // true
IS_NOT_EMPTY([]) // false
IS_NOT_EMPTY("abc") // true
IS_NOT_EMPTY("") // false
IS_NOT_EMPTY(123) // true
IS_NOT_EMPTY(0) // true

# static IS_WORKFLOW_STARTED(stepName) → {boolean}

Check if a workflow has started

IMPORTANT: only valid on the client, for "hideWhen" formulae

Parameters:
Name Type Description
stepName string

View Source common/formula.js, line 1012

true if the given step name is the current step

boolean

# static IS_WORKFLOW_STEP(stepName) → {boolean}

Check the current workflow step

IMPORTANT: only valid on the client, for "hideWhen" formulae

Parameters:
Name Type Description
stepName string

View Source common/formula.js, line 993

true if the given step name is the current step

boolean

# static JOIN(array, separator) → {string}

Join an array of strings into a single string, given a separator

Parameters:
Name Type Description
array Array.<string>
separator string

View Source common/formula.js, line 807

The resulting string

string
Example
JOIN(["Paris", "San Diego", "Ajaccio"], " & ") // "Paris & San Diego & Ajaccio"

# static LEFT(text, n) → {text}

Returns the left part of a string

Parameters:
Name Type Description
text string
n number

View Source common/formula.js, line 49

text
Example
LEFT("San Francisco", 3) // San

# static LEN(text) → {number}

Returns the length of a string or an array

Parameters:
Name Type Description
text string

View Source common/formula.js, line 30

number
Example
LENGTH("San Francisco") // 13
LENGTH("") // 0
LENGTH(null) // 0
LENGTH(123) // 0
LENGTH([1, 2, 3]) // 3
LENGTH([]) // 0

# static LENGTH(array) → {number}

Returns the LENGTH of an array or a string

Parameters:
Name Type Description
array array | string

View Source common/formula.js, line 766

number
Example
LENGTH([0, 1, 2, 3]) // 4
LENGTH("Satori") // 6

# static LIST(…strings) → {string}

Concatenate any number of strings as a comma separated text

Parameters:
Name Type Attributes Description
strings any <repeatable>

View Source common/formula.js, line 1137

string
Example
LIST("A", "B", "C") // "A, B, C"

# static LIST_NAMES(…names) → {Array.<string>}

Merge a list of names into an array of names

Parameters:
Name Type Attributes Description
names string <repeatable>

View Source common/formula.js, line 1148

Array.<string>
Example
LIST_NAMES("John", "Bob", "Steve") // ["John, Bob, Steve"]

# static LOG(number, baseopt) → {number}

Computes the logarithm of the value in provided base. The base defaults to 10 if not specified.

Parameters:
Name Type Attributes Description
number number
base number <optional>

View Source common/formula.js, line 383

number
Example
LOG(1024, 2) // 10
LOG(1000) // 3

# static LOWERCASE(text) → {text}

Convert a string to lowercase

Parameters:
Name Type Description
text string

View Source common/formula.js, line 137

text
Example
LOWERCASE("San Francisco") // san francisco

# static MAX(…numbers) → {number}

MAX

Parameters:
Name Type Attributes Description
numbers any <repeatable>

View Source common/formula.js, line 261

number
Example
MAX(42, 666, 1515, 7) // 1515

# static MIDDLE(text, n) → {text}

Returns the middle part of a string

Parameters:
Name Type Description
text string
n number

View Source common/formula.js, line 79

text
Example
MIDDLE("San Francisco", 4, 8) // Fran

# static MIN(…numbers) → {number}

MIN

Parameters:
Name Type Attributes Description
numbers any <repeatable>

View Source common/formula.js, line 244

number
Example
MIN(42, 666, 1515, 7) // 7

# static MOD(number, divisor) → {number}

Returns the modulus operation.

Parameters:
Name Type Description
number number
divisor number

View Source common/formula.js, line 400

number
Example
MOD(10, 3) // 1
MOD(10, 5) // 0
MOD(10, 7) // 3

# static MONTH(strDateISO) → {string}

Get the MONTH of an ISO date

Parameters:
Name Type Description
strDateISO string

View Source common/formula.js, line 489

string
Example
MONTH("2022-12-24") // "12"

# static NOW() → {string}

Get the current date and time as a simple readable string (without time shift)

View Source common/formula.js, line 1193

string
Example
NOW() // "2022-12-24 14:53:28"

# static NTH(array, index) → {*}

Returns the NTH element of an array or a string

Parameters:
Name Type Description
array array | string
index number

View Source common/formula.js, line 788

*
Example
NTH(["low", "medium", "high"], 1) // "medium"

# static PI() → {number}

PI

View Source common/formula.js, line 413

number
Example
PI() // 3.1415927...

# static POWER(number, power) → {number}

POW

Parameters:
Name Type Description
number number
power number

View Source common/formula.js, line 367

number
Example
POW(4, 2) // 16

# static REPLACE(text, oldText, newText) → {text}

Replace a string inside another string

Parameters:
Name Type Description
text string
oldText string
newText string

View Source common/formula.js, line 167

text
Example
REPLACE("New York is great", "New York", "Paris") // Paris is great

# static RIGHT(text, n) → {text}

Returns the right part of a string

Parameters:
Name Type Description
text string
n number

View Source common/formula.js, line 64

text
Example
RIGHT("San Francisco", 9) // Francisco

# static ROUND(number, precision) → {number}

ROUND

Parameters:
Name Type Description
number number
precision number

View Source common/formula.js, line 290

number
Example
ROUND(12.367891, 3) // 12.378

# static SHORT_ID() → {string}

Generates a short id

View Source common/formula.js, line 1047

string
Example
SHORT_ID() // "A84F007X"

# static SIN(number) → {number}

Returns the SINUS of a number

Parameters:
Name Type Description
number number

View Source common/formula.js, line 441

number
Example
SIN(PI() / 2) // 1

# static SLUG(title) → {string}

Generates a slug from a plain title

Parameters:
Name Type Description
title string

View Source common/formula.js, line 181

The generated slug

string
Example
SLUG("My article about dogs") // Returns "my-article-about-dogs"

# static SPLIT(text, separator) → {Array.<string>}

Split a string into an array of strings, given a separator

Parameters:
Name Type Description
text string
separator string

View Source common/formula.js, line 1162

The resulting array of strings

Array.<string>
Example
SPLIT("Paris,San Diego,Ajaccio", ",") // ["Paris", "San Diego", "Ajaccio"]

# static SQRT(number) → {number}

Returns the square root of a number

Parameters:
Name Type Description
number number

View Source common/formula.js, line 352

number
Example
SQRT(16) // 4

# static STRLEFT(text, separator) → {text}

Returns the left part of a string, given a separator

Parameters:
Name Type Description
text string
separator string

View Source common/formula.js, line 94

text
Example
STRLEFT("San Francisco", " ") // San

# static STRRIGHT(text, separator) → {text}

Returns the right part of a string, given a separator

Parameters:
Name Type Description
text string
separator string

View Source common/formula.js, line 109

text
Example
STRRIGHT("San Francisco", " ") // Francisco

# static SUM(…numbers) → {number}

SUM

Parameters:
Name Type Attributes Description
numbers any <repeatable>

View Source common/formula.js, line 751

number
Example
SUM(1, 2, 3) // 6

# static TAN(number) → {number}

Returns the TANGENT of a number

Parameters:
Name Type Description
number number

View Source common/formula.js, line 455

number
Example
TAN(PI() / 4) // 1

# static TIME() → {string}

Get the current time as an ISO string (without time shift)

View Source common/formula.js, line 1183

string
Example
TIME() // "14:53:28"

# static TIME_DIFFERENCE(fromISODate, toISODate, unit) → {integer}

Compute the time difference between 2 dates

Parameters:
Name Type Description
fromISODate string

As an ISO date string like "2023-02-14T15:44:05.886Z" or "2023-02-14"
toISODate string

As an ISO date string like "2023-02-14T15:44:05.886Z" or "2023-02-14"
unit string

"d" for days, "h" for hours... "mn", "s", "ms"

View Source common/formula.js, line 550

Time diffence in the required unit of time

integer
Example
TIME_DIFFERENCE("2023-02-14T15:44:05.886Z", "2023-02-14T18:44:26.316Z", "h") // 3
TIME_DIFFERENCE("2023-02-10", "2023-02-20", "d") // 10

# static TITLECASE(text) → {text}

Convert a string to titlecase

Parameters:
Name Type Description
text string

View Source common/formula.js, line 151

text
Example
TITLECASE("paris") // Paris

# static TODAY(strDateISO) → {string}

Get the current date as an ISO date string

Parameters:
Name Type Description
strDateISO string

View Source common/formula.js, line 1173

string
Example
TODAY() // "2022-12-24"

# static TRIM(string) → {boolean}

Removes whitespace at the beginning and end of a string

Parameters:
Name Type Description
string string

View Source common/formula.js, line 225

boolean
Example
TRIM("  Hello   !  ") // "Hello !"

# static UID() → {string}

Generates a unique id

View Source common/formula.js, line 1034

string
Example
UID() // "01844399-988f-7974-a68f-92d35fc702cc"

# static UPPERCASE(text) → {text}

Convert a string to uppercase

Parameters:
Name Type Description
text string

View Source common/formula.js, line 123

text
Example
UPPERCASE("San Francisco") // SAN FRANCISCO

# static WEEK(strDateISO) → {number}

Get the WEEK number of an ISO date. Follow the ISO-8601 standard, where the first week of the year is the one that contains the first Thursday.

Parameters:
Name Type Description
strDateISO string

View Source common/formula.js, line 505

number
Example
WEEK("2022-12-24") // "51"
WEEK("2022-01-04") // "1"

# static YEAR(strDateISO) → {string}

Get the YEAR of an ISO date

Parameters:
Name Type Description
strDateISO string

View Source common/formula.js, line 475

string
Example
YEAR("2022-12-24") // "2022"

# static YEAR_MONTH(strDateISO) → {string}

Get the YEAR and MONTH of an ISO date

Parameters:
Name Type Description
strDateISO string

View Source common/formula.js, line 533

The year

string
Example
YEAR_MONTH("2022-12-24") // "2022-12"

# static execute(formula, record, fields, field) → {*}

Execute a formula that is an arithmetic expression mixed or not with functions calls and return the result

Parameters:
Name Type Description
formula string

The formula to parse and execute
record Object

A record object. Each object property will be available in the formula with the following syntax: "{{property_name}}" if the corresponding entry is listed in fields.
fields Array.<{label: string, id: string}>

A list of record properties sorted in a way such as {{index}} will be resolved as a record property.
field Object

The field being processed

View Source common/formula.js, line 1210

  • The formula result
*
Example
kiss.formula.execute("SUM(4, 6)") // returns 10
kiss.formula.execute("'Test: ' + (2 * SUM(3, 4))") // returns "Test: 14"
kiss.formula.execute("true && !false") // returns true
kiss.formula.execute("{{amount}} + {{vat}}") // returns 12 with record `{ amount: 10, vat: 2 }`