Update TBEL help links

2022-11-22 18:12:46 +02:00 · 2022-11-22 18:12:46 +02:00 · bed4d61281
commit bed4d61281
parent d10f64c348
10 changed files with 573 additions and 2 deletions
--- a/application/src/main/resources/thingsboard.yml
+++ b/application/src/main/resources/thingsboard.yml
@ -148,7 +148,7 @@ ui:
  # Help parameters
  help:
    # Base url for UI help assets
-    base-url: "${UI_HELP_BASE_URL:https://raw.githubusercontent.com/thingsboard/thingsboard-ui-help/release-3.4.1}"
+    base-url: "${UI_HELP_BASE_URL:https://raw.githubusercontent.com/thingsboard/thingsboard-ui-help/release-3.4.2}"

 database:
  ts_max_intervals: "${DATABASE_TS_MAX_INTERVALS:700}" # Max number of DB queries generated by single API call to fetch telemetry records
--- a/rule-engine/rule-engine-components/src/main/resources/public/static/rulenode/rulenode-core-config.js
+++ b/rule-engine/rule-engine-components/src/main/resources/public/static/rulenode/rulenode-core-config.js
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/clear_alarm_node_script_fn.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/clear_alarm_node_script_fn.md
@ -0,0 +1,68 @@
+#### Clear alarm details builder function
+
+<div class="divider"></div>
+<br/>
+
+*function Details(msg, metadata, msgType): any*
+
+JavaScript function generating **Alarm Details** object to update existing one. Used for storing additional parameters inside Alarm.<br>
+For example you can save attribute name/value pair from Original Message payload or Metadata.
+
+**Parameters:**
+
+{% include rulenode/tbel/common_node_script_args %}
+
+**Returns:**
+
+Should return the object presenting **Alarm Details**.
+
+Current Alarm Details can be accessed via `metadata.prevAlarmDetails`.<br>
+**Note** that `metadata.prevAlarmDetails` is a raw String field, and it needs to be converted into object using this construction:
+
+```javascript
+var details = {};
+if (metadata.prevAlarmDetails) {
+  // remove prevAlarmDetails from metadata
+  delete metadata.prevAlarmDetails;
+  details = JSON.parse(metadata.prevAlarmDetails);
+}
+{:copy-code}
+```
+
+<div class="divider"></div>
+
+##### Examples
+
+<ul>
+<li>
+Take <code>count</code> property from previous Alarm and increment it.<br>
+Also put <code>temperature</code> attribute from inbound Message payload into Alarm details:
+</li>
+</ul>
+
+```javascript
+var details = {temperature: msg.temperature, count: 1};
+
+if (metadata.prevAlarmDetails) {
+  var prevDetails = JSON.parse(metadata.prevAlarmDetails);
+  // remove prevAlarmDetails from metadata
+  delete metadata.prevAlarmDetails;
+  if (prevDetails.count) {
+    details.count = prevDetails.count + 1;
+  }
+}
+
+return details;
+{:copy-code}
+```
+
+<br>
+
+More details about Alarms can be found in [this tutorial{:target="_blank"}](${siteBaseUrl}/docs/user-guide/alarms/).
+
+You can see the real life example, where this node is used, in the next tutorial:
+
+- [Create and Clear Alarms{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/create-clear-alarms/)
+
+<br>
+<br>
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/common_node_script_args.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/common_node_script_args.md
@ -0,0 +1,11 @@
+<ul>
+  <li><b>msg:</b> <code>{[key: string]: any}</code> - is a Message payload key/value object.
+  </li>
+  <li><b>metadata:</b> <code>{[key: string]: string}</code> - is a Message metadata key/value map, where both keys and values are strings.
+  </li>
+  <li><b>msgType:</b> <code>string</code> - is a string containing Message type. See <a href="https://github.com/thingsboard/thingsboard/blob/ea039008b148453dfa166cf92bc40b26e487e660/ui-ngx/src/app/shared/models/rule-node.models.ts#L338" target="_blank">MessageType</a> enum for common used values.
+  </li>
+</ul>
+
+Enable 'debug mode' for your rule node to see the messages that arrive in near real-time. 
+See <a href="https://thingsboard.io/docs/user-guide/rule-engine-2-0/overview/#debugging" target="_blank">Debugging</a> for more information.
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/create_alarm_node_script_fn.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/create_alarm_node_script_fn.md
@ -0,0 +1,69 @@
+#### Create alarm details builder function
+
+<div class="divider"></div>
+<br/>
+
+*function Details(msg, metadata, msgType): any*
+
+JavaScript function generating **Alarm Details** object. Used for storing additional parameters inside Alarm.<br>
+For example you can save attribute name/value pair from Original Message payload or Metadata.
+
+**Parameters:**
+
+{% include rulenode/tbel/common_node_script_args %}
+
+**Returns:**
+
+Should return the object presenting **Alarm Details**.
+
+**Optional:** previous Alarm Details can be accessed via `metadata.prevAlarmDetails`.<br>
+If previous Alarm does not exist, this field will not be present in Metadata. **Note** that `metadata.prevAlarmDetails`<br>
+is a raw String field, and it needs to be converted into object using this construction:
+
+```javascript
+var details = {};
+if (metadata.prevAlarmDetails) {
+  // remove prevAlarmDetails from metadata
+  delete metadata.prevAlarmDetails;
+  details = JSON.parse(metadata.prevAlarmDetails);
+}
+{:copy-code}
+```
+
+<div class="divider"></div>
+
+##### Examples
+
+<ul>
+<li>
+Take <code>count</code> property from previous Alarm and increment it.<br>
+Also put <code>temperature</code> attribute from inbound Message payload into Alarm details:
+</li>
+</ul>
+
+```javascript
+var details = {temperature: msg.temperature, count: 1};
+
+if (metadata.prevAlarmDetails) {
+  var prevDetails = JSON.parse(metadata.prevAlarmDetails);
+  // remove prevAlarmDetails from metadata
+  delete metadata.prevAlarmDetails;
+  if (prevDetails.count) {
+    details.count = prevDetails.count + 1;
+  }
+}
+
+return details;
+{:copy-code}
+```
+
+<br>
+
+More details about Alarms can be found in [this tutorial{:target="_blank"}](${siteBaseUrl}/docs/user-guide/alarms/).
+
+You can see the real life example, where this node is used, in the next tutorial:
+
+- [Create and Clear Alarms{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/create-clear-alarms/)
+
+<br>
+<br>
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/filter_node_script_fn.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/filter_node_script_fn.md
@ -0,0 +1,84 @@
+#### Filter message function
+
+<div class="divider"></div>
+<br/>
+
+*function Filter(msg, metadata, msgType): boolean*
+
+JavaScript function defines a boolean expression based on the incoming Message and Metadata.
+
+**Parameters:**
+
+{% include rulenode/tbel/common_node_script_args %}
+
+**Returns:**
+
+Must return a `boolean` value. If `true` - routes Message to subsequent rule nodes that are related via **True** link, 
+otherwise sends Message to rule nodes related via **False** link. 
+Uses 'Failure' link in case of any failures to evaluate the expression.
+
+<div class="divider"></div>
+
+##### Examples
+
+* Forward all messages with `temperature` value greater than `20` to the **True** link and all other messages to the **False** link.
+  Assumes that incoming messages always contain the 'temperature' field:
+
+```javascript
+return msg.temperature > 20;
+{:copy-code}
+```
+
+
+Example of the rule chain configuration:
+
+![image](${helpBaseUrl}/help/images/rulenode/examples/filter-node.png)
+
+* Same as above, but checks that the message has 'temperature' field to **avoid failures** on unexpected messages:
+
+```javascript
+return typeof msg.temperature !== 'undefined' && msg.temperature > 20;
+{:copy-code}
+```
+
+* Forward all messages with type `ATTRIBUTES_UPDATED` to the **True** chain and all other messages to the **False** chain:
+
+```javascript
+if (msgType === 'ATTRIBUTES_UPDATED') {
+    return true;
+} else {
+    return false;
+}
+{:copy-code}
+```
+
+<ul>
+<li>Send message to the <strong>True</strong> chain if the following conditions are met.<br>Message type is <code>POST_TELEMETRY_REQUEST</code> and<br>
+(device type is <code>vehicle</code> and <code>humidity</code> value is greater than <code>50</code> or<br>
+device type is <code>controller</code> and <code>temperature</code> value is greater than <code>20</code> and <code>humidity</code> value is greater than <code>60</code>).<br>
+Otherwise send message to the <strong>False</strong> chain:
+</li>
+</ul>
+
+```javascript
+if (msgType === 'POST_TELEMETRY_REQUEST') {
+  if (metadata.deviceType === 'vehicle') {
+    return msg.humidity > 50;
+  } else if (metadata.deviceType === 'controller') {
+    return msg.temperature > 20 && msg.humidity > 60;
+  }
+}
+return false;
+{:copy-code}
+```
+
+<br>
+
+You can see real life example, how to use this node in those tutorials:
+
+- [Create and Clear Alarms{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/create-clear-alarms/#node-a-filter-script)
+- [Reply to RPC Calls{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/rpc-reply-tutorial#add-filter-script-node)
+
+<br>
+<br>
+
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/generator_node_script_fn.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/generator_node_script_fn.md
@ -0,0 +1,112 @@
+#### Message generator function
+
+<div class="divider"></div>
+<br/>
+
+*function Generate(prevMsg, prevMetadata, prevMsgType): {msg: object, metadata: object, msgType: string}*
+
+JavaScript function generating new Message using previous Message payload, Metadata and Message type as input arguments.
+
+**Parameters:**
+
+<ul>
+  <li><b>prevMsg:</b> <code>{[key: string]: any}</code> - is a previously generated Message payload key/value object.
+  </li>
+  <li><b>prevMetadata:</b> <code>{[key: string]: string}</code> - is a previously generated Message metadata key/value object.
+  </li>
+  <li><b>prevMsgType:</b> <code>string</code> - is a previously generated string Message type. See <a href="https://github.com/thingsboard/thingsboard/blob/ea039008b148453dfa166cf92bc40b26e487e660/ui-ngx/src/app/shared/models/rule-node.models.ts#L338" target="_blank">MessageType</a> enum for common used values.
+  </li>
+</ul>
+
+**Returns:**
+
+Should return the object with the following structure:
+
+```javascript
+{ 
+   msg: {[key: string]: any},
+   metadata: {[key: string]: string},
+   msgType: string
+}
+```
+
+All fields in resulting object are mandatory.
+
+<div class="divider"></div>
+
+##### Examples
+
+* Generate message of type `POST_TELEMETRY_REQUEST` with random `temperature` value from `18` to `32`:
+
+```javascript
+var temperature = 18 + Math.random() * (32 - 18);
+// Round to at most 2 decimal places (optional)
+temperature = Math.round( temperature * 100 ) / 100;
+var msg = { temperature: temperature };
+return { msg: msg, metadata: {}, msgType: "POST_TELEMETRY_REQUEST" };
+{:copy-code}
+```
+
+
+<ul>
+<li>
+Generate message of type <code>POST_TELEMETRY_REQUEST</code> with <code>temp</code> value <code>42</code>,
+<code>humidity</code> value <code>77</code><br>
+and <strong>metadata</strong> with field <code>data</code> having value <code>40</code>:
+</li>
+</ul>
+
+```javascript
+var msg = { temp: 42, humidity: 77 };
+var metadata = { data: 40 };
+return { msg: msg, metadata: metadata, msgType: "POST_TELEMETRY_REQUEST" };
+{:copy-code}
+```
+
+<ul>
+<li>
+Generate message of type <code>POST_TELEMETRY_REQUEST</code> with <code>temperature</code> value<br>
+increasing and decreasing linearly in the range from <code>18</code> to <code>32</code>:
+</li>
+</ul>
+
+```javascript
+var lower = 18;
+var upper = 32;
+var isDecrement = 'false';
+var temperature = lower;
+
+// Get previous values
+
+if (typeof prevMetadata !== 'undefined' &&
+  typeof prevMetadata.isDecrement !== 'undefined') {
+  isDecrement = prevMetadata.isDecrement;
+}
+if (typeof prevMsg !== 'undefined' &&
+  typeof prevMsg.temperature !== 'undefined') {
+  temperature = prevMsg.temperature;
+}
+
+if (isDecrement === 'true') {
+  temperature--;
+  if (temperature <= lower) {
+    isDecrement = 'false';
+    temperature = lower;
+  }
+} else {
+  temperature++;
+  if (temperature >= upper) {
+    isDecrement = 'true';
+    temperature = upper;
+  }
+}
+
+var msg = { temperature: temperature };
+var metadata = { isDecrement: isDecrement };
+
+return { msg: msg, metadata: metadata, msgType: "POST_TELEMETRY_REQUEST" };
+{:copy-code}
+```
+
+<br>
+<br>
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/log_node_script_fn.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/log_node_script_fn.md
@ -0,0 +1,37 @@
+#### Message to string function
+
+<div class="divider"></div>
+<br/>
+
+*function toString(msg, metadata, msgType): string*
+
+JavaScript function transforming incoming Message to String for further logging to the server log file.
+
+**Parameters:**
+
+{% include rulenode/tbel/common_node_script_args %}
+
+**Returns:**
+
+Should return `string` value used for logging to the server log file.
+
+<div class="divider"></div>
+
+##### Examples
+
+* Create string message containing incoming message and incoming metadata values:
+
+```javascript
+return 'Incoming message:\n' + JSON.stringify(msg) + 
+       '\nIncoming metadata:\n' + JSON.stringify(metadata);
+{:copy-code}
+```
+
+<br>
+
+You can see real life example, how to use this node in this tutorial:
+
+- [Reply to RPC Calls{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/rpc-reply-tutorial#log-unknown-request)
+
+<br>
+<br>
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/switch_node_script_fn.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/switch_node_script_fn.md
@ -0,0 +1,101 @@
+#### Switch message function
+
+<div class="divider"></div>
+<br/>
+
+*function Switch(msg, metadata, msgType): string[]*
+
+JavaScript function computing **an array of Link names** to forward the incoming Message.
+
+**Parameters:**
+
+{% include rulenode/tbel/common_node_script_args %}
+
+**Returns:**
+
+Should return an array of `string` values presenting **link names** that the Rule Engine should use to further route the incoming Message.<br>
+If the result is an empty array - message will not be routed to any Node and will be immediately 
+<a href="https://thingsboard.io/docs/user-guide/rule-engine-2-0/overview/#message-processing-result" target="_blank">acknowledged</a>.
+
+<div class="divider"></div>
+
+##### Examples
+
+<ul>
+<li>
+Forward all messages with <code>temperature</code> value greater than <code>30</code> to the <strong>'High temperature'</strong> chain,<br>
+with <code>temperature</code> value lower than <code>20</code> to the <strong>'Low temperature'</strong> chain and all other messages<br>
+to the <strong>'Other'</strong> chain:
+</li>
+</ul>
+
+```javascript
+if (msg.temperature > 30) {
+    return ['High temperature'];
+} else if (msg.temperature < 20) {
+    return ['Low temperature'];
+} else {
+    return ['Other'];
+}
+{:copy-code}
+```
+
+Example of the rule chain configuration:
+
+![image](${helpBaseUrl}/help/images/rulenode/examples/switch-node.png)
+
+<ul>
+  <li>
+    For messages with type <code>POST_TELEMETRY_REQUEST</code>:
+      <ul>
+        <li>
+          if <code>temperature</code> value lower than <code>18</code> forward to the <strong>'Low temperature telemetry'</strong> chain,
+        </li>
+        <li>
+          otherwise to the <strong>'Normal temperature telemetry'</strong> chain.
+        </li>
+      </ul>
+    For messages with type <code>POST_ATTRIBUTES_REQUEST</code>:<br>
+      <ul>
+        <li>
+            if <code>currentState</code> value is <code>IDLE</code> forward to the <strong>'Idle State'</strong> and <strong>'Update State Attribute'</strong> chains,
+        </li>
+        <li>
+            if <code>currentState</code> value is <code>RUNNING</code> forward to the <strong>'Running State'</strong> and <strong>'Update State Attribute'</strong> chains,
+        </li>
+        <li>
+            otherwise to the <strong>'Unknown State'</strong> chain.
+        </li>
+      </ul>
+    For all other message types - discard the message (do not route to any Node).
+  </li>
+</ul>
+
+```javascript
+if (msgType === 'POST_TELEMETRY_REQUEST') {
+  if (msg.temperature < 18) {
+    return ['Low Temperature Telemetry'];
+  } else {
+    return ['Normal Temperature Telemetry'];
+  }
+} else if (msgType === 'POST_ATTRIBUTES_REQUEST') {
+  if (msg.currentState === 'IDLE') {
+    return ['Idle State', 'Update State Attribute'];
+  } else if (msg.currentState === 'RUNNING') {
+    return ['Running State', 'Update State Attribute'];
+  } else {
+    return ['Unknown State'];
+  }
+}
+return [];
+{:copy-code}
+```
+
+<br>
+
+You can see real life example, how to use this node in this tutorial:
+
+- [Data function based on telemetry from 2 devices{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/function-based-on-telemetry-from-two-devices#delta-temperature-rule-chain)
+
+<br>
+<br>
--- a/ui-ngx/src/assets/help/en_US/rulenode/tbel/transformation_node_script_fn.md
+++ b/ui-ngx/src/assets/help/en_US/rulenode/tbel/transformation_node_script_fn.md
@ -0,0 +1,89 @@
+#### Transform message function
+
+<div class="divider"></div>
+<br/>
+
+*function Transform(msg, metadata, msgType): {msg: object, metadata: object, msgType: string}*
+
+The JavaScript function to transform input Message payload, Metadata and/or Message type to the output message.  
+
+**Parameters:**
+
+{% include rulenode/tbel/common_node_script_args %}
+
+**Returns:**
+
+Should return the object with the following structure:
+
+```javascript
+{ 
+   msg?: {[key: string]: any},
+   metadata?: {[key: string]: string},
+   msgType?: string
+}
+```
+
+All fields in resulting object are optional and will be taken from original message if not specified.
+
+<div class="divider"></div>
+
+##### Examples
+
+* Add sum of two fields ('a' and 'b') as a new field ('sum') of existing message:
+
+```javascript
+if(typeof msg.a !== "undefined" && typeof msg.b !== "undefined"){
+    msg.sum = msg.a + msg.b;
+}
+return {msg: msg};
+```
+
+* Transform value of the 'temperature' field from °F to °C:
+
+```javascript
+msg.temperature = (msg.temperature - 32) * 5 / 9;
+return {msg: msg};
+```
+
+* Replace the incoming message with the new message that contains only one field - count of properties in the original message:
+
+```javascript
+var newMsg = {
+    count: Object.keys(msg).length
+};
+return {msg: newMsg};
+```
+
+<ul>
+  <li>Change message type to <code>CUSTOM_UPDATE</code>,<br/>add additional attribute <strong><em>version</em></strong> into payload with value <strong><em>v1.1</em></strong>,<br/>change <strong><em>sensorType</em></strong> attribute value in Metadata to <strong><em>roomTemp</em></strong>:</li>
+</ul>
+
+```javascript
+var newType = "CUSTOM_UPDATE";
+msg.version = "v1.1";
+metadata.sensorType = "roomTemp"
+return {msg: msg, metadata: metadata, msgType: newType};
+{:copy-code}
+```
+
+* Replace the incoming message with **two** new messages that contain only one field - sum or difference of properties in the original message:
+
+```javascript
+var sum = msg.a + msg.b;
+var diff = msg.a - msg.b;
+
+return [
+    {msg: {sum: sum}, metadata: metadata, msgType: msgType},
+    {msg: {difference: diff}, metadata: metadata, msgType: msgType}
+    ];
+```
+
+<br>
+
+You can see real life example, how to use this node in those tutorials:
+
+- [Transform incoming telemetry{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/transform-incoming-telemetry/)
+- [Reply to RPC Calls{:target="_blank"}](${siteBaseUrl}/docs/user-guide/rule-engine-2-0/tutorials/rpc-reply-tutorial#add-transform-script-node)
+
+<br>
+<br>