Expressions

An expression is any combination of operators, constant, functions and names of fields that evaluates to a single value. Expressions are easier to read then velocity scripts, but they can contain one single line only. That makes them very useful for simple calculations, but as soon as the calculation becomes more complex, it is advised to switch to velocity.

Operators

Operators specify the type of calculation that you want to perform. The Application Engine includes three different types of operators: arithmetic, comparison and text.

Arithmetic operators

Arithmetic operators perform basic mathematical operations such as addition, subtraction or multiplication and produce numeric results.

substracting a date field from another date field will return the difference in time between them in string format. This works for time fields as well

Comparison operators

Comparison operators compare two values and they produce the logical value true or false.

Text operator

& (ampersand). Connects or concatenates two values to produce one continuous text value

Boolean operator

use boolean operators and and or for your condtions

Constants

A constant value, a word or piece of text, in quotes, eg. "Dear". 

Functions

If (arg1;arg2;arg3)

If is a function with three arguments. The first one is a so called conditional expression which must evaluate to either true or false. The second argument is an expression, which will be the result of the function when the conditional value evaluates to true. The third argument will be the result of the function when the conditional value evaluates to false.

simple example: Gender is a field with a lookup list containing "male" and "female". Suppose the field Gender evaluates to "female", then the function if(Gender="male";"Mr.";"Mrs.") returns "Mrs.".

now()

Returns the current time and date.

AddDay(arg1;arg2)

AddDay() is a function that takes 2 arguments. The first one should be a date or date time expression and the second an integer expression. The result of the function is a date or date time expression by adding the result of the second argument as number of days to the result of the first expression.
A simple example: DateOfBirth is a field with data type Date. Suppose the field DateOfBirth evaluates to 01-01-2007, then the function Addday(DateOfBirth; 5) returns 06-01-2007. This also works with negative values.

AddSecond(arg1;arg2)

AddMinute(arg1;arg2)

AddHour(arg1;arg2)

AddMonth(arg1;arg2)

AddYear(arg1;arg2)

Can be used in the same way as AddDay().

DiffInDays(arg1;arg2)

DiffInDays() is a function with 2 date expressions as arguments. The result is the number of days between the two dates.
A simple example: StartDate end EndDate are fields with data type Date. Suppose StartDate evaluates to 01-01-2007 and EndDate to 06-01-2007, then the function DiffInDays(StartDate; EndDate) returns 5.

It's also possible to use an actual date; now(). Suppose the current date we retrieve with function now() evaluates to 21-01-2008 and the field ExecutionDate contains the date 26-01-2008, the function DiffInDays(now(); ExecutionDate) returns 5.

day(arg1)

month(arg1)

year(arg1)

 Returns the day, month or year of a date or datetime object (arg1).

left(arg1;arg2)

right(arg1;arg2)

 Trims string arg1 down to size arg2 (has to be an int), keeping the left- or rightmost part respectively.

mid(arg1;arg2;arg3)

Trims string arg1 down by removing all characters except for those from arg2 to arg3 (have to be integers).

length(arg1)

 Returns the length of string arg1. Also works on memo fields.

lower(arg1)

upper(arg1)

 Change all characters in string or memo arg1 to lower or upper case respectively.

replace(arg1;arg2;arg3)

replaceFirst(arg1;arg2;arg3)

 Replace the first occurence of string arg2 in string (or memo) arg1 by string arg3.

replaceAll(arg1;arg2;arg3)

 Replace all occurences of string arg2 in string (or memo) arg1 by string arg3.

Examples

Conditional expression

Suppose you have the following fields in a class 'person': 'Gender' (with lookup list: male, female) and 'Last name'. Now you want to create a new field Salutation, e.g. to be used at the head of a letter.

Create a new field 'Salutation' in the class Person.

Go to the tab Calculation and choose Expression from the list of Built-in calculations. At the tab Parameters you select the parameter 'Expression' and enter the following: "Dear " & Last name.

Suppose there is a person with last name Jones, then the result of the calculation will be: "Dear Jones".

To obtain a gender specific and more common salutation you can put the following expression in the value field:

"Dear " & if(Gender="male";"Mr.";"Mrs.") & " " & Last name.

Now, if a person is a male and has last name Jones, then its salutation will be "Dear Mr. Jones" and otherwise it will be "Dear Mrs. Jones".

In case you have three values (male, female and unknown) in your lookup list for 'Gender' and you want a different salutation for each value in the lookup list, then you can solve this with the following expression:

"Dear " & if(Gender="male";"Mr.";if(Gender="female";"Mrs.";"Mr./Mrs.")) & " " & Last name.

Now, the salutation will be either "Dear Mr. Jones", "Dear Mrs. Jones" or "Dear Mr./Mrs. Jones" depending on the value of the field 'Gender'.

In many common conditional expressions you want to check if a certain field has a value or not. For instance, in our first version of the salutation example, the expression evaluates to "Dear Mrs. Jones", when gender is female, but also when there is no gender. If you want to treat this as a special case, then you can solve this with the use of null in the following expression:

"Dear " & if(Gender=null;"Mr./Mrs.";if(Gender="male";"Mr.";"Mrs.")) & " " & Last name.

Now, the salutation will be "Dear Mr./Mrs. Jones" if there is no gender, "Dear Mr. Jones" if gender is male and "Dear Mrs. Jones" if gender has a value different from male.

In this way you can make almost any concatenation of fields using only the concat-operator &  in combination with the function if.