Dynamic Forms - Expressions

Introduction

The Dynamic Forms is designed to streamline data capture, and at the heart of its flexibility are expressions. These powerful, dynamic logic constructs allow you to bring intelligence and automation to your data collection forms. Instead of static fields, expressions enable properties like visibility, mandatory status, and even field values to react in real-time to user input, external data, or system conditions. By embedding these dynamic rules, you can create smarter, more intuitive forms that adapt to specific scenarios, guide users through complex workflows, and ensure data consistency and accuracy.

What are Expressions in DCS

The Data Collection expressions can be used on the working copy to bring dynamic actions to these properties:

• read only;

• mandatory;

• visible;

• Initial value;

• Computed value;

Read only

Using an expression for this property the user can adjust the ability of the field. It is important that the expression returns a Boolean type. If the evaluated result is true, the field will be read-only / non-editable. On the contrary if it is evaluated at false, the field will be editable. When no expression is indicated in the field, by default it assumes a false value, so the node is editable.

The read-only property is not available for the section node.

Mandatory

Using an expression for this property the user can adjust whether the field is mandatory or not. It is important that the expression returns a Boolean type. If the evaluated result is true, the field will be mandatory. On the contrary if it is evaluated at false, the field won’t be mandatory. When no expression is indicated in the field, by default it assumes a false value, so the node is optional (not mandatory).

The mandatory property is not available for the section node.

Visible

Using an expression for this property the user can adjust whether the field is visible or not. It is important that the expression returns a Boolean type. If the evaluated result is true, the field will be visible. On the contrary, if it is evaluated at false the field will be not visible to the user. When no expression is indicated in the field, by default it assumes a true value, so the node is visible.

Initial value

Using an expression for this property the user can adjust the initial value for the input field. In this case it is important that the expression returns a value that is linear to the type of the node (for example number, text, date, etc.). When no expression is indicated in the field, by default it assumes the initial value as not specified.

The initial value is not available for the following types of fields: attachment, photo, signature, barcode, section.

Computed value

Using an expression for this property you can adjust the current value for the input field. In this case it is important that the expression returns a value that is linear to the type of node (for example number, text, date, etc.). When no expression is indicated in the field, by default it assumes the initial value as not specified.

The current value is not available for the following types of fields: attachment, photo, signature, barcode section.

When a node is marked as “Computed Node”, only computed value can be used ( i.e. visible, read-only, mandatory and initial value properties can’t be longer used).

 Technical tip

Starting from the 12.0 fsm version, the dynamo which interprets the expression has been changed. Now is based on a library (SpEL) on server and mobile side.

How to build an expression

A simple expression used in a DCS node property can be a basic expression like constant values, linear to the node’s type:

• true/false constants can be used for visible, read-only and mandatory properties

• a typed value linear to the node’s type used in the Initial Value and Computed Value properties. “Text example” constant can be used for Text node, or 144 constants can be used if the node is of type “Integer Number”, etc.

However, it is also possible to use advanced expressions containing:

• the current values ​​of other nodes (also in this case is required that the evaluation returns a value suitable with the node’s type);

• the current value of Visible, Read-Only or Mandatory properties of other nodes (in this case the evaluation returns a Boolean type);

• reserved keywords to retrieve some special data such as:

  • a system value like the current date or time;

  • a value of an FSM entity connected with the DCS (the list of currently supported Reserved Keywords is available in the following chapter "Reserved Keywords").

• common arithmetic, logical and comparison operators to compound more complex assembling expression.

• conditional structure management to make choices based on the evaluation of a condition between two given expressions. Conditional expression could be nested to evaluate multiple choices.

In the following paragraph, we are going to explain how to build expressions containing these elements.

Constant expression and how to define the Initial value property

Constant values can be included in complex expression but are used also to provide an initial value to an input field so the user can use them in “Initial value” property for the field that the user want to initialize.

Here few important objects to consider:

• the constant or the expression must be linear to the type of the node.

• the format of complex nodes like dates, time, coordinates must be strictly respected.

In the next table for each node’s type, there are few examples to properly set the Initial property’s value.

Expressions with current values of other nodes

In expressions it is also possible to use the current value of other nodes.

The user must consider that the type of the nodes used must be linear (cannot be used the value of a coordinate node to set a value of a numeric node).

For example, if there are two decimal nodes respectively with code “Pipe Radius” and “Pipe Area”, the following expression can be used:

#PIPE_RADIUS.value * 3.1415

In this case the formula re-calculates every time the Pipe Radius changes.

So in order to access to the current value of a node having as code “FieldCode”, the syntax to use is:  #<FieldCode>.value.

If needed, the user can use more fields in the formula referencing to the code of the fields to use (for example, #AMPERE.value * #VOLTS.value)

Info

Take care that user has to use the “Code” of the node not his name.

Also to define the code the user can only use regular expression an /^[a..z,1..9,_]+$/ so only uppercase alphabetic letter, number or underscore sign.

So #FIELDNAME_1 is a valid name for the code node, while #Field-12! is not.

Please note that #FIELDNAME_1.value is the correct syntax to access to the value of the node with code FIELDNAME_1 while #FIELDNAME_1.VALUE or #FIELDNAME_1.Value is not.

Expressions with current properties of other nodes

In some cases, might be useful to consider not the current value of the field but the one of a property between visible, read-only and mandatory.

In this case the expression looks like the one explained the previous paragraph: the only difference is that after the point, instead of the reserved word value, we will now use:

• .visible to refer the current value of the visible property;

• .readonly to refer the current value of the read only property;

• .mandatory to refer the current value of the mandatory property.

This can be useful when users want to make visible some fields or sections, depending on the state of other fields.

Figure - Expression used to adjust the visibility of “Area” node based on the visibility of “radius” node

Operators that can be used in expressions

In expressions, users can use operators to combine multiple jobs together.

Since the operators must be consistent with the type of arguments and the returned value, will have logical, numeric and string operators.

No operators are currently supported for manipulating date, time, attachment, or coordinate values. They could be supported as future improvements.

Operators working on text values

Operators working on logical values

Operators working on numeric values (integer and decimal)

Comparison operations between numerical values

The following comparison operators can be used for comparison operations on numeric values. The result of a comparison operation is a logical value between true / false.

Comparison operations between date/time values

There are not currently comparison operations on date / time values.

Conditional Expression

Users can use the following conditional structure (based on a condition), to choose which expressions to use to set the node property.

The syntax to use is the following:

1 condition ? expression1 : expression2

• condition is a mandatory logical expression;

• expression1 is an expression, mandatory;

• expression2 is an expression, mandatory.

expression1 and expression2 when evaluated must return a result type consistent with that of the field they value (for example Boolean if they assign the visible property of the node or read-only or mandatory).

Here are some examples of cases of the conditional structure:

Example 1 - Conditional structure that returns a numeric value

1
#NUMERICFIELD1.value >= 5 ? #NUMERICFIELD1.value - 5 : #NUMERICFIELD1.value + NUMERICFIELD2.value + 5

or also

#NUMERICFIELD1.value >= 5 ? #NUMERICFIELD1.value * 2 : null

Example 2 - Conditional structur that returns a string value

1
#NUMERICFIELD1.value > 3 ? ‘ok’ : #STRINGFIELD1.value

Example 3  - Conditional structure that returns a logical value:

#NUMERICFIELD1.visible && #NUMERICFIELD2.visible ? true : #NUMERICFIELD1.visible

Nested conditional structure

It is possible to build conditional expressions with multiple outputs, by using single conditional expressions and nesting them properly.

Example:

"Dice" is a numeric node that accepts values ​​between 1 and 6. The expression reads the value and assigns a value to the string field between 'small', 'medium', 'large' depending on the score obtained from the die.

1
#DICE.value == null ? null : (#DICE.value < 3 ? 'small' : ( #DICE.value < 5 ? 'medium' : 'large' ) )

Reserved Keywords

In the "Initial Value" and "Computed Value" properties, is possible to use the Reserved Words to instruct the system to retrieve information external to the DCS.

Here below few information, belonging to different context:

• sys;

• wo;

• woo;

• agenda;

• tobj;

• res.

The "sys” stands for system context and allows the user to retrieve information that can be calculated by the system, such as the current date or time.

The “wo” stands for work order context and allows the user to retrieve information related to the work order associated with the DCS (via wo operation). If the DCS is not associated with the WO or the information is not present on the WO, a null value is returned.

The “woo” stands for work order operation context and allows the user to retrieve information related to the work order operation associated with the DCS. If the DCS is not associated with the WO operation or the information is not present on the WO operation, a null value is returned.

The “agenda” stands for intervention agenda context and allows the user to retrieve information related to the foreman agenda for the (last) intervention. If the DCS is not associated with any agenda or the information is not present on the intervention agenda, a null value is returned.

The “tobj” stand for technical object context and allows the user to retrieve information related to the technical object for the current intervention. If the DCS is not associated with any intervention or the information is not present on the technical object linked with the current intervention, a null value is returned.

The “res” stands for scheduling resource and allows the user to retrieve the resource assigned to perform the intervention. If the DCS is not associated with any scheduling resource or the information is not present on the scheduling resource, a null value is returned.

In the next table, for each context, you will find the catalog of reserved work that can be used within expression, their meaning and the Next-Gen FSM Platform database’s field where the information is retrieved from.

Be carefull

With reserved keywords the syntax with .value is not allowed. For example, it is necessary to indicate #sys.currentDatetime to get the current date and time, while the indication # sys.currentDatetime.value is not allowed and is reported as an error.

Other special operators

Selection and comparison of a value available in a Selection node

The following expression operates on the node with the Selection Node type “fileType” code. The node presents the following list of possible options {'txt', 'jpg', 'doc'} with codes {'txtCode', 'jpgCode', 'docCode'}.

1
#fileType.value != null && #fileType.value == 'txtCode'

The expression consists of two clauses, the first checks that the field has been filled-in with the first item in the list, while the second checks that the first element selected is equal to 1. The numerator 1 indicates “the first item in the list, in the case 'txt'. (if it were == 2, it meant the second in the list 'jpg', and so on).

Selection and comparison of a value available in a multi-selection node

The following expression operates on the node with Multi-selection Node type “fileType” code. The node always has the same list of possible options {'txt', 'jpg', 'doc'} with codes {'txtCode', 'jpgCode', 'docCode'}.. The syntax changes slightly, because it refers to an array of selected elements.

1
2
3

#fileType.value == null ? null : ( 
                            (#fileType.value).contains('txtCode') ? 'Ok, Txt code is selected' : 'Ko, Txt code is not selected'
                                 )

The expression consists of two clauses. The first clauses verifies that the field has been filled and it is not null, while the second verifies that “FileType” field contains an element with code ‘txtCode0. If true the system prints out ‘Ok, Txt code is selected’, otherwise it prints out 'Ko, Txt code is not selected’.

Expression evaluation order

Whenever the value of a node used in expressions changes, all expressions on the tab are recalculated.

The order used to re-calculate the expressions is determined by Next-Gen FSM Platform and it is stored in the DCS model, while saving each model of the working copy model. It is calculated by building the graph, representing the dependencies that the inserted expression must satisfy.

In the graph there are all the nodes which make up the DCS, and many oriented arcs A → B, the arc A → B is present in the graph if there is at least one formula in B that uses node A.

The nodes are finally sorted by Next-Gen FSM Platform in order to ensure compliance with the previous in the calculation (i.e., if a user must calculate B, must calculates A first and so on). The following example shows how the graph is built-in, and how it is used to determine if expressions entered are computable (they do not contain any cycles).

The corresponding graph will be like:

So we can assign the order used to carry out the recalculation when updating a node in the sheet (I, C, D, E, F, H, G).

The graph is used by Next-Gen FSM Platform to find out if the formula entered, introduces unwanted cyclical evaluations

In fact, if we add to the following formula on node B, visible: # E.value == true we would have the further dependence E → B and therefore the following graph that contains cycles. (e.g. B-> C-> E).

The existence of the cycle cannot be admitted, because it would cause an infinite recalculation of the formula so if the system detects the existence of at least one cycle, Next-Gen FSM Platform warns the user displaying "Cycles in Data Collection expression are not allowed" message, and will refuse the update expression.

The user can verify the order assigned by Next-Gen FSM Platform, by inspecting the model property of the DC template release / DC Sheet (this is the evaluation Order field).

Figure - Model data structure - evaluationOrder properties

The evaluation Order indicates the order for visiting the nodes. Please note that when a node is processed its properties are evaluated, using the following order:

• visible

• read only

• mandatory

• initial value

• computed value.