95 lines
2.8 KiB
Markdown
95 lines
2.8 KiB
Markdown
---
|
|
id: exec
|
|
label: Exec
|
|
title: Exec - Transformation Services
|
|
type: transform
|
|
description: "Transforms an input string with an external program."
|
|
since: 2x
|
|
install: auto
|
|
---
|
|
|
|
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
|
|
|
|
{% include base.html %}
|
|
|
|
# Exec Transformation Service
|
|
|
|
Transforms an input string with an external program.
|
|
|
|
Executes an external program and returns the output as a string.
|
|
In the given command line the placeholder `%s` is substituted with the input value.
|
|
|
|
The external program must either be in the executable search path of the server process, or an absolute path has to be used.
|
|
|
|
## Examples
|
|
|
|
### General Setup
|
|
|
|
**Item**
|
|
|
|
This will replace the visible label in the UI with the transformation you apply with the command <TransformProgram>.
|
|
|
|
```java
|
|
String yourItem "Some info [EXEC(/absolute/path/to/your/<TransformProgram> %s):%s]"
|
|
```
|
|
|
|
**Rule**
|
|
|
|
```java
|
|
rule "Your Rule Name"
|
|
when
|
|
Item YourTriggeringItem changed
|
|
then
|
|
var formatted = transform("EXEC","/absolute/path/to/your/<TransformProgram>", YourTriggeringItem.state.toString)
|
|
yourFormattedItem.sendCommand(formatted.toString)
|
|
end
|
|
```
|
|
|
|
### Example with a program
|
|
|
|
Substitute the `/absolute/path/to/your/<TransformProgram>` with
|
|
|
|
```shell
|
|
/bin/date -v1d -v+1m -v-1d -v-%s
|
|
```
|
|
|
|
When the input argument for `%s` is `fri` the execution returns a string with the last weekday of the month, formated as readable text.
|
|
|
|
```
|
|
Fri 31 Mar 2017 13:58:47 IST`
|
|
```
|
|
|
|
Or replace it with
|
|
|
|
```shell
|
|
numfmt --to=iec-i --suffix=B --padding=7 %s
|
|
```
|
|
|
|
When the input argument for `%s` is 1234567 it will return the bytes formated in a better readable form
|
|
|
|
```shell
|
|
1.2MiB
|
|
```
|
|
|
|
### Usage as a Profile
|
|
|
|
The functionality of this `TransformationService` can be used in a `Profile` on an `ItemChannelLink` too.
|
|
To do so, it can be configured in the `.items` file as follows:
|
|
|
|
```java
|
|
String <itemName> { channel="<channelUID>"[profile="transform:EXEC", function="<shellcommand>", sourceFormat="<valueFormat>"]}
|
|
```
|
|
|
|
The shell command to be executed has to be set in the `function` parameter.
|
|
The parameter `sourceFormat` is optional and can be used to format the input value **before** the transformation, i.e. `%.3f`.
|
|
If omitted the default is `%s`, so the input value will be put into the transformation without any format changes.
|
|
|
|
Please note: This profile is a one-way transformation, i.e. only values from a device towards the item are changed, the other direction is left untouched.
|
|
|
|
# Further Reading
|
|
|
|
* [Manual](http://man7.org/linux/man-pages/man1/date.1.html) and [tutorial](https://linode.com/docs/tools-reference/tools/use-the-date-command-in-linux/) for date.
|
|
* [Manual](http://man7.org/linux/man-pages/man1/numfmt.1.html) and [tutorial](http://www.pixelbeat.org/docs/numfmt.html) for numfmt.
|
|
|
|
|