193 lines
6.7 KiB
Markdown
193 lines
6.7 KiB
Markdown
---
|
||
layout: documentation
|
||
title: Rules Blockly - Run & Process and Transformations
|
||
---
|
||
<!-- markdownlint-disable MD036 -->
|
||
|
||
# Run & Process (Rules and Scripts)
|
||
|
||
[return to Blockly Reference](index.html#run-process-rules-and-scripts)
|
||
|
||
## Introduction
|
||
|
||
This section contains several possibilities
|
||
|
||
- Calling Rules or other scripts either located as files on the server or provided via the UI
|
||
- Retrieving attributes provided by the rule context or from the own caller rule.
|
||
- Transforming values via different conversion methods (map, regex, jsonpath)
|
||
|
||
**A note about Rules and Scripts**
|
||
|
||
A Script _is_ a Rule too. It’s just a special type of rule that only has a single script action and a “Script” tag.
|
||
|
||
[[toc]]
|
||
|
||
## Overview of the Run & Process blocks
|
||
|
||
|
||
|
||
## Run & Process Blocks
|
||
|
||
See also the short video part about  [Run & Process blocks, transform](https://youtu.be/KwhYKy1_qVk?t=2110)
|
||
|
||
### Call Script File
|
||
|
||
|
||
|
||
_Function:_ Calls a script file with the given name which must be located in the _$OPENHAB_CONF/scripts/_ folder.
|
||
|
||
- No parameters can be provided
|
||
|
||
See [openHAB Call-Script](https://www.openhab.org/docs/configuration/actions.html#openhab-subsystem-actions) for background information
|
||
|
||
### Run Rule or Script created in UI
|
||
|
||
|
||
|
||
_Function:_ calls another _rule_ or _script_ that was created via the openHAB UI.
|
||
|
||
The _ruleUID_ can be found in the list of rules or scripts in the second line of the list (like here _helloBlockly_ or _helloWorld_)
|
||
|
||
|
||
Parameters are optional:
|
||
|
||
- If not providing parameters leave the _with context_ section as is.
|
||
- If providing parameters you **must** replace the _create empty dictionary_ block with [the _dictionary_ block from the Lists section](https://community.openhab.org/t/blockly-reference/128785#lists-76), modifying the number of key/value pairs to suit.
|
||
|
||
Notes:
|
||
|
||
- parameters can be retrieved in the called script via the "get context attribute"-block (see below)
|
||
- the called rule / script cannot return any value
|
||
- it is not possible to access a particular function in another script or rule as scripts / rules have to be perceived as completely autonomous
|
||
- the called rule / script is run synchronously
|
||
|
||
### Retrieve context attribute from rule
|
||
|
||
Function: Retrieve context attributes passed by a calling rule/script (see above)
|
||
|
||
|
||
|
||
This retrieves the value for the key "myKey1" that was passed by the calling rule.
|
||
|
||
_Example_
|
||
|
||
|
||
|
||
### Retrieve rule context information
|
||
|
||
|
||
|
||
_Function:_ Retrieve event context related information of the rule
|
||
|
||
A rule carries contextual information when triggered - this block can retrieve that information.
|
||
|
||
- The rule trigger type defines which of the attributes are available to the rule - the types available depend on the trigger type of the rule.
|
||
- For more detailed information see [UI Event Object](https://next.openhab.org/addons/automation/jsscripting/#ui-event-object) or [openHAB Events](https://www.openhab.org/docs/developer/utils/events.html).
|
||
|
||
Here is a list of possible values that can be retrieved.
|
||
|
||
- rule UID - String
|
||
- event available - Boolean
|
||
- event type - String
|
||
- new state of item - String / Number by selection
|
||
- previous state of item - String / Number by selection
|
||
- triggering item name - [Item](rules-blockly-items-things.html#item), not a String
|
||
- received command - String / Number by selection
|
||
- triggered channel - String
|
||
- triggered event - String
|
||
|
||
Note on "event available": All values except _rule UID_ expect an event context to be available.
|
||
Thus, to avoid issues, you can validate that with the _event available_ block in case this is not guaranteed in your rule.
|
||
|
||
The block adds a selection drop down in case a state or command is returned:
|
||
|
||
|
||
|
||
## Transform values via Map, Regex or JsonPath and others
|
||
|
||
openHAB provides many [transformations](https://www.openhab.org/docs/configuration/transformations.html):
|
||
|
||
- [Map](https://www.openhab.org/addons/transformations/map/)
|
||
- [Regex](https://www.openhab.org/addons/transformations/regex/)
|
||
- [JsonPath](https://www.openhab.org/addons/transformations/jsonpath/)
|
||
- [Binary to Json](https://www.openhab.org/addons/transformations/bin2json/)
|
||
- [Exec](https://www.openhab.org/addons/transformations/exec/)
|
||
- [Jinja](https://www.openhab.org/addons/transformations/jinja/)
|
||
- [Scale](https://www.openhab.org/addons/transformations/scale/)
|
||
- [XPath](https://www.openhab.org/addons/transformations/xpath/)
|
||
- [XSLT](https://www.openhab.org/addons/transformations/xslt/)
|
||
|
||
The following describes examples for Map, Regex, and JsonPath
|
||
|
||
|
||
|
||
|
||
|
||
Function: Transform the given value via one of the different transformation methods
|
||
|
||
### Example 1: Regex
|
||
|
||
Convert #123456 into rgb(12,34,56)
|
||
|
||
|
||
|
||
### Example 2: JsonPath transformation
|
||
|
||
Extract the temperature from the following JSON
|
||
|
||
```json
|
||
{ "device": { "location": "Outside", "status": { "temperature": 23.2 }}}
|
||
```
|
||
|
||
by using the jsonpath
|
||
|
||
```json
|
||
$.device.status.temperature
|
||
```
|
||
|
||
|
||
|
||
### Example 3: Map transformation
|
||
|
||
This example applies a map transformation from the map file nanoleaf.map in _$OPENHAB-CONF/transform/_
|
||
|
||
|
||
|
||
The above, with the below map file
|
||
|
||
```text
|
||
ON=Ja
|
||
OFF=Nein
|
||
effects=Effekte
|
||
-=?
|
||
NULL=n/a
|
||
hs = Hue/Saturation
|
||
ct = Color Temperature
|
||
```
|
||
|
||
would result in the following log entry
|
||
|
||
```bash
|
||
Hue/Saturation
|
||
```
|
||
|
||
## Inline Script
|
||
|
||
|
||
|
||
_Function:_ execute arbitrary ECMAScript content
|
||
|
||
Provides the possibility to inject any ECMAScript at a given position.
|
||
This should be used in cases when Blockly does not provide the desired functionality.
|
||
Use with diligence.
|
||
|
||
### Example
|
||
|
||
|
||
|
||
See also the short video part about  [Inline Scripts](https://youtu.be/KwhYKy1_qVk?t=2165)
|
||
|
||
## Return to Blockly Reference
|
||
|
||
[return to Blockly Reference](index.html#run-process-rules-and-scripts)
|