Conditional Default Values¶
Overview¶
Field Default Values is an application concept where the initial or default values are dynamically applied to fields when a new record is being created. This allows for more flexible and streamlined data entry, enabling different sets of rules to be activated or deactivated depending on certain conditions and setting the default value of fields in a dynamic way. The user can either use the default value that has been set on a field, or change it.
Concept¶
Field Default Values involve multiple rules that can be enabled or disabled based on the state of other fields. When a new record is being created, whether in an overview page, a detail page or an Assistant, when a default value rule's associated condition is met, the field gets the value specified in the rule as its initial value. The process includes:
- Conditional Activation: For each field on the current page, rules are conditionally activated based on predefined criteria in the order they are defined.
- Evaluation: The default value provided by the first Active rule is set to the field, and the field and the page it is in will both be treated as "dirty", i.e.:, data has been entered. This means that if all mandatory fields have values and other validations pass, the data on the page is ready to be saved by the user.
- Fallback: If no rule is Active, but the core functionality set a value to the field, that value will be reflected. If the core functionality does not set a value, the field will be shown as empty.
How It Works¶
- Condition Check: When a new record is being created in an overview page, detail page or an (TOFUSE)Assistant, the system goes through each visible field on the page in a non-deterministic order. For each field, the system checks the conditions specified for each Default Value rule in the order they are defined.
- Rule Activation: The first rule whose conditions are met is considered active, stopping further checks for that field.
- Default Value evaluation: The active rule is processed and the default value it provides is set to the field. This value can either be a hard-coded value, a reference to another field, or a CSV value or expression that returns a value compatible with the field's data type.
- Field and Page behavior: The field and the Page containing it are both shown as "dirty" which means they behave the same way as if the user entered the value. Default value for a field will update if changes to other fields activates a different rule. This is true as long as the user has not made any manual change to the default value give. If a user choose to change a default value, the manual value will not be updated further even if a new default value rule, comes into play.
Note: In Page Designer, "Default Values" is not a required attribute and may not be directly visible in the designer. To show optional attributes, click the (...) icon at the bottom of the field attribute list.
Attributes of Default Value Case Items¶
| Property | Description |
|---|---|
| Case | Defines the condition under which the default value rule is enabled or disabled. The rule only applies if this condition is met. For details about the condition syntax, see Condition Syntax |
| Enabled | A static flag used to activate or deactivate a default value case item manually. This attribute allows administrators to temporarily disable specific rules without altering or deleting them. It facilitates easier management and merging of configurations during updates. |
| Value | The expression that determines the field's value. This value can either be a hard-coded value, a reference to another field, a CSV value or an expression that returns a value compatible with the field's data type. For details about the expression syntax, see Condition Syntax. |
Value Expression Syntax¶
Attributes References¶
In general, all available types can be set by referencing values from another attribute. This can include attributes on the current record, the parent, or a reference entity. An attribute reference can typically be used directly or as a parameter within an expression.
| Value | Description |
|---|---|
| MyAttribute | By default, the context is the current record, so an attribute identifier without any namespace refers to the current record (i.e., record.MyAttribute). |
| parent.SomeAttribute | The parent namespace denotes an attribute on the parent record. |
| SomeReference.Name | When an entity references other entities, an attribute from the referenced entity can be accessed by prefixing the attribute with the reference name. |
Boolean¶
Boolean values are defined as boolean literals (true|false) or as a boolean expression. See Condition Syntax for more details.
Text¶
The value for a text attribute is defined as an interpolation template, where attribute values are injected into a string template. For example, in the string "My age is", the age can be injected as "My age is ${UserAge}". Here, ${} denotes an interpolation value, and the content should be an attribute identifier or attribute reference.
| Value | Description |
|---|---|
| SomeAttribute | String literal - The default value for a text attribute can be a static string literal. |
| ${SomeAttribute} | Attribute reference - Copies the value from another attribute. Interpolations support record, parent, and reference attributes. See Attributes above. |
| FirsName} - ${LastName} | Attribute interpolations - Combines any static text with interpolated values. |
Number¶
Number values can be either number literals or number expressions, using a combination of both.
| Value | Description |
|---|---|
| 42 | Number literal - Default values can be static number literals (decimal or integer) depending on the field type. |
| parent.SomeAttribute | Reference - Uses record or reference attribute values. |
| 40 + 2 | Expressions - Supports simple arithmetic expressions. |
| SomeAttribute * 10 | Calculations - Uses attribute values in arithmetic calculations. |
Date¶
Date values can be defined as date literals, date expressions, or context substitution variables (CSV). Note that context substitution variables can be used to set a dynamic date as a default value, but they cannot be included in a date expression. Date expressions utilize date functions, such as today().
| Value | Description |
|---|---|
| 2024-01-01 | Date literal - Entered in ISO 8601 format. |
| #TODAY# | Context substitution variable - For a list of available variables, see Context Substitution Variables (CSV). |
| SomeAttribute | Record attributes and reference values - Can be used standalone or as part of expressions. |
In addition to literals, CSV, and attribute references, values can be calculated by calling date functions.
| Date function | Description |
|---|---|
| addDays(v: date, addend: number) | Adds or subtracts days from a given date. Example: Add 7 days to a start date attribute: addDays(StartDate, 7) |
| addMonths(v: date, addend: number) | Adds or subtracts months from a given date. Example: Add one month to the current day: addMonths(today(), 1) |
| addYears(v: date, addend: number) | Adds or subtracts years from a given date. Example: Add years to a date based on another attribute: addYears(StartDate, Age) |
| today() | Returns the current date according to the user's working timezone. Note: now() returns the current time in UTC, while today() adjusts for the current working or browser timezone. |
Timestamp¶
Timestamp values can be defined as timestamp literals or datetime expressions.
| Value | Description |
|---|---|
| 2020-11-09T04:03:10 | Timestamp literal - Entered in ISO 8601 format. |
| TimestampAttribute | Record attributes and reference values - Can be used standalone or as part of an expression. |
In addition to literals and attribute references, values can be calculated by calling date and timestamp functions.
| Timestamp function | Description |
|---|---|
| addDays, addMonths, addYears | Timestamps can be modified using the date functions listed above. Example: Add days to the current time: addDays(now(), 7) |
| addSeconds(v: date, addend: number) | Adds or subtracts seconds from a given timestamp. Example: Subtract seconds from a timestamp: addSeconds(StartTime, Offset * -1) |
| addMinutes(v: date, addend: number) | Adds or subtracts minutes from a given timestamp. Example: Add minutes to the current time: addMinutes(now(), ValidPeriod) |
| addHours(v: date, addend: number) | Adds or subtracts hours from a given timestamp. |
| now() | Returns the current timestamp in UTC. |
Enumeration¶
Enumeration values are set by selecting a value from the list of available options.
Example Usage¶
Scenario: You have an Assistant for employee onboarding. In Step 1, you capture the new employee's first and last names while in Step 2 you capture the employment location. Your organization uses different e-mail address patterns based on the country of employment and would like to generate the employee's e-mail address in Step 3.
Validation Hierarchy Setup:
- Open the Page Designer and locate the Assistant in question
- Locate the "E-mail address" field in Step 3
- Toggle (show) "Optional Attributes" by clicking the (...) button at the bottom of the field attributes.
- On the "Default Value Switch" node click (+) to add a new default value case item and set attributes
- Case:
LocationCode = "JP" - Value:
${FirstName}.${LastName}@jp.ventechi.com - Optionally create other rules reflecting other locations
- Confirm and close the dialog
- Save and then publish the configuration.
In this example, the default value for the "E-mail address" field is only applied if the location matches the desired condition. If the condition is met, the field is pre-populated with its default value in a way that reduces data entry effort and greatly minimizing errors. Since this is only the default value, the user is free to modify it if needed.
Important considerations¶
Here are some important points to bear in mind when configuring Default Values.
-
Default values are re-evaluated as other values are modified. However, if a value is manually changed at any point, the system stops updating it automatically. Note: In IFS Cloud Mobile the default values are evaluated only once, when the record is first initiated. Here, the values are not re-evaluated as a result of other changes. Exception to this is that in a multistep assistant IFS Cloud Mobile will also re-evaluate default values, when switching between steps.
-
Some field-specific formatting is enforced directly by the field when editing and displaying values (e.g., uppercase, lowercase). However, these formats are not validated or enforced system-wide. In these cases, it is important to ensure that a default value follows the correct format.
-
When referencing an attribute in a default value expression, no value converters are applied. E.g., A timestamp is stored in UTC format. If used in a text interpolation value, it will be displayed in ISO 8601 format.
-
When referencing attributes in a value expression, the referenced value must match the expected data type. For example, if a default value for a number attribute is set to
"ATextAttribute", the reference will be invalid, resulting in anulldefault value. This requirement applies to all data types except for string interpolation templates, where references are automatically cast to strings. For instance, in the template"My age is ${Age}", ifAgeis a numeric attribute with the value42, the expression evaluates to"My age is 42". Note that values are not automatically converted, and number and date formats will not be adjusted according to locale settings.