Advanced formula

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;
}

Quick links

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 :

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)

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:

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

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:

Examples

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)

Type conversion

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

Examples

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)

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.

Examples

Equality

Relational

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' :

return element.Amount * 2;

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

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:

Examples

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":

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:

Examples

NOT IMPLEMENTED YET

see ELT-545 & ELT-544

Functions

Global functions are available for basic data testing.

isEmpty

This function tests the 'emptyness' of the parameter.

Definition

Name	Arguments	Return type
isEmpty	One argument which can be any expression	a Boolean type

Behaviour

The behaviour of the function depends on the argument type and content. It returns true only if the argument is null or the empty string :

Argument type	Expected return type
Number	false
Boolean	false
Null	true
Empty string ("")	true
Non empty string ("abc")	false

Example

JS

if (isEmpty(element.Amount)) {
	return 10;
}
else {
	return element.Amount;
}

isNotEmpty

This function tests the 'non emptyness' of the parameter. 

Equivalence: calling isNotEmpty is strictly equivalent to calling  !isEmpty.

CODE

isNotEmpty(argument) == !isEmpty(argument)

Definition

Name	Arguments	Return type
isNotEmpty	One argument which can be any expression	a Boolean type

Example

JS

if (isNotEmpty(element.Amount)) {
	return element.Amount;
}
else {
	return 10;
}

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