Advanced formula




Advanced formula give more control and allow reference to attributes and issue field




Overview

With advanced formula, you can reference other attributes and issue fields. You have more control and you can return more complex calculations.

An advanced formula is a fragment of script that returns a value. This value is the calculated value displayed in your attribute.

Example of formula:

if (element['Apply discount']) {
	return (element.Amount * (100-issue['Discount rate(10001)'])/100);
}
else {
	return element.Amount;
}


Types

As you might have noticed in the example above, there are constants in the formula ('Discount', 0.9) and there are also references to attributes or issue fields.

These constants and references represent data. Data have a type :

TypeExplanationExamples
NumberRepresents a number0.5, 158, 1e-1
StringRepresents a string of text'Discount', "Value"
BooleanRepresents a boolean logical valuetrue or false
Null

Represents an empty value.

This cannot be referenced directly, but can be the result of a reference evaluation


Returning a value

The main reason for formula is to return a value to display (or use elsewhere). This is achieved by a return instruction:

return 2 * element.count;

A return instruction is final. That means that when the execution reaches a return instruction, the execution ends.

Arithmetic expressions

Syntax

return 2 * element.count;

Like in basic formulas, you can use the following arithmetic expressions. If one of the arguments is a string, the string concatenation applies (see below)

OperationOperatorExampleRemark
Addition+load + 5.3If load is a string, then string concatenation is applied. See next paragraph
Subtraction-load - 5.3
Multiplication*load * 0.9
Division/

load / 2


Type conversion

When you use types that are not numbers, they are converted before the operation can be performed.

String concatenation

There is one special case : when using the + operator and one argument is a string, the operation is not an arithmetic addition but a string concatenation.

Conversion rules:

TypeConversion
NumberN/A
Boolean

true is converted to 1

false is converted to 0

String

If the string represents a number, it is converted to this number.

If the string does not represent a number, the result is an error and the evaluation stops.

Nullnull is converted to 0

If you want to use a string that represents a number in an arithmetic expression, you will need to force it to a number. This can be done with the + operator like this : +'12' alone is converted to a number. See the examples below.


Examples

ExampleResultExplanation
1 + 23
1 + "2""12"String concatenation applies because one of the arguments is string
"abc" + 56"abc56"Same as above
5 + element.amount5If the amount attribute is empty, it evaluates to null which is converted to 0
12.5 / 0Division by zero errorWhen a division by zero is attempted, an error is raised and the evaluation stops
55 / "abc"Number conversion error
8 + true9Type conversion of true gives 1
5/(1-true)Division by zero errorType conversion of true gives 1
+"12"12The string is converted to a number
-"12"-12The string is converted to a number
1-"12"Number conversion error

The string is not converted to a number directly by the operator.

1-(+"12")-11By grouping and using the +/- operator alone, the string is converted to a number
+"abc"Number conversion error


String concatenation

Syntax

return "12." + element.remainder;

As explained above, when you use the '+' operator on two arguments and one is a number, the result of the operation will be a string concatenation.

Type conversion

Conversion rules:

TypeConversion
NumberThe number is converted to a string representing the number value.
Boolean

true is converted to "true"

false is converted to "false"

StringN/A
Nullnull is converted to "null"

Examples

ExampleResultExplanation
"abc" + "def""abcdef"
"abc" + 8"abc8"
8 + "abc""8abc"
"abc" + true"abctrue"
"abc" + element.amount"abcnull"if amount is not defined

Logical expressions

Syntax

if (element.amount == 0 && element.discount == 0) {...}
else {...} 

Logical expressions are expressions that evaluate to a boolean result (true or false). This result can be used in a control statement (see below)

OperationOperatorExample
And&&element.amount == 1 && element.count > 0
Or||element.amount == 1 || element.count > 0
Not!!element.done

Type conversion

The operators above take boolean arguments. When you use them with another type, the following conversions apply:

TypeConversion
Number

0 is evaluated to false.

Any other number is evaluated to true

Boolean

N/A

String

The empty string ("" or '') is evaluated to false.

Any other string is evaluated to true

Nullnull is converted to false

Examples

ExampleResultExplanation
12 == 12true
true && 0false0 is false
"" || falsefalse"" is false
"abc" && truetrue"abc" is true
5 || falsetrue5 is true


