Skip to content

Commit 628bb10

Browse files
authored
Improve doc widgets/data post processing + rephrase "Series" section (#2401)
1 parent e197288 commit 628bb10

File tree

1 file changed

+27
-4
lines changed

1 file changed

+27
-4
lines changed

_includes/docs/user-guide/widgets.md

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ A data key identifies the telemetry, attribute, or entity field a widget should
152152

153153
<b><font size="3">Sources of keys</font></b>
154154
- **Attributes** — the combined set of Client, Server, and Shared [attributes](/docs/{{docsPrefix}}user-guide/attributes/){:target="_blank"} of the selected entity. If a needed attribute doesn&#39;t exist yet, you can still add the key; the widget will show data once the device reports it.
155-
- **Time series** — telemetry keys reported by devices or written by the Rule Engine / [REST API](/docs/{{docsPrefix}}reference/rest-api/){:target="_blank"}.
155+
- **Time series** — telemetry keys reported by devices or written by the [Rule Engine](/docs/{{docsPrefix}}user-guide/rule-engine-2-0/overview/){:target="_blank"} / [REST API](/docs/{{docsPrefix}}reference/rest-api/){:target="_blank"}.
156156
- **Entity fields** — metadata fields that depend on entity type and may evolve over time (e.g. created time, entity type, name, type, label).
157157

158158
The data keys list for data source depends on the [widget type](/docs/{{docsPrefix}}user-guide/widgets/#widget-types){:target="_blank"}:
@@ -222,9 +222,9 @@ Let&#39;s look at the basic data key settings an example of the "Entities table"
222222

223223
{% include images-gallery.html imageCollection="data-key-configuration-color" %}
224224

225-
- **Use data postprocessing function** — enable a custom function to transform raw values before display.
225+
- [**Use data post-processing function**](#data-post-processing-function) — enable a custom function to transform raw values before display.
226226

227-
**Aggregation of key**
227+
##### Aggregation of key
228228

229229
By default, the Latest values widgets do not have the time window. If you enable aggregation for any data
230230
key in the **Latest values** widgets, the time window control will appear. You can set up aggregation for each telemetry
@@ -305,7 +305,30 @@ This option allows you to specify how the result should be displayed:
305305

306306
- **Delta (percent)** - Displays the result as a percentage relative to the previous interval <br>formula: **(IntervalValue - prevIntervalValue)/prevIntervalValue*100**
307307

308-
**Use data post-processing function.** The data post-processing function allows changing the output data depending on your wishes. To use data post-processing function, you must check the "Use data post-processing function" checkbox and enter the function in the field below. Then click the "Save" button in the lower-right corner.
308+
##### Data post-processing function
309+
The data post-processing function enables real-time transformation of incoming telemetry values before they are displayed
310+
in widgets. This feature allows you to apply custom JavaScript logic to each data point — for example, convert units,
311+
filter out anomalies, or calculate derived metrics without touching upstream sources.
312+
313+
**How to use:**
314+
- In the widget → go to section with **Data keys** → click the **Pencil** icon of the target data key.
315+
- Enable toggle **Use data post-processing function**.
316+
- Enter your code in the function body. The platform automatically injects the function header:
317+
<br> **function** (time, value, prevValue, timePrev, prevOrigValue) {
318+
<br> **`YOUR_JS_CODE`**
319+
<br> }
320+
- Click **Save** button.
321+
322+
**Once enabled, the function has access to the following parameters:**
323+
324+
- **time** – timestamp of the current value,
325+
- **value** – the current value,
326+
- **prevValue** – value returned by the previous function call,
327+
- **timePrev** – timestamp of the previous value,
328+
- **prevOrigValue** – original previous value.
329+
330+
The function must **return** a value (**number**|**string**|**boolean**|**null**).
331+
Returning **null** excludes the data point from visualization.
309332

310333
{% include images-gallery.html imageCollection="data-key-configuration-settings-post-processing" %}
311334

0 commit comments

Comments
 (0)