NileDesk Dynamic Expression Support :
Expressions : An Expression is a one line code snippet that represents a computation, condition, or value within NileDesk. It is comparable with Excel formulas. Expressions play a pivotal role in decision-making, calculations, and data manipulation throughout NileDesk forms , process flows and control options, offering flexibility and customization.
Syntax : an expression is made of a mixture of fields , operators and values to produce desired logic or calculation. For example in the computed option of a field invoice_total , you can compute the quantity field and unit_price field as below :
quantity * unit_price
Here “quantity” is a number field on form or in a dataset and “unit_price” is another number field which will be multiplied (* operator is for multiplication) and the result for this calculation will be shown in the field where the computed expression is used.
Field Names usage in Expressions : Each expression field throughout NileDesk always has a Sigma Icon Σ on the right side. By clicking it, a list of fields available at that specific location will appear. Clicking on any field ID in the list will insert it into the expression field, with the field ID appearing at the last location of your keyboard cursor in the expression field. If you already know the field ID, you can simply type it
Field Id vs Field Titles/Names : Each field on the form has a title displayed to the user; this title is purely for display purposes. In the form designer under each field property, you will find both the 'Field Title' and a 'Field Id.' In expressions, only field IDs can be used, not field Titles. Field IDs will not contain any spaces. For example a field with title Customer Name may have customer_name as its Id , you can change field ids to more meaningful ids while designing forms.
Supported Operator :
NileDesk support subset of C# operators , below is a list of core operators supported in expressions..
Operator | Usage | Example |
+ | Addition : Add 2 values / Fields. | To add 2 number fields balance1 and balance2 the expression will be : balance1 + balance2 The result of expression will be sum of balance1 and balance2 |
- | Subtraction: subtract one value from other | To subtract a Number field balance from qty the expression will be : balance - qty The result of expression will be a Number with value of balance less the value of qty field. |
* | Multiplication: Multiply two values | To multiply 2 Number fields unit_price and qty , expression could be : unit_price * qty The result of this expression will be multiplication of value of Number field Unit_price and qty. |
/ | Division: Divide values | Percentage of a Number field “consumed” could be calculated using another number field “balance” using expression like this : consumed / balance * 100 |
% | Remainder: get remainder of division of 2 values | To get the remainder of 2 Number field number1 and number2 division , the expression will be like this. number1 % number2 |
< | Less Than: compare if a number is smaller than other | To compare a date field invoice_date to see if it is less than current time the expression could be like this: Invoice_date < DateTime.Now If the invoice_date value will be less than current date time then expression will result “true” otherwise it will result as “false” Here on the right side of < the date, the DateTime building function is used to get the current date.
Similar comparisons could be done for Number or aggregate fields. |
> | Greater Than: compare if number is greater than other | To compare a number field balance is greater than the consumed number field. The expression could be like this : balance > consumed If the value in balance field is greater than value in consumed field then expression result will be “true” otherwise it will be “false” |
>= | Less Than or Equal : compare if a number is smaller than or equal to other number/field | Same like Less Than Examples above. |
<= | Greater than or Equal: compare if a number is greater than or equal to other number/field | Same like Greater Than Examples above. |
== | Equal: compare two number values or two text values if they are equal or not | It is to compare if 2 Number Fields , Date Fields , or text fields are equal or not. For example if you have a text field customer_name and you want to check if the entered name is “david boi” or not , then the expression will be like this. customer_name == “David Bowie” Here note the text value mentioned to compare is surrounded by double quotes. During evaluation of this expression , if the value of customer_name field value will be David Bowie then the expression result will be true , otherwise it will be false. |
!= | Not Equal : compare two number values or two text values if they are unequal or not | Same like Equal examples , it will compare if the 2 values or field under comparison are not equal. If they are not equal then the expression result will be true , otherwise it will be false. |
&& | AND: conditionally check if two expressions are false or true etc. | AND operator is used to check more than one expression comparison. If all the comparisons made during the expression will result true then the expression result will be true , otherwise even if one expression will be false then it will result as false. For example , if you want to check if the current user is Bill Hicks and the selected product type dropdown field value is “General” then the expression could be something like this. (_user.name == “Bill Hicks”) && (product_type == “General”) If the currently logged in User name is Bill Hicks and the selected value in product_type dropdown field is “General” then this expression will be true , if either product_type value is different or current user name is not “Bill Hicks” then the expression will result as false. |
|| | OR: conditionally check if between two expressions either is false or true etc. | OR operator is used to check more than one comparisons but compare to AND if any part of expression will result as true then expression will result as true , otherwise it will be resulted as false. |
? : | Conditional IF: Select a value based on a situation/condition | Conditional IF is used to compare a situation and if it is true then one result will be returned, otherwise the other result will be returned by expression. For example if you want to see if the balance number field value is greater than 0 then return the expression as “Balance available” and in other case you want to mention “No balance available” in a text field. Then in that text field inside the computed option write the expression as below. balance > 0 ? “Balance available” : “No balance available”
|
* Operators precedence is respected during evaluation of expressions as it is done in mathematics , however for simplicity of understanding you may use brackets to make the expression more readable like : (a + b) / c * ( a + c)
Field Types :
Each field in NileDesk forms has a certain data type , it is important to know field types and their relevant data type structures while writing expressions to compare or assigning their values.
Field Type | Data Type | Details |
TextBox | Text/String | To compare a value of a textbox customer_name expression will be like this : customer_name == “SkyLine Limited” If the field value in “customer_name” field will be “SkyLine Limited” then expression will result in “true” otherwise it will be “false” |
Number | Decimal | To see if a number field Budgeted_amount : Budgeted_amount > spent_amount If the field name “budgeted_amount” will be greater than “spend_amount” then result will be “true” otherwise it will be “false” |
Date | Date | To see if a date field is bigger is equal to or bigger than today then expression will be like this : Invoice_date >= DateTime.Now Here system function DateTime is used which provide different utility functions to compare dates. DateTime.Now provid current date time. If the invoice_date value will be equal to or greater than current date time then this expression will result true otherwise it will be false. |
CheckBox | Bool | To see if a checkbox “is_holiday” is checked or unchecked , it could be compared like this. Is_holiday == true If the checkbox will be checked then the expression result will be true , otherwise it will be false. |
DropDown | Text/String | It is used just like a textbox, see example of textbox. |
Radios | Text/String | It is used just like a textbox, see example of textbox. |
Serial No. | Text/String | It is used just like a textbox, see example of textbox. |
Aggregates | Decimal | It is used just like a number field, see example of Number. |
User | Object | User field is to represent a user, it holds the value of user unique system Id and user name as below. Object Structure : _id = unique system id for User Text = User Name To compare if a user selected in the field “requested_by” is the same as the current user who is logged in. then the expression will be like this. _user._id == requested_by._id Here _user is a system field which represents currently logged in user information. In expression if currently logged in user id will be equal to user selected in requested_by field then expression will be “true” otherwise “false”. |
Data Link | Object | Data link fields are used to link data from another dataset to a field to more reliably access other attributes of the fields dynamically. Object Structure: _id = unique row id for selected data Text = selected field’s text For a more practical example , if we have a dataset of products , which have a data link field which holds information for customer types (defined in another dataset) to maintain a list of products by customer. On your form you can have a Data Link field named customer type , where the user will select some value of customer type , in the next dropdown field you need to display a list of products for that customer type , then in that field the filter could be like this. customer_type is equal to Expression customer_type._id Note : Similar results could be produced by simply using text fields or simple Dropdown fields to filter data , however in case customer type text is changed in the original list then it will require readjusting the fields. However in DataLink no need to readjust as it depends on _ids of data and not on texts. |
Multi Link | Object Array | It is an array of data links objects |
Attachments , Picture , Spacer , Label | Not Supported | Not Supported in expressions |
Data Snap | Object | Data Snap has a dynamic structure based on its linked field. On selection of a record it fetches all the selected Linked Fields from selected DataSet and makes it available for expressions or display on form. If a data snap field Id is “products” and its data source is Products Dataset then all the column names Product Dataset row selected in datasnap can be accessed like below. products.balance products.unit_price products.type etc. *here it is assumed your Products DataSet have fields “balance” and “unit_price” |
Date Handling Functions:
Below date handling functions are supported in NileDesk Expressions.
Function | Description | Example |
DateTime.Now | Returns full date and time as of now | Expression : DateTime.Now Example Result : 2024-02-02 15:30:45 |
DateTime.Today | Returns the current date with the time set to midnight (00:00:00). | Expression : DateTime.Today Example Result : 2024-02-02 00:00:00 |
DateTime.Parse() | Converts the string representation of a date and time to its DateTime equivalent. | Expression : DateTime.Parse("2024-02-02") Result : date value to be used for dates. A text field can be used which has a date value to convert it to a date data type for further usage. |
DateTime.ToString() | Converts the DateTime data to its equivalent string representation. | Expression: date_field.ToString("yyyy-MM-dd HH:mm:ss") Example Result : 2024-01-24 08:45:22 |
Adding Days , Minutes Seconds , hours , months and years to date field values. | For a date field with id date_field1 can be used like below: date_field1.AddDays(5) date_field1.AddHours(3) date_field1.AddMinutes(30) date_field1.AddSeconds(45) date_field1.AddMonths(2) date_field1.AddYears(1) | |
Getting Date Differences in minutes, hours, days and years between 2 date fields. | Example : date1 and date2 fields with date values can be compared as below. (date2 - date1).TotalMinutes (date2 - date1).TotalHours (date2 - date1).TotalDays (date2.Year - date1).Year The result will be a number (int) to be used in field values or for further comparisons. |
Text Handling functions :
Following different functions are supported to use text values more effectively in NileDesk expressions. An example Text Field with id text_field1 is used in all examples below.
Function | Expression | Result details |
Length | text_field1.Length | Returns the number of characters in the text_field1 string. |
Substring | text_field1.Substring(7, 5) | Returns a substring of text_field1 starting from index 7 and consisting of 5 characters. |
Concatenation | string.Concat("Hello, ", "World!") | Concatenates the strings "Hello, " and "World!". |
IndexOf | text_field1.IndexOf("World") | Returns the index of the first occurrence of "World" in text_field1. |
LastIndexOf | text_field1.LastIndexOf("o") | Returns the index of the last occurrence of "o" in text_field1. |
Replace | text_field1.Replace("Hello", "Hi") | Replaces occurrences of "Hello" with "Hi" in text_field1. |
ToLower | text_field1.ToLower() | Converts all characters in text_field1 to lowercase. |
ToUpper | text_field1.ToUpper() | Converts all characters in text_field1 to uppercase. |
Trim | text_field1.Trim() | Removes leading and trailing whitespaces from text_field1. |
StartsWith | text_field1.StartsWith(" He") | Checks if text_field1 starts with the substring " He" and returns true or false result. |
EndsWith | text_field1.EndsWith("! ") | Checks if text_field1 ends with the substring "! ". |
Number and Mathematical Functions:
Since NileDesk Expressions support subset of c# language , You can use different math functions supported in C# Math library to better use the numbers in expressions as below.
Function | Description | Example |
ToString() | Convert a number to string/text | Example : a number field with id num1 can be converted to its equivalent text as below. num1.ToString() |
Math.Round | Rounds a decimal value to the nearest integer or to the specified number of decimal places. | Example: a Number field with id num1 and value 3.75 can be rounded like this. Math.Round(num1) Result: 4 |
Math.Pow | Raises a number to the power of another. | Example: a Number field with id num2 and value 2.5 can be used like this. Math.Pow(num2, 2) Result: 6.25 |
Math.Sqrt | Returns the square root of a number. | Example: field num1 with value 25 can be used like below. Math.Sqrt(num1)
Result: 5 |
Math.Min: | Returns the smaller of two values. | Example: num1 with value 10.3 and num2 with value 7.8 can be compared like below. Math.Min(num1, num2) Result: 7.8 |
Math.Max: | Returns the larger of two values. | Example: num1 with value 10.3 and num2 with value 7.8 can be compared like below. Math.Max(10.3m, 7.8m) Result: 10.3 |
Embedded Expressions in Text:
In NileDesk, specific areas require the incorporation of text with embedded form fields and expressions to generate dynamic content. These areas include:
- Process Subject: In the Form Designer, the process subject is defined using text and embedded form field expressions.
- Send Email Step: Within the Process Designer, the Send Email step offers a feature to format emails and their subjects using embedded expressions.
- Notification Setup: In the organization-level setup, NileDesk provides a facility to define email formats using HTML and embedded expressions.
Syntax for Embedded Expressions: The overall syntax for embedded expressions remains consistent, as explained above; however, they are enclosed by double curly brackets at the start and end, like {{ field_id }}, marking the beginning and end of expressions within the text.
As an illustration, a process subject can be created by embedding the form example field _request_title and the process system field _created_by as shown below:
Customer Request: {{ request_title }} by: {{ _created_by }}
If the form field request_title holds the text value "Laptop screen flickering repeatedly" and the request creator's name is "Julia Garner," then when the process is initiated, its subject will be something like "Customer Request: Laptop screen flickering repeatedly by Julia Garner."
Different Types of Information Access in Expressions:
In addition to basic form fields, various areas within applications can access diverse dynamic information to incorporate into expressions, as outlined below.
Current User Information:
Information about the user currently logged in can be accessed using the _user prefix along with its user attributes. For instance, to include the current user's name in an expression, use the following syntax:
_user.name
System Process Information:
Process information, such as creation date, creator's ID and name, subject, etc., can be accessed by placing process fields in expressions. All process fields have a preceding underscore _. To include the name of the process creator in an expression, use the following expression:
_created_by
Initiator Information:
Information about the user who created or initiated the process is available in expressions in specific areas. Access initiator information using the _initiator prefix along with its user attributes. For example, to access the initiator's name in an expression, use the following syntax:
_initiator.name
Table Parent Form Access:
When a form contains a table, and you need to write an expression to access its parent form field, use the _parent prefix followed by the form field ID. For instance, to access a form field with the ID "customer_name" within a table field, use the following expression:
_parent.customer_name
These methods enable you to seamlessly integrate various types of dynamic information into your expressions, enhancing the flexibility and functionality of your applications.