Comparison expressions

Syntax

if (element.amount <= 0) {...}
else {...} 

 Comparison expressions compare to values and evaluate to a boolean result (true or false). This result can be used in a control statement (see below)

OperationOperatorExample
Equals==

"abc" == "def"

12 == element.amount

Not equals!=

12 != 1

issue.customfield_10001 != 'Discount'

Lower<15 < 25
Lower or equals<="abc" < "zzz"
Greater>1 <= 1
Greater or equals>=55 >=555

String comparison

If both arguments in the comparison are strings, then string comparison applies.

Strings are equals if they represent the same string value ("abc" == "abc").

In the case of relational operators (<,>, <=, >=) string are compared char by chars. String representing numbers are not converted. For example, the expression ("100" < "11") is true

Number comparison

Number comparison apply if both operators are not strings. For example, when comparing a string and a number or a number and a boolean value or two numbers.

In this case, both arguments are converted to numbers and the comparison is made.


TypeConversion
NumberN/A


Boolean

true is converted to 1

false is converted to 0

String

String is converted to a number.

If conversion fails, an error is raised


Null

Comparison with empty value is not recommended.

We advise to test with the isEmpty function 


Examples

Equality

ExampleResult
12 == 12true
12 == "12" true
"abc" == "def"false
"abc" == "abc"true
1 != 2true

Relational

ExampleResultExplanation
12 <= 12trueNumber comparison
12 <= "12" trueNumber comparison
12 <= "abc"Number conversion error
"abc" < "def"falseString comparison
"abc" > "def"trueString comparison
"abc" > "abc"falseString comparison
true > 0trueNumber comparison
"100" > "11"falseThis is a string comparison, not a number


Control statements

Syntax

Control statements allow you to execute one portion of formula or another, depending on the evaluation of condition.

if (element.done) {
	return 1;
}
else if (issue.customfield_10012 == 'In progress') {
	return 0.5;
}
return 0;

The possible syntax is :

if (<condition>) {
	<statements>
}
// Optional list of else if ()
else if (<condition>) {
	<statements>
}
else if (<condition>) {
	...
}
// Optional final else
else {
	<statements>
}


Attributes reference

You can use other attributes values in your formula. To make a reference, you can use the element namespace like below:

Syntax

The reference to an attribute can be made in two ways. This is an example of a direct reference to an attribute named 'Amount' :

Attributes reference
return element.Amount * 2;

In case your attribute name contains characters that prevent the above reference, you can use the following syntax:

Attributes reference
return element['Nb. participants'] + 1;

Attribute types

Attribute references are evaluated to a data type that depends on their type and content. Here are the supported attribute types:


Attribute typeExpected data typeBehaviour when emptyComment
NumberNumberWhen the number is empty, a Null type is returned
CalculateNumberN/AAdvanced or basic formulas return a number
CheckboxBooleanN/AThis is true when the checkbox is checked
Select list (single)StringWhen nothing is selected, a Null type is returnedThe selected text is returned
Select list (multi)N/AWhen nothing is selected, a Null type is returnedA error message is returned

Examples

Example
if (element.Amount > 0) {...} else {...}
return 0.1 * element['Base discount'];

Issue field references

As you can reference element attributes, you can also reference issue custom fields in your formula. To make a reference, you can use the issue namespace like below:

Syntax

The reference to an issue custom field can be made by id and name. This is an example of a direct reference to an issue custom field 10020 with name "Amount":

Field reference
return issue['Amount(10020)'] * 0.8;

Custom field types

Issue custom field references are evaluated to a data type that depends on their type and content. Here are the supported attribute types:


Custom field typeExpected data typeBehaviour when emptyComment
NumberNumberWhen the number is empty, a Null type is returned

Examples

Example
if (issue['Amount(10020)'] > 0) {...} else {...}
return 0.1 * issue['Amount(10020)'];

Errors

Invalid number

This error can occur when you try to make an arithmetic operation on a data that is not a number

Example:

return 'abc' / 2;

Division by zero

This error can occur when you try to make a division by an argument that evaluates to zero.

Example:

return element.Amout / "0";


Next ➡ Configure template