Expressions – how nexxcite computes values¶
Expressions are the formulas of nexxcite. Wherever a definition needs a value that is not fixed – a caption, a condition, a default value, the text of an e-mail, the comparison value of a query – it takes an expression. This chapter explains what an expression is, where it is evaluated, how values of different data types are converted and how to work with the expression editor. Every expression type has a reference page of its own (section 8).
It is intended for administrators who configure forms, rules, actions and queries.
1. Expressions at a glance¶
An expression computes exactly one value. It has no statements and changes nothing: it reads fields, variables, global values or system functions, combines them and returns the result. Whatever uses the expression – a form block, a business rule, an action command – decides what happens with that value.
An expression is built from other expressions. A text expression can contain a field, a logical expression compares two expressions, a case expression returns one of several expressions. This is how complex values are put together from small, reusable parts.
| Term | Meaning |
|---|---|
| Expression type | What the expression does – for example "Text", "Logical" or "Aggregate". It is chosen when the expression is created. |
| Stored expression | An expression with a name of its own, listed under Admin Studio → Design → Expressions. It can be used in many places. |
| Custom expression | An expression that is written directly into the setting that uses it. It belongs to that definition only. |
| Current record | The record the expression is evaluated for, for example the record shown in a form. |
| Return value | The computed value. It always has a data type (text, number, date, …). |
Summary¶
- An expression computes a value; it never stores or changes anything.
- It is evaluated for a record – the same expression gives different results for different records.
- The place that uses the value converts it to the type it needs. A value that cannot be converted does not cause an error but becomes a default value (0, false, an early date). Section 5 explains this in detail.
- Missing parts (no field selected, an expression that cannot be found) also do not cause errors – the expression returns an empty value. Check new expressions with real records.
2. Where expressions are used¶
Almost every editor of nexxcite offers settings that take an expression. Typical uses:
| Area | Examples |
|---|---|
| Forms and dashboards | Captions, visibility and read-only conditions, values shown in blocks, colours, icons |
| Grids and lists | Columns that show a computed value, badges, images |
| Business rules | The value a calculation or default value rule writes, the condition of a validation |
| Actions | The values of command parameters, conditions that decide whether a command runs, prompts that ask the user for input |
| Queries and filters | The value a field is compared with ("assigned to the current user"), the labels of quick filters |
| Entities | The title of a record |
A setting that takes an expression shows a few buttons of its own (section 6). The setting decides which data type it needs – a visibility condition needs a yes/no value, a caption needs text.
3. Stored and custom expressions¶
There are two ways to create an expression. Both have the same expression types and the same editor.
| Stored expression | Custom expression | |
|---|---|---|
| Created in | Admin Studio → Design → Expressions, or with "Set Expression" on the tab "Select Expression" | With "Set Expression" on the tab "Create Custom Expression", or by typing a value directly into a setting |
| Name | Has its own name, description and tags | Has no name of its own |
| Reuse | Can be used in any number of places | Belongs to the one setting it was created in |
| Changes | A change affects every place that uses the expression | A change affects only this place |
| Deleting | Separately, in the expression management view | Removed together with the setting or definition it belongs to |
Use a stored expression for values you need in several places, for example "Is overdue" or "Full name of the customer". Use a custom expression for anything that only makes sense in one place, for example the caption of a single button.
Entity of a stored expression¶
A stored expression belongs either to an entity or to no entity. The management view groups the expressions accordingly ("Without entity" for the second group). To create an expression for an entity, select the entity's group first and then add the expression.
- An expression that belongs to an entity can read the fields of that entity and of its related records.
- An expression without an entity cannot read fields. It is meant for values that do not depend on a record – today's date, the current user, a fixed text.
When you select a stored expression for a setting, the selection shows the expressions that fit the context of the setting.
Permissions¶
| Permission | Allows |
|---|---|
| "Open Expression Manager" | Opening Admin Studio → Design → Expressions |
| "Add Expression" | Creating stored expressions |
| "Edit Expression" | Changing stored expressions |
| "Delete Expression" | Deleting stored expressions |
By default, these permissions are part of "System Developer". Custom expressions are saved together with the definition they belong to; for them, the permission to edit that definition counts.
4. The current record¶
An expression is always evaluated in a context: usually a record and, inside an action, the variables of the action.
| Where the expression is used | Current record |
|---|---|
| In a form | The record the form shows |
| In an action | The record the action runs on (for an action that runs over several records: the record of the current run) |
| In a grid or list column | The record of the row |
| In the condition of an aggregate expression | Each related record in turn |
| In the comparison value of a query clause | The record the query is run from – not the records the query searches |
| In a scheduled action or other background processing | The record that is processed, or none |
Without a current record, field references return an empty value. In the management view Admin Studio → Design → Expressions, "Evaluate" computes the selected expression and shows the result in the dialog "Evaluation Result". It uses the record that is currently open in the application, if there is one – otherwise the expression is evaluated without a record.
5. Data types and conversions¶
Return types¶
Every expression returns a value with a data type:
| Expression types | Return type |
|---|---|
| Text, Image, File Contents | Text |
| Mathematic | Decimal number |
| Logical | Yes/no (true / false) |
| Counter | Whole number |
| Duration | Decimal number, or text with "Return Time Remaining" |
| Date Time Math | Date and time, as text in ISO 8601 format (for example 2026-10-20T14:30:00.0000000) |
| Field, Variable, Global Value, System Function, Case, Aggregate, Sub Query, Modify Value, Prompt, Dynamic, Cache | The type of the value they read or return |
How a value is converted¶
The place that uses an expression converts the value to the type it needs. It does not check whether the conversion makes sense. A value that cannot be converted becomes a default value:
| Needed type | Converts successfully | Otherwise |
|---|---|---|
| Text | Always. Numbers use a decimal point; a date and time becomes text in the form 10/20/2026 14:30:00 (month/day/year); an empty date becomes an empty text. |
– |
| Whole number | Text that consists of a whole number, for example 42 |
0 |
| Decimal number | Text that is a number with a decimal point, for example 3.5 |
0 |
| Yes/no | true, false, 1, 0 (upper or lower case) |
false – also for "yes", "no" or "on" |
| Date, date and time | A date value, or text in a culture-neutral format such as 2026-10-20 or 2026-10-20 14:30 |
1 January 1753 |
| Id | Text in the form of an id | The empty id (all zeros) |
Example: A calculation rule writes the expression "Discount" into a decimal field. If "Discount"
returns n/a or an empty value, the field is set to 0 – without any message. A date comparison
with an empty value compares with 1 January 1753.
For administrators
- Build the expression to return the type that is needed. If a field can be empty, decide
explicitly what should happen, for example with the rule
Coalesceof a Modify Value expression or with a Case expression. - A result of 0 or a date in the year 1753 is almost always an empty or wrongly typed value, not a mistake in the formula.
- Format dates before you put them into a text. A date inserted into a text expression appears
in the form
10/20/2026 14:30:00. Use the ruleDateTimeFormatof a Modify Value expression for any other format.
Empty values¶
Several places test whether a value is empty – the operators Empty and NotEmpty, the rule
Coalesce, required field checks. A value counts as empty when it is
- no value at all or an empty text,
- the empty id (all zeros),
- a date that is 1 January 1753 or earlier.
The last point is intentional: a date field without a value is stored as 1 January 1753, the
earliest date the database knows. Every later date is a value – a date of birth in 1985 is not
empty. Wherever such an empty date is shown or used as text – in a grid, a label, a text built by
an expression – it appears as an empty text, not as the year 1753. The number 0 and the value
false are not empty.
When something is missing¶
An expression never stops with an error because something is missing. Instead it returns an empty value, for example when
- a required setting of the expression is not filled in,
- a referenced expression, field or definition no longer exists,
- there is no current record.
The cause is written to the application log. Exceptions are the Prompt expression, whose cancellation can stop the surrounding action, and the Mathematic expression, which returns the formula itself when it cannot be calculated.
6. The expression editor¶
Every expression is edited in the same editor frame: a header with name, description and tags, followed by the settings of the expression type.
Creating a stored expression¶
- Open Admin Studio → Design → Expressions (or the group "Expressions" of an entity under Admin Studio → Entities).
- Select the entity the expression belongs to, or "Without entity".
- Add a new expression. The editor shows the expression types as tabs; "Text" is selected first.
- Choose the type, fill in the settings and save.
A stored expression keeps its type once it is saved. To change the type, create a new expression. In the dialog for a custom expression, the type tabs stay available: choosing another tab starts a new custom expression of that type, which replaces the old one when you save it.
Setting an expression in another editor¶
A setting that takes an expression offers three ways to fill it:
| Action | Result |
|---|---|
| Click into the setting and type | A fixed value. nexxcite creates a custom text expression from it. Depending on the setting, a date picker, a switch, a colour picker or an image picker is shown instead of a text box. |
| The arrow of the setting | A list of quick references: the fields of the current entity ("[this] …"), fields of related entities, action variables ("Variable"), "Global Values" and "System Functions". Selecting one creates a matching custom expression. |
| "Set Expression" (function icon) | A dialog with the tabs "Select Expression" (pick a stored expression) and "Create Custom Expression" (or "Edit Custom Expression", write a custom expression of any type) |
"Modify value" (pencil) changes a fixed value, "Clear" removes the expression. A right click on a setting offers "Copy" and "Paste", to move an expression from one setting to another.
The type "Variable" is only offered where action variables exist, that is inside an action.
7. Expression types¶
| Type (as shown in the editor) | What it does | Page |
|---|---|---|
| "Text" | Composes text from fixed text, line breaks, fields, other expressions, global values and system functions. Also the way to write a fixed value. | Text |
| "Mathematic" | Calculates a formula such as (Price * Quantity) * 1.19 |
Mathematic |
| "Field" | Reads a field of the current record or of a record linked through a relationship | Field |
| "Variable" | Reads a variable of the running action | Variable |
| "Global Value" | Reads a global value | Global Value |
| "System Function" | Returns a built-in value such as the current user or the current time | System Function |
| "Logical" | Compares values and combines the comparisons with And/Or; returns yes/no | Logical |
| "Case" | Returns the value of the first condition that applies (if – else if – else) | Case |
| "Aggregate" | Counts, sums or selects over the related records of the current record | Aggregate |
| "Sub Query" | Runs a query on any entity and returns one value from its result | Sub Query |
| "Date Time Math" | Adds or subtracts time units to or from a date, optionally in business hours | Date Time Math |
| "Duration" | Computes the time between two dates, optionally in business hours | Duration |
| "Counter" | Draws the next number from a counter | Counter |
| "Modify Value" | Transforms a value step by step – text, JSON, XML, dates, numbers, encodings | Modify Value |
| "Cache" | Remembers the value of another expression for a while | Cache |
| "Prompt" | Asks the user for a value in a dialog | Prompt |
| "Image" | Returns an image or an icon | Image |
| "File Contents" | Reads a file from the application server | File Contents |
| "Dynamic" | Evaluates an expression that is only known at runtime | Dynamic |
Further reference pages:
- System functions – every system function with its return value
- Value modification rules – every rule of the Modify Value expression
8. Frequently asked questions¶
Does an error in an expression stop the form or the action? No. A missing or wrong part makes the expression return an empty value; the cause is written to the log. Only a cancelled Prompt can stop the surrounding action.
Why does my calculated field show 0? The expression returned a value that is not a number – usually an empty value or a text. See section 5.
Can I change the type of an existing stored expression? No. Create a new expression of the right type and replace the old one where it is used.
I changed a stored expression. Where does the change take effect? Everywhere the expression is used. The management view lists stored expressions with their entity, so you can check which group an expression belongs to before changing it.
Can an expression change data? No. An expression only computes a value. To store a value, use a business rule or an action that uses the expression. The Counter expression is the only one with a side effect: every evaluation draws a new number.