# 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 provided command line is split on spaces before it is passed to the shell.
Using single quotes ('
) splitting can be avoided (e.g. '%s'
would prevent splitting on spaces within the input value).
The surrounding single quotes are removed.
The external program must either be in the executable search path of the server process, or an absolute path has to be used.
For security reasons all commands need to be whitelisted.
Allowed commands need to be added to the misc/exec.whitelist
file in the configuration directory.
Every command needs to be on a separate line.
Example:
/bin/date -v1d -v+1m -v-1d -v-%s
numfmt --to=iec-i --suffix=B --padding=7 %s
# Examples
# General Setup
# Item
This will replace the visible label in the UI with the transformation you apply with the command <TransformProgram>.
String yourItem "Some info [EXEC(/absolute/path/to/your/\<TransformProgram\> %s):%s]"
# Rule
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
/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
numfmt --to=iec-i --suffix=B --padding=7 %s
When the input argument for %s
is 1234567 it will return the bytes formatted in a better readable form
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:
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 (opens new window) and tutorial (opens new window) for date.
- Manual (opens new window) and tutorial (opens new window) for numfmt.
← Binary To JSON Jinja →