Fieldcode Manual
Tip: You can use filters for better results
Fieldcode Expression Language
Copy the URL link to this section to share
The FEL is a cross-platform contextual expression language. It can be used to quickly, safely and reliably evaluate conditions and read out values
Syntax
Copy the URL link to this section to share
Like most expression languages, the FEL provides a simplified syntax using operators and functions to read out data or test conditions within the provided context.
Context
Copy the URL link to this section to share
Context refers to the data behind the scenes that the engine can access. In the FEL, there is a global context, which is the engine’s original data input, and a relative context, which is the current default context. Some operators might shift the relative context from the global context.
Expressions
Copy the URL link to this section to share
Expressions are text inputs that can be evaluated by the engine. Any text input that can be evaluated by the FEL engine is an expression.
Expressions in the FEL are made out of any amount of tokens, which are categorized as identifiers, constant literals, operators, functions and keywords.
An expression always returns a single value of any of the supported data types.
Conditions
Copy the URL link to this section to share
Conditions are expressions which always result in a Boolean value.
Data types
Copy the URL link to this section to share
Each and every user-defined value, identifier, and expression has a data type that describes the type of data it holds.
| Data type | Description | Example |
|---|---|---|
| Null | Represents a missing, undefined value. | null |
| Boolean | A boolean value, either true or false. | true |
| Number | A numeric value, both fractals and integers are supported. | 2.13 |
| String | A numeric value, both fractals and integers are supported. | "apple" |
| Date | A date and time representation, stored with timezone information. | toDate("2022-06-28T12:00:00Z") |
| Object | A data structure with fields. Each field of an Object also have a data type. | ticket |
| Array | A list of any amount of elements of any data types. | ticket.interventions |
| Regex | A regular expression, used internally for the like relational operator. Can be created using the regex string function. | regex("[a-z]{4}", "i") |
| DateModifier | A special internal type in Fieldcode Expression Language which can be used to modify dates. Can be created using DateModifier functions. | days(5) |
Keywords
Copy the URL link to this section to share
Keywords are literals with custom, predefined logic or meaning.
| Keyword | Description | Example |
|---|---|---|
| null | The Null value. | ticket.delivery.slaConstant == null |
| true | The Boolean true value. | ticket.additional.vip == true |
| false | The Boolean false value. | ticket.additional.vip == false |
| first | Can be used as index to reference the first element's index of an Array in an Element accessor. Equivalent with the use of 0 index. | ticket.interventions[first] |
| last | Can be used as index to reference the last element's index of an Array in an Element accessor. Equivalent with the use of -1 index. | ticket.interventions[last] |
| it | Returns the relative context. Can be used in filter conditions to access the tested element. | ticket.interventions[it == $myIntervention] |
Constant literals
Copy the URL link to this section to share
Constant literals represent a user defined constant value of a specific type.
| Constant litereal syntax | Name | Description | Example |
|---|---|---|---|
| -integer.fractional | Number literal | Defines a Number with the given integer part and fractional part values. | 1, -10, 0.25, .5 |
| "text" | Text literal | Defines a String with the enclosed text value. The text can be skipped for empty string. | "Fieldcode", John Doe |
| [elements] | Array literal | Defines an Array with the enclosed elements. Any amount of elements are allowed, including none for empty array. Multiple elements must be separated using , (comma). | [1, 2, 3] |
| {key:value} | Object literal | Defines an Object with the enclosed key-value pairs. Any amount of key-value pairs are allowed, including none for empty object. Multiple key-value pairs must be separated using , (comma). | {company:"Fieldcode", name:"John Doe", age:40} |
Identifiers
Copy the URL link to this section to share
Identifiers are any literals which are not keywords and matches the following rules:
- Only contains letters of the English alphabet, numbers, and underscores;
- Starts with a letter or underscore.
Identifiers are always evaluated from the relative context unless explicitly defined to be taken from the global context.
Operators
Copy the URL link to this section to share
Operators are functions marked by symbols or short keywords. Operators have their specific syntax and always have an exact amount of parameters.
Functions
Copy the URL link to this section to share
Functions are named commands with predefined logic that might have no or any number of parameters and always follow the same syntax: functionName(parameter1, parameter2, …)
List of operators
Copy the URL link to this section to share
Relational operators
Copy the URL link to this section to share
| Operator syntax | Name | Description | Example |
|---|---|---|---|
| a == b | Equals operator | Returns true if a and b have the same value. | ticket.cni == 123 |
| a < b | Less than operator | Returns true if the value of a is less than b. | ticket.cni < 123 |
| a <= b | Less than or equals operator | Returns true if the value of a is less than b or the same. | ticket.cni <= 123 |
| a > b | Greater than operator | Returns true if the value of a is greater than b. | ticket.cni > 123 |
| a >= b | Greater than or equals operator | Returns true if the value of a is greater than b or the same. | ticket.cni >= 123 |
| a =~ b | Text contains operator | Returns true if String a contains the value of b. | ticket.cne =~ "TEST" |
| a ~~ b | Like operator | Returns true if String a matches the regular expression value of b. | ticket.cne ~~ "TEST\-\d{4}" |
| a in b | In operator | Returns true if a is an element of Array b or if both a and b are String values then it returns whether String b contains String a. | ticket.cni in [123, 24, 31] |
Logical operators
Copy the URL link to this section to share
| Operator syntax | Name | Description | Example |
|---|---|---|---|
| !value | Not operator | Negates a Boolean value. | !ticket.additional.vip |
| a && b | And operator | Returns true if both Boolean a and Boolean b are true. | ticket.additional.vip && ticket.additional.escalation |
| a || b | Or operator | Returns true if either Boolean a or Boolean b are true. | ticket.additional.vip || ticket.additional.escalatio |
| condition ? a : b | Ternary operator | If the Boolean condition is true, then returns a otherwise b. | ticket.additional.vip ? 1 : 0 |
Mathematical operators
Copy the URL link to this section to share
| Operator syntax | Name | Description | Example |
|---|---|---|---|
| a + b | Addition | Returns the result of Number a plus Number b. If provided with String a then it will concatenate String a with the String representation of the value of b. If provided with Date a and DateModifier b then it will return a new Date adjusted with the DateModifier. | 1 + 2 |
| a - b | Subtraction | Returns the result of Number a minus Number b. If provided with Date a and DateModifier b then it will return a new Date adjusted with the DateModifier. | 2 - 1 |
| a * b | Multiplication | Returns the result of Number a multiplied by Number b. | 1 * 2 |
| a / b | Division | Returns the result of Number a divided by Number b. | 5 / 2 |
| a % b | Remainder | Returns the remainder of Number a divided by Number b. | 5 % 2 |
| a ^ b | Power operator | Returns the result of exponentiation with Number a as the base and Number b as the exponent, where Number b is an integer. | 2 ^ 3 |
Accessors
Copy the URL link to this section to share
| Operator syntax | Name | Description | Example |
|---|---|---|---|
| object.field | Member accessor | Returns the given field within the object. | ticket.cni |
| object[text] | Dynamic member accessor | Returns the field within the object which name matches the given String text. | ticket["cni"] |
| array[index] | Element accessor | Returns the element within an array with the given index. Indexing in Hem-Script starts with 0. Negative index values are used to index backward, from the end of the array. | ticket.interventions[0] |
| $identifier | Global context accessor | Returns the identifier from the global context. Can be used in filter conditions to access the global context. | ticket.interventions[id == $myIntervention.id] |
Filter operators
Copy the URL link to this section to share
Filter operators test the given values against the given conditions, returning only the matches. The relative context is always shifted within a filter condition to the tested value.
| Operator syntax | Name | Description | Example |
|---|---|---|---|
| object[condition] | Match | Returns the given object if it matches the given condition. Returns null if the object does not match the condition. | ticket[lastIntervention.reporting != null] |
| array[condition] | Find | Returns the first element within the given array which matches the given condition. Returns null if no elements match. | ticket.interventions[reporting != null] myNumbers[it < 0] |
| array{condition} | Filter | Returns an Array including all elements from the given array which match the given condition. | ticket.interventions{reporting != null} myNumbers{it % 2 == 0} |
List of functions
Copy the URL link to this section to share
String functions
Copy the URL link to this section to share
| Function | Description | Example |
|---|---|---|
| split(text, delimiter) | Splits a String text using the String delimiter, returning an Array of String elements. The delimiter parameter is optional and defaults to "". | split("seven", "e") == ["s", "v", "n"] |
| toUpperCase(text) | Returns the String text with all upper case letters. | toUpperCase("FieldCode") == "FIELDCODE" |
| toLowerCase(text) | Returns the String text with all lower case letters. | toLowerCase("FieldCode-ScrIpT") == "fieldcode-script" |
| toNumber(text) | Parses the String text to a Number value. Returns NaN if the conversion fails. | toNumber("25") == 25 |
| toDate(text) | Parses the String text to a Date value. Returns null if the conversion fails. | toDate("2022-06-28T12:00:00Z") != null |
| regex(text, ...option) | Parses a String text into a Regular Expression with the given String option, returning an Regex. The option parameter is optional and multiple values are accepted seperated by , (comma). Supported options are: "m" - matches across multiple lines; "i" - ignores the casing of letters. | "Lsdt" ~~ regex("[a-z]{4}", "i") |
| jsonSafeFormat(text) | Escapes any JSON unsafe characters from a String text. |
Number functions
Copy the URL link to this section to share
| Function | Description | Example |
|---|---|---|
| add(a, b) | Returns the result of Number a plus Number b. | add(1, 2) == 3 |
| sub(a, b) | Returns the result of Number a minus Number b. | sub(2, 1) == 1 |
| times(a, b) | Returns the result of Number a multiplied by Number b. | times(1, 2) == 2 |
| div(a, b) | Returns the result of Number a divided by Number b. | div(5, 2) == 2.5 |
| mod(a, b) | Returns the remainder of Number a divided by Number b. | mod(5, 2) == 1 |
| abs(number) | Returns the absolute value of the given Number number. | abs(-5) == 5 |
| sum(...number) | Returns the sum of all Number number. Multiple number parameters are accepted seperated by , (comma). | sum(1, 2, 3) == 6 |
| isNaN(number) | Returns true if the given Number number is NaN, false otherwise. | isNaN(toNumber("apple")) == true |
Date functions
Copy the URL link to this section to share
| Function | Description | Example |
|---|---|---|
| now() | Returns a new Date which represents the current date and time. | now() > ticket.delivery.currentLsdt |
| getDate(date) | Returns a new Date which represents the given Date date at exact midnight for date comparision. The date parameter is optional and defaults to now(). | getDate(now()) == getDate(ticket.delivery.currentLsdt) |
| getTime(date) | Returns a new Date which represents the current date at the time value of the given Date date for time comparision. The date parameter is optional and defaults to now(). | getTime(now()) >= toDate("12:00:00") |
| getDay(date) | Returns the English name of the day as a String for the given Date date, written with upper case letters only. | getDay(ticket.delivery.currentLsdt) == "MONDAY" |
| setDate(date, year, month, dayOfMonth) | Returns a new Date which represents the provided Number year, Number month and Number dayOfMonth at the time value of the given Date date. The Number year, Number month and Number dayOfMonth parameters are optional and might be null to skip the overwrite of the specific fields. | setDate(toDate("2022-10-10T12:00:00Z"), 2022, 11, 11) == toDate("2022-11-11T12:00:00Z") |
| setTime(date, hour, minute, seconds, milliseconds) | Returns a new Date which represents the date value of the provided Date date at the given Number hour, Number minute, Number seconds and Number milliseconds. The Number hour, Number minute, Number seconds and Number milliseconds parameters are optional and might be null to skip the overwrite of the specific fields. | setTime(toDate("2022-10-10T12:00:00Z"), 6, 30) == toDate("2022-11-11T06:30:00Z") |
| format(date, format) | Returns a String representation for the given Date date using the provided String format. The format parameter is optional and defaults to ISO formatting. Formats might differ between platforms as Hem-Script is using external formatters. See the formatter references for more info. | format(toDate("2022-10-10T12:00:00Z"), "dd.MM.yyyy HH:mm") == "10.10.2022 12:00" |
| utcFormat(date) | Returns a String representation for the given Date date in UTC offset using ISO formatting. | utcFormat(toDate("2022-10-10T14:00:00+02:00")) == "2022-10-10T12:00:00Z" |
| diff(a, b) | Returns the difference between Date a and Date b in milliseconds as a Number. The result will be negative if Date a is later than Date b. | diff(toDate("2022-10-10T12:00:00Z"), toDate("2022-10-10T12:30:00Z")) == 1800000 |
DateModifier functions
Copy the URL link to this section to share
| Function | Description | Example |
|---|---|---|
| years(amount) | Returns a new DateModifier which represents Number amount of years. | toDate("2022-10-10T12:30:00Z") + years(1) == toDate("2023-10-10T12:30:00Z") |
| months(amount) | Returns a new DateModifier which represents Number amount of months. | toDate("2022-10-10T12:30:00Z") + months(1) == toDate("2022-11-10T12:30:00Z") |
| days(amount) | Returns a new DateModifier which represents Number amount of days. | toDate("2022-10-10T12:30:00Z") + days(1) == toDate("2022-10-11T12:30:00Z") |
| businessDays(amount) | Returns a new DateModifier which represents Number amount of business days. Hem-Script handles days from Monday to Friday as business days. | toDate("2022-10-10T12:30:00Z") - businessDays(1) == toDate("2022-10-07T12:30:00Z") |
| hours(amount) | Returns a new DateModifier which represents Number amount of hours. | toDate("2022-10-10T12:30:00Z") + hours(1) == toDate("2022-10-10T13:30:00Z") |
| minutes(amount) | Returns a new DateModifier which represents Number amount of minutes. | toDate("2022-10-10T12:30:00Z") + minutes(1) == toDate("2022-10-10T12:31:00Z") |
| seconds(amount) | Returns a new DateModifier which represents Number amount of seconds. | toDate("2022-10-10T12:30:00Z") + seconds(10) == toDate("2022-10-10T12:30:10Z") |
| milliseconds(amount) | Returns a new DateModifier which represents Number amount of milliseconds. | toDate("2022-10-10T12:30:00Z") + milliseconds(500) == toDate("2022-10-10T12:30:00.500Z") |
Utility functions
Copy the URL link to this section to share
| Function | Description | Example |
|---|---|---|
| sizeOf(array) | Returns the Number of elements in the Array array. | sizeOf([1, 2, 3]) == 3 |
| typeOf(value) | Returns the String representation of the data type of the given value. The following values might be returned: null, string, number, boolean, date, array, object or unknown for unsupported or internal types (Untested). | typeOf(ticket) == "object" |