Expressions

An Expression is a one-line code snippet that represents a computation, condition, or value within NileDesk. It is comparable to 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 the 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 shown below:

quantity * unit_price

Here quantity is a number field on a form or in a dataset, and unit_price is another number field. They are multiplied (* operator is for multiplication), and the result of 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 current cursor position in the expression field. If you already know the field ID, you can simply type it directly.

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 the title Customer Name may have customer_name as its ID. You can change field IDs to more meaningful ones while designing forms.

Supported Operators

NileDesk expressions support a core set of C# operators. These operators allow you to perform calculations, comparisons, and conditional logic within fields, forms, and processes.

Operator	Usage	Example
+	Addition: add two numbers or fields.	balance1 + balance2 Returns the sum of balance1 and balance2.
-	Subtraction: subtract one value from another.	total_amount - discount Returns the net amount after subtracting discount.
*	Multiplication: multiply two values.	unit_price * qty Returns the product of unit_price and qty.
/	Division: divide one value by another.	(consumed / total) * 100 Returns the percentage of consumed out of total.
%	Remainder: return the remainder of a division.	items % 5 Returns how many items remain if grouped in 5s.
<	Less Than: check if a value is smaller.	invoice_date < DateTime.Now Returns true if invoice_date is before the current date/time.
>	Greater Than: check if a value is larger.	balance > consumed Returns true if balance is greater than consumed.
>=	Greater Than or Equal: check if a value is larger or equal.	qty >= 10 Returns true if qty is at least 10.
<=	Less Than or Equal: check if a value is smaller or equal.	discount <= 100 Returns true if discount is 100 or less.
==	Equal: check if two values are equal.	customer_name == "David Bowie" Returns true if the customer_name is exactly "David Bowie".
!=	Not Equal: check if two values are different.	status != "Closed" Returns true if status is not "Closed".
&&	AND: ensure all conditions are true.	(qty > 0) && (balance > 0) Returns true only if both qty and balance are greater than 0.
||	OR: check if at least one condition is true.	(qty > 0) || (balance > 0) Returns true if either qty or balance is greater than 0.
? :	Conditional IF: return one value if true, another if false.	balance > 0 ? "Balance available" : "No balance" Returns text depending on whether balance is positive.

(a + b) / c * (a + c)

Field Types

Each field in NileDesk forms has a specific data type. It is important to understand field types and their structures when writing expressions, so you can compare or assign values correctly.

Field Type	Data Type	Details & Example
TextBox	Text / String	Compare text values: customer_name == "SkyLine Limited" Returns true if customer_name matches "SkyLine Limited".
Number	Decimal	Compare numeric values: budgeted_amount > spent_amount Returns true if budgeted_amount is greater than spent_amount.
Date	Date	Compare against the current date: invoice_date >= DateTime.Now Uses DateTime.Now to get the current date/time. Returns true if invoice_date is today or later.
CheckBox	Bool	Check if selected: is_holiday == true Returns true if the checkbox is_holiday is checked.
DropDown	Text / String	Used like a text field. Example: product_type == "General"
Radios	Text / String	Same usage as DropDown or TextBox.
Serial No.	Text / String	Behaves like a TextBox.
Aggregates	Decimal	Behaves like a Number field. Example: total_sales > 1000
User	Object	Holds user _id (unique system id) and text (user name). Compare current user with a field: _user._id == requested_by._id Returns true if the logged-in user is the same as requested_by.
Data Link	Object	Links data from another dataset. Structure: _id = row id, text = display text. Example (filter by selected customer type): customer_type._id == some_dataset.customer_type_id More reliable than text-based filters since it depends on IDs, not labels.
Multi Select	String Array	Holds multiple selected values as an array of texts. Example: selected_tags.Contains("Urgent") Returns true if "Urgent" is one of the selected values.
Attachments, Picture, Spacer, Label	Not Supported	These fields cannot be used in expressions.
Data Snap	Object	Fetches multiple fields from a linked dataset. Example (if DataSnap field products links to Products dataset): products.balance products.unit_price products.type Makes dataset row attributes directly available in expressions.

Date Handling Functions

NileDesk Expressions support several date handling functions. Most of these are custom functions designed with UTC handling for internationalization purposes.

