Formula Scripts

In the Mythradon Entity Manager, you can implement business logic that executes before a record is saved. This is achieved through formula scripts tailored to specific entities.

Mythradon's formula scripts enable the declaration of variables, manipulation of field values (attributes) through calculated logic, creation or modification of other records, and execution of conditional statements and loops. They also support the functionality to send emails, push notifications and much more.

This documentation includes sections on:

• Creating Formula Script
• Formula Script Syntax

• Adding Comments to Scripts

• Attributes

• Calculated Fields

• Operators

• Comparison Operators
• Arithmetic Operators
• Unary Operators
• Relational Operators
• Logical Operators
• Null Coalescing Operator
• Operator Precedence
• Functions
• Formula Sandbox
• Examples

---

Creating Formula Script

To create or edit a formula for a specific entity:

• Select Administration → Entity Manager from the Menu Button
• Select the required entity type
• Click the Formula button. This displays the formula script editor.
• Define the required formula. Select the required attributes or functions using the + button.
• Click the Save button.

Note

You can create and test Formula Scripts in the Formula Sandbox.

---

Formula Script Syntax

Mythradon utilises a specially designed scripting language for creating formulas that is intuitive and straightforward.

In Mythradon formulas, you can use four types of elements:

• Operators
• Functions
• Values (including both scalars and the NULL value)
• Attributes

Separate expressions within a formula must be separated by the ; character.

For example:

Basic Example

$webSite = 'acme.com';

$test = string\concatenate(name, ' - ', $webSite);

Explanation of components:

• string\concatenate() - a function that concatenates strings
• name - an attribute, referring to a property of the target entity to which the formula is applied
• $webSite - a variable holding the string value 'acme.com'
• ' - ' - a string value used as a separator in the concatenation
• $test - a variable where the result of the concatenation is stored

Supported scalar types include:

• string - denoted by 'my string value'
• int - represented by values like 1000
• float - values such as 1000.5
• boolean - true or false
• datetime - represented as strings in the format YYYY-MM-DD HH:MM:SS I.e. 2024-04-19 13:26:58

---

Adding Comments to Scripts

In Mythradon formula scripts, comments serve as annotations and explanations within the code, aiding in its readability and comprehension.

Line comment:

Line comments are denoted by a double forward slash (//). They are typically used to add brief explanations or notes to a single line of code.

// This is a line comment providing additional context

Section comment:

Section comments, also known as block comments, are enclosed within /* */ symbols. They are often employed to annotate larger sections of code, including multiple lines.

/*
  This is a line comment providing additional context
*/

In Mythradon formula scripts, comments are invaluable for clarifying the logic behind the code, making it easier for developers to understand and maintain the software.

---

Operators in Formula Scripts

Mythradon formulas support a range of operators, each serving a specific function in formula construction:

• = - Assigns a value to a variable.
• ?? - Returns the right-hand operand if the left-hand operand is null.
• || - Logical OR; true if either operand is true.
• && - Logical AND; true only if both operands are true.
• ! - Logical NOT; inverts the truth value of the operand.
• + - Adds two numbers.
• - - Subtracts one number from another.
• * - Multiplies two numbers.
• / - Divides one number by another.
• % - Returns the remainder of a division between two numbers.
• == - Tests for equality between two values.
• != - Tests for inequality between two values.
• > - Checks if the left-hand operand is greater than the right-hand operand.
• < - Checks if the left-hand operand is less than the right-hand operand.
• >= - Checks if the left-hand operand is greater than or equal to the right-hand operand.
• <= - Checks if the left-hand operand is less than or equal to the right-hand operand.

---

Comparison Operators

The following comparison operators are available:

• == - equals,
• != - not equals,
• > - greater than,
• < - less than,
• >= - greater than or equals,
• <= - less than or equals.

Important: Strict comparison is used. If you compare int 1 to float 1.0 with == operator they are treated as not equal. You need to compare values of same types or check whether a value falls in range with $a - 0.0001 <= $b && $b <= $a + 0.0001.

---

Arithmetic Operators

The following table shows all the arithmetic operators supported by the Mythradon formula language. Assume variable A holds 10 and variable B holds 20 then:

Operator	Description	Example
+	Adds two numeric operands. Use string\concatenate() for strings.	A + B = 30
-	Subtracts second operand from the first	A - B = -10
*	Multiplies both operands	A * B = 200
/	Divides numerator by de-numerator	B / A = 2
%	Modulus Operator and remainder of after an integer division	B % A = 0

| Operators

---

Unary Operators

The following table shows all the unary operators supported by the Mythradon formula language.

Operator	Description	Example
+	Returns the value of its operand.	+4 = 4
-	Computes the numeric negation of its operand.	-4 = -4, -(-4) = 4

| Operators

---

Relational Operators

The following table shows all the relational operators supported by the Mythradon formula language. Assume variable A holds 10 and variable B holds 20 then:

Operator	Description	Example
==	Checks if the values of two operands are equal or not. If yes, then the condition becomes true.	(A == B) is not true
!=	Checks if the values of two operands are equal or not. If the values are not equal, then the condition becomes true.	(A != B) is true
>	Checks if the value of left operand is greater than the value of right operand. If yes, then the condition becomes true.	(A > B) is not true
<	Checks if the value of left operand is less than the value of right operand. If yes, then the condition becomes true.	(A < B) is true
>=	Checks if the value of left operand is greater than or equal to the value of right operand. If yes, then the condition becomes true.	(A >= B) is not true
<=	Checks if the value of left operand is less than or equal to the value of right operand. If yes, then the condition becomes true.	(A <= B) is true

| Operators

---

Logical Operators

Following table shows all the logical operators supported by Mythradon formula language. Assume variable A holds 1 and variable B holds 0 then:

Operator	Description	Example
&&	Called Logical AND operator. If both the operands are true (non-zero), then the condition becomes true.	(A && B) is false
||	Checks if the values of two operands are equal or not. If yes, then the condition becomes true.	(A || B) is true
!	Checks if the values of two operands are equal or not. If yes, then the condition becomes true.	(A == B) is not true

| Operators

---

Assignment Operators

The following table lists the assignment operators supported by the Mythradon formula language.

Operator	Description	Example
=	Simple assignment operator. Assigns values from right side operands to left side operand.	C = A + B will assign the value of A + B to C
??	Null Coalescing Operator. (Refer below for details)	null ?? 1 = 1 2 ?? 1 = 2

| Operators

---

Null Coalescing Operator

A Null Coalescing Operator ?? is a syntactic construct that provides a concise way to check for null or undefined values and set a default value when they are encountered. It is often used in conditional statements, assignments, and function parameters to simplify null checking code.

The operator works by evaluating the expression on the left-hand side (LHS) of the operator, and if it is null or undefined, it returns the expression on the right-hand side (RHS) of the operator. If the LHS is not null or undefined, the operator returns the value of the LHS.

Example 1:

Null Coalescing Example 1

null ?? 1; // resolves to 1

2 ?? 1; // resolves to 2

Example 2:

Null Coalescing Example 2

$name = null;
$defaultName = "Guest";
$finalName = $name ?? $defaultName; // $finalName will be "Guest"

In this example, the null coalescing operator checks if the $name variable is null or undefined. Since it is, it returns the value of $defaultName, which is "Guest". If $name had a non-null value, the operator would return its value instead.

| Operators

---

Operator Precedence

Operator precedence determines the grouping of terms in an expression and decides how an expression is evaluated. An operator's precedence is meaningful only if other operators with higher or lower precedence are present.

Certain operators have higher precedence than others; for example, the multiplication operator has a higher precedence than the addition operator.

For example, $x = 7 + 3 * 2; here, $x is assigned 13, not 20 because operator * has a higher precedence than +, so it first gets multiplied with 3 * 2 and then adds 7.

Here, operators with the highest precedence appear at the top of the table, those with the lowest appear at the bottom. Within an expression, higher precedence operators will be evaluated first.

Note

The recommended approach is to avoid depending on natural operator precedence and instead use parentheses to explicitly specify the order of operations. i.e. Instead of using $x = 7 + 3 * 2; use $x = 7 + (3 * 2);.

Category	Operator	Associativity
Postfix	()	Left to right
Unary	+ - !	Right to left
Multiplicative	* / %	Left to right
Additive	+ -	Left to right
Relational	< <= >= >	Left to right
Equality	== !=	Left to right
Logical AND	&&	Left to right
Logical OR	||	Left to right
NULL Coalescing	??	Right to left
Assignment	=	Right to left

| Operators

---

Control Flow Statements

Control flow statements in a programming language determine the sequence of execution for various operations. In Mythradon, the following control flow statements are supported:

• ifThen - Executes a block of code if a specified condition is true.
• ifThenElse - Executes different blocks of code based on a condition.
• while - Repeatedly executes a block of code as long as a condition remains true.

| Control Flow Statements

---

ifThen( )

The ifThen() statement supports conditional logic. If CONDITION is met, then do CONSEQUENT. If not - do nothing.

ifThen()

ifThen(CONDITION, CONSEQUENT)

CONSEQUENT can consist of mutliple commands separated by the semicolon ;.

Example:

ifThen() Example 1

$someVariable = 'someValue';
$anotherVariable = 0;

ifThen(($someVariable == 'someValue'),
  (
    $anotherVariable = 1;
    $someVariable = 'Alpha';
  )
);

output\printLine($anotherVariable); // Outputs 1
output\printLine($someVariable); // Outputs 'Alpha'

Note

The ifThen() operates like a function and should be closed out with a ;.

| Control Flow Statements

---

ifThenElse( )

The ifThenElse() statement supports conditional logic. If CONDITION is met, then do CONSEQUENT. If not - then do ALTERNATIVE.

ifThenElse()

ifThenElse(CONDITION, CONSEQUENT, ALTERNATIVE)

Example:

ifThenElse() Example 1

ifThenElse($someVariable == 'someValue', // if condition is true
    $anotherVariable = 1, // do this
    $anotherVariable = 2 // otherwise do this
);

The ifThenElse() statement can be written so that CONSEQUENT and ALTERNATIVE can consist of mutliple commands separated by the semicolon ; such as shown in the following example.

ifThenElse() Example 2

$someVariable = 'someValue';
$anotherVariable = 0;

ifThenElse(($someVariable == 'someValue'),
  (
    $anotherVariable = 1;
    $someVariable = 'Alpha';
  )
, // Else
  (
    $anotherVariable = 2;
    $someVariable = 'Bravo';
  )
);

output\printLine($anotherVariable); // Outputs 1
output\printLine($someVariable); // Outputs 'Alpha'

Note

The ifThenElse() operates like a function and should be closed out with a ;.

[ Control Flow Statements

---

while

The while() statement executes STATEMENT repeatedly as long CONDITION is true.

while()

while(CONDITION, STATEMENT)

Example:

while() Example

// Copy the elements from $source to $target
$source = list(0, 1, 2);
$target = list();

$i = 0;

while($i < array\length($source),
    $target = array\push(
        $target,
        array\at($source, $i)
    );
    $i = $i + 1;
);

output\printLine($target);

Note

The while() operates like a function and should be closed out with a ;.

| Control Flow Statements

---

Arrays

• list - Handles collections or arrays.

list( )

The list() function is used to build an array of items that are passed in.

list()

list(VALUE-1[, ... VALUE-N]) 

Example:

list() Example 1

$list = list(0, 1, 2); // will return array [0, 1, 2]

Useful to create an array for link-multiple IDs.

Example:

list() Example 2

teamsIds = list($teamId); // `['team-id']`

| Control Flow Statements

---

Attributes

Attributes represent fields in a target entity, and you can insert them by clicking on the plus button and selecting from the available data types.

Using the format linkName.attributeName, it is possible to access the attributes of related entities.

The introduction of the attribute lexeme allows for simplified writing, such as this:

Attribute Assignment Example 1

// Assign the value 'test' to the description attribute/field of the current entity record
description = 'test';

If we didn't have attributes we would need to write more verbose:

Attribute Assignment Example 2

entity\setAttribute('description', 'test');

[ Control Flow Statements

---

Calculated Fields

Mythradon doesn't perform field calculations when retrieving a record. As a result, any field that requires a calculated value from other fields or records should be created as a standard field, and then populated using a formula that runs when the record is saved.

Example:

Assume that you need a FullName field on a Contact record that currently has only has FirstName and LastName fields.

Note

Creating a FullName field on a Contact entity is not a great example as it already has such a field. However the following does show the process of creating a calculated field.

• Using the Entity Manager, create a new varchar field called FullName and set it to Read-Only. Although the field will be read-only on the user interface, it will be set by the formula.
• In the Formula area on the same entity enter the following formula:

FullName Formula Script

ifThen((entity\isAttributeChanged('firstName') || entity\isAttributeChanged('lastName')),
    fullNameCust = string\trim(string\concatenate(firstName, ' ', lastName));
);

• Click the Check Syntax button to validate your formula before saving.
• Add the new FullName field to a layout for the purposes of debugging

Now when you create or edit a Contact record and you make a change to either the firstName or lastName fields the fullNameCust field will be updated.

---

Formula Sandbox

The Formula Sandbox is a feature designed for administrators that enables them to create and test formulas without implementing them directly on an Entity, which could affect all users of the system.

With the Formula Sandbox, you can create formulas that target a specific record, which can save time when developing formulas.

To access the Formula Sandbox:

• Select Administration → Formula Sandbox from the Menu Button

• Create your required formula
• If required, select a specific entity to test against
• Click the Check Syntax button to validate the syntax of your formula
• Click the Run button to execute the formula

Note

The Formula Sandbox executes actual code, which means that any records created or updated through it are physically stored and updated in the database.

---

Functions

Format of function use: groupName\functionName(argument1, argument2, ..., argumentN).

The supported functions are calssified into the following groups:

• Array
• Datetime
• Entity
• Env
• Ext
• Json
• Language
• Number
• Object
• Output
• Password
• Record
• String
• Util

---

Function arguments

LINK

A name of the relationship. Available link names can be found at Administration > Entity Manager > ... > Relationships.

Link names must be wrapped in quotes when used as function arguments.

More info about links here.

ATTRIBUTE

Attribute name usually is the same as a system field name. Fields are listed in Entity Manager > ... > Fields.

Field types having multiple attributes:

• Link: fieldId, fieldName.
• Link-Multiple: fieldIds, fieldNames.
• Link-Parent: fieldId, fieldType, fieldName.
• Currency: field, fieldCurrency.

Where field is the name of the field.

Attribute names must be wrapped in quotes when used as function arguments. E.g. record\attribute('Lead', 'someId', 'assignedUserId').

More info about attributes here.

ENTITY_TYPE

ENTITY_TYPE list is available at Administration > Entity Manager.

Entity type names must be wrapped in quotes when used as function arguments. E.g. record\attribute('Lead', 'someId', 'assignedUserId').

More info about entity types here.

FILTER

A name of a filter pre-defined in the system.

---

Examples

// Set the 'Assigned User Id' and 'Status' fields if the record is newly created and the 'Assigned User Id' has not been set
ifThen(
  entity\isNew() && assignedUserId == null,
  assignedUserId = 'managerId'; 
  status = 'Assigned';
);

// Set the value of the 'someDateField' to todays date if the record is newly created and 'closeDate' is not set and 'stage' equals 'Closed Won'
someDateField = ifThen(entity\isNew() && closeDate == null && stage == 'Closed Won',
  datetime\today()
);

amount = product.listPrice - (product.listPriceConverted * discount / 100.0);
amountCurrency = 'USD';

someField = string\concatenate(firstName, " '", middleName, "' ", lastName);

ifThenElse(entity\isNew() && status == 'Planned' && dateStart == null,
  dateStart = datetime\addDays(datetime\now(), 10),
  ifThen(status == 'Held' && dateStart == null,
    dateStart = datetime\now()
  )
);

---

See Also

• Formula Examples

• Formula Sandbox

• Mythradon Bookshelf Home

• Mythradon Basics

• Mythradon Marketing
• Mythradon Sales
• Mythradon Service
• Mythradon System Administration
• Mythradon Tools

---