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.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)