Function	Description	Example Expression	Example Result
Now()	Returns the full date and time of the current moment.	Now()	2024-02-02 15:30:45
Today()	Returns today’s date with time set to midnight (00:00:00).	Today()	2024-02-02 00:00:00
Today_EOD()	Returns today’s date with time set to end of day (23:59:59).	Today_EOD()	2024-02-02 23:59:59
Tomorrow()	Returns tomorrow’s date at midnight.	Tomorrow()	2024-02-03 00:00:00
Tomorrow_EOD()	Returns tomorrow’s date at end of day.	Tomorrow_EOD()	2024-02-03 23:59:59
Yesterday()	Returns yesterday’s date at midnight.	Yesterday()	2024-02-01 00:00:00
Yesterday_EOD()	Returns yesterday’s date at end of day.	Yesterday_EOD()	2024-02-01 23:59:59
Last_6_Hours()	Returns the date and time 6 hours ago.	Last_6_Hours()	2024-02-02 09:30:45
Last_12_Hours()	Returns the date and time 12 hours ago.	Last_12_Hours()	2024-02-02 03:30:45
Next_6_Hours()	Returns the date and time 6 hours from now.	Next_6_Hours()	2024-02-02 21:30:45
Next_12_Hours()	Returns the date and time 12 hours from now.	Next_12_Hours()	2024-02-03 03:30:45
Last_7_Days()	Returns the date and time 7 days ago.	Last_7_Days()	2024-01-26 15:30:45
Next_7_Days()	Returns the date and time 7 days from now.	Next_7_Days()	2024-02-09 15:30:45
Last_14_Days()	Returns the date and time 14 days ago.	Last_14_Days()	2024-01-19 15:30:45
Last_30_Days()	Returns the date and time 30 days ago.	Last_30_Days()	2024-01-03 15:30:45
This_Week()	Returns the date of the first day of the current week.	This_Week()	2024-01-29 00:00:00
This_Month()	Returns the first day of the current month.	This_Month()	2024-02-01 00:00:00
This_Qrt()	Returns the first day of the current quarter.	This_Qrt()	2024-01-01 00:00:00
Last_Qrt()	Returns the first day of the previous quarter.	Last_Qrt()	2023-10-01 00:00:00
This_Year()	Returns the first day of the current year.	This_Year()	2024-01-01 00:00:00
BOM()	Returns the first date of the current month at midnight.	BOM()	2024-02-01 00:00:00
EOM()	Returns the last date of the current month at end of day.	EOM()	2024-02-28 23:59:59

Parsing and Formatting Dates

Convert string to DateTime:

DateTime.Parse("2024-02-02")

Convert DateTime to string:

date_field.ToString("yyyy-MM-dd HH:mm:ss")

Example Result: 2024-01-24 08:45:22

Adding Time to Dates

You can add intervals to a date field:

date_field1.AddDays(5) date_field1.AddHours(3) date_field1.AddMinutes(30) date_field1.AddSeconds(45) date_field1.AddMonths(2) date_field1.AddYears(1)

Calculating Differences Between Dates

For two date fields date1 and date2:

(date2 - date1).TotalMinutes (date2 - date1).TotalHours (date2 - date1).TotalDays (date2.Year - date1.Year)

The result is a number that can be used for comparisons or further calculations.

Text Handling Functions

NileDesk Expressions support various text handling functions to work with string values effectively. In the examples below, a sample text field with the ID text_field1 is used.

Function	Example Expression	Result / Description
Length	text_field1.Length	Returns the number of characters in text_field1.
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 (joins) the strings "Hello, " and "World!".
IndexOf	text_field1.IndexOf("World")	Returns the index (position) of the first occurrence of "World" in text_field1. Returns -1 if not found.
LastIndexOf	text_field1.LastIndexOf("o")	Returns the index of the last occurrence of "o" in text_field1.
Replace	text_field1.Replace("Hello", "Hi")	Replaces all 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 "He". Returns true or false.
EndsWith	text_field1.EndsWith("!")	Checks if text_field1 ends with "!". Returns true or false.

Number and Mathematical Functions

NileDesk Expressions support a subset of the C# language. You can use common mathematical functions from the C# Math library to perform calculations on number fields. Below are the supported functions with examples.

Function	Description	Example Expression	Result
ToString()	Converts a numeric value into its string (text) representation.	num1.ToString()	If num1 = 123.45, result = "123.45"
Math.Round()	Rounds a decimal value to the nearest integer, or to a specified number of decimal places.	Math.Round(num1)	If num1 = 3.75, result = 4
Math.Pow()	Raises a number to the power of another.	Math.Pow(num2, 2)	If num2 = 2.5, result = 6.25
Math.Sqrt()	Returns the square root of a number.	Math.Sqrt(num1)	If num1 = 25, result = 5
Math.Min()	Returns the smaller of two values.	Math.Min(num1, num2)	If num1 = 10.3 and num2 = 7.8, result = 7.8
Math.Max()	Returns the larger of two values.	Math.Max(num1, num2)	If num1 = 10.3 and num2 = 7.8, result = 10.3

Embedded Expressions in Text

In NileDesk, certain areas allow you to combine static text with embedded form fields or expressions to create dynamic content. These areas include:

• Process Subject: In the Form Designer, the process subject can include text and embedded form field expressions.
• Send Email Step: Within the Process Designer, the Send Email step allows formatting email content and subjects using embedded expressions.
• Notification Setup: At the organization level, NileDesk supports defining email formats with HTML and embedded expressions.

Syntax for Embedded Expressions

Embedded expressions follow the same syntax as regular expressions, but they are enclosed in double curly brackets to mark their start and end. Example syntax: {{ field_id }}

Example

Suppose you want to create a process subject using a form field request_title and a system field _created_by. The expression would be written as:

Customer Request: {{ request_title }} by: {{ _created_by }}

If request_title contains "Laptop screen flickering repeatedly" and _created_by is "Julia Garner", then when the process is initiated, the subject will dynamically appear as:

Customer Request: Laptop screen flickering repeatedly by Julia Garner

Different Types of Information Access in Expressions

In addition to basic form fields, NileDesk allows you to access a variety of dynamic information within expressions to make them more powerful and context-aware. Below are the main types of information you can use:

1. Current User Information

Information about the currently logged-in user can be accessed using the _user prefix along with user attributes. Example: To include the current user's name in an expression:

_user.name

2. System Process Information

Process-related information such as creation date, creator's ID, name, subject, etc., can be accessed using process fields. All process fields start with an underscore _. Example: To access the name of the process creator:

_created_by

3. Initiator Information

You can access information about the user who initiated the process using the _initiator prefix along with user attributes. Example: To get the initiator's name:

_initiator.name

4. Table Parent Form Access

When a form contains a table, you may need to access fields from the parent form. Use the _parent prefix followed by the field ID. Example: To access a parent form field with ID customer_name within a table:

_parent.customer_name

These methods allow you to seamlessly incorporate diverse types of dynamic information into your expressions, enhancing the flexibility and functionality of your applications.

---

Handling Nulls in Expressions

In NileDesk, When working with fields or variables, it's common to encounter null values. In case of fields , if a field value is completely cleared and no value is selected or entered , then it is considered null, Proper handling of nulls ensures that your expressions do not fail and produce predictable results.

1. Checking for Null Values

You can check if a variable or field is null using the standard C# null comparison:

myVariable != null

This returns true if myVariable has a value, otherwise false.

2. Using Null-Coalescing Operator

To provide a default value when a variable is null, use the ?? operator. Example: Multiply a variable by 10, defaulting to 0 if null:

(myVariable ?? 0) * 10

If myVariable is null, the expression evaluates to 0 * 10 = 0. Otherwise, it multiplies the actual value by 10.

3. Safe Navigation / Null-Conditional Operator

For object type variables like DataSnap fields, User objects, or DataLink fields, you can use the null-conditional operator ?. to safely access properties:

Customer?.Name

Here, if Customer is null, the expression will return null instead of throwing an error. You can combine it with ?? for a default value:

Customer?.Name ?? "Unknown"

4. Using Null Checks in Expressions

You can combine null checks with conditions and calculations:

• InvoiceAmount != null && InvoiceAmount > 1000 — checks that InvoiceAmount is not null and greater than 1000.
• (Balance ?? 0) - (Spent ?? 0) — safely calculates remaining balance even if one of the fields is null.
• User?.Email != null ? User.Email : "noemail@example.com" — conditional check with fallback value for null object properties.

5. Summary

Using these approaches ensures your expressions handle null values safely:

• Direct null check: myVariable != null
• Default values with null-coalescing: myVariable ?? defaultValue
• Safe property access: Object?.Property
• Combining checks in calculations or conditions: use ?? or ?: operators.

---

Handling Numbers in NileDesk Expressions

In NileDesk, all Number and Aggregate fields are stored as decimal. When writing expressions, it's important to handle decimals correctly to avoid errors and ensure accurate calculations.

1. Integer vs Decimal Literals

Multiplying or performing operations with whole numbers works directly:

myNumber * 4

But for decimal numbers, you must append m to the literal to indicate a decimal type:

myNumber * 4.2m

2. Safe Null Handling

When performing calculations, always consider nulls to avoid runtime errors. Example:

(myNumber ?? 0) * 4.2m

3. Common Tips

• All calculations with number fields are decimal by default.
• Use Math functions like Math.Round(), Math.Min(), Math.Max() for precise operations.
• Be careful when mixing decimals and integers; always match types explicitly for clarity.
• Use parentheses () to control the order of operations and improve readability.