Merge pull request #14673 from irynamatveieva/related-entities-cf/help-page

Related entities aggregation calculated field: added help pages for scripts

ui-ngx/src/app/modules/home/components/calculated-fields/components/metrics/calculated-field-metrics-panel.component.html

@@ -170,7 +170,7 @@
                     [highlightRules]="highlightRules"
                     [editorCompleter]="editorCompleter"
                     [helpPopupStyle]="{ width: '1200px' }"
-                    helpId="calculated-field/expression_fn">
+                    helpId="calculated-field/map_expression_fn">
           <div toolbarPrefixButton
                class="tb-primary-background tbel-script-lang-chip">{{ 'api-usage.tbel' | translate }}
           </div>

ui-ngx/src/assets/help/en_US/calculated-field/expression_fn.md

@@ -11,12 +11,16 @@ function calculate(ctx, arg1, arg2, ...): object | object[]
 
 ### Supported Arguments
 
+Arguments are passed to the function by **name** defined in the calculated field configuration.
+
 There are three types of arguments supported in the calculated field configuration:
 
 #### Attribute and Latest Telemetry Arguments
 
 These arguments are single values and may be of type: boolean, int64 (long), double, string, or JSON.
 
+#### Direct argument access via **`<argName>`**
+
 **Example: Convert Temperature from Fahrenheit to Celsius**
 
 ```javascript
@@ -26,7 +30,9 @@ return {
 }
 ```
 
-Alternatively, using `ctx` to access the argument as an object:
+#### Accessing argument via **`ctx.args.<argName>`**
+
+In addition to direct access, arguments can be accessed via the `ctx.args.<argName>` object, which includes both the `value` of an argument and its timestamp as `ts`:
 
 ```json
 {
@@ -37,7 +43,6 @@ Alternatively, using `ctx` to access the argument as an object:
 }
 ```
 
-You may notice that the object includes both the `value` of an argument and its timestamp as `ts`.
 Let's modify the function that converts Fahrenheit to Celsius to also return the timestamp information:
 
 ```javascript

ui-ngx/src/assets/help/en_US/calculated-field/filter_expression_fn.md

@@ -1,10 +1,70 @@
 ## Calculated Field TBEL Filter Function
 
-The **filter()** function is a user-defined script that enables custom calculations using [TBEL](${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/tbel/) on telemetry and attribute data.
+The **filter()** function is a [TBEL](${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/tbel/) script used in aggregation metrics of a calculated field.
+
 It receives arguments configured in the calculated field setup, along with an additional `ctx` object that stores `latestTs` and provides access to all arguments.
 
+It allows you to include or exclude related entities from aggregation based on their telemetry or attribute values.
+
+The filter is evaluated per related entity before the aggregation function is applied.
+
 ### Function Signature
 
 ```javascript
-function calculate(ctx, arg1, arg2, ...): boolean
+function filter(ctx, arg1, arg2, ...): boolean
+```
+
+### Supported Arguments
+
+Arguments are passed to the function by **name** defined in the calculated field configuration.
+
+There are two types of arguments supported in the calculated field configuration: **Attribute and Latest Telemetry Arguments**
+
+These arguments are single values and may be of type: boolean, int64 (long), double, string, or JSON.
+
+#### Direct argument access via **`<argName>`**
+
+**Example: Count free parking spaces**
+
+**Goal**: Include only parking spaces that are active and not occupied.
+
+```javascript
+return active == true && occupied == false;
+```
+
+Only entities that satisfy this condition will be included in the aggregation.
+
+#### Accessing argument via **`ctx.args.<argName>`**
+
+In addition to direct access, arguments can be accessed via the `ctx.args.<argName>` object, which includes both the `value` of an argument and its timestamp as `ts`:
+
+```json
+{
+  "consumption": {
+    "ts": 1740644656669,
+    "value": 542.6
+  }
+}
+```
+
+The `ctx.latestTs` property represents the latest timestamp across all related entities and their arguments participating in the aggregation.
+
+**Example: Calculate the total consumption across multiple related pumps**
+
+**Scenario**: Each pump reports consumption telemetry approximately every 10 minutes, but reporting times may vary due to network delays (up to ~30 seconds).
+To avoid counting outdated values, only recently updated telemetry should be included.
+
+**Goal**: Include only pumps whose consumption value was reported within 1 minute of the latest timestamp.
+
+```javascript
+var ONE_MINUTE = 60 * 1000;
+return (ctx.latestTs - ctx.args.consumption.ts) <= ONE_MINUTE;
 ```
+
+### Function return format
+
+The function **must** return a boolean:
+- `true` → include entity in aggregation
+- `false` → exclude entity from aggregation
+
+Any other return type is considered invalid.

ui-ngx/src/assets/help/en_US/calculated-field/map_expression_fn.md

@@ -0,0 +1,79 @@
+## Calculated Field TBEL Map Function
+
+The **map()** function is a [TBEL](${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/tbel/) script used in aggregation metrics of a calculated field.
+
+It determines the value applied by each related entity to the aggregation.
+
+The function receives arguments configured in the calculated field setup, along with an additional `ctx` object that stores `latestTs` and provides access to all arguments.
+
+The function is evaluated **per related entity**, after filtering is applied.
+
+### Function Signature
+
+```javascript
+function map(ctx, arg1, arg2, ...): number | boolean | string
+```
+
+### Supported Arguments
+
+Arguments are passed to the function by **name** defined in the calculated field configuration.
+
+There are two types of arguments supported in the calculated field configuration: **Attribute and Latest Telemetry Arguments**
+
+These arguments are single values and may be of type: boolean, int64 (long), double, string, or JSON.
+
+#### Direct argument access via **`<argName>`**
+
+**Example: Calculate average temperature across sensors**
+
+**Scenario**: Multiple related sensors report temperature in Fahrenheit. You want to aggregate temperature values, but the aggregation must be performed in Celsius.
+
+**Goal**: Convert temperature to Celsius before aggregation
+
+```javascript
+var temperatureC = (temperature - 32) / 1.8;
+return toFixed(temperatureC, 2);
+```
+
+Instead of creating a separate calculated field for conversion, the transformation is performed per entity, before aggregation.
+
+#### Accessing argument via **`ctx.args.<argName>`**
+
+In addition to direct access, arguments can be accessed via the `ctx.args.<argName>` object, which includes both the `value` of an argument and its timestamp as `ts`:
+
+```json
+{
+  "temperature": {
+    "ts": 1740644656761,
+    "value": 33.6
+  }
+}
+```
+
+The `ctx.latestTs` property represents the latest timestamp across all related entities and their arguments participating in the aggregation.
+
+**Example: Calculate average temperature**
+
+**Scenario**: Each sensor reports temperature approximately every 10 minutes, but reporting times may vary due to network delays (up to ~30 seconds).
+If a temperature value is outdated, you want the entity to remain part of the aggregation, but contribute a default value instead of a stale one.
+
+**Goal**: Return a default value when the temperature was not reported within 1 minute of the latest aggregation timestamp.
+
+```javascript
+var ONE_MINUTE = 60 * 1000;
+if ((ctx.latestTs - ctx.args.temperature.ts) > ONE_MINUTE) {
+  return 0;
+};
+return temperature;
+```
+
+### Function return format
+
+The returned value is passed directly to the aggregation engine:
+
+| Aggregation function           | Expected return value |
+|--------------------------------|-----------------------|
+| Count, Count unique            |       any value       |
+| Sum, Average, Minimum, Maximum |        number         |
+
+Returning a value of an incompatible type may result in the entity being ignored or the aggregation producing incorrect results.