Transformation Services

Transformations are used to translate data from a cluttered or technical raw value to a processed or human-readable representation. They are often useful, to interpret received Item values, like sensor readings or state variables, and to translate them into a human-readable or better processible format.

Examples:

• Translation of a technical Binding output, e.g., “CLOSED” can be translated to the Spanish translation “cerrado”
• Processing of a raw Item value, e.g., Parsing a number from a JSON string, like { "temperature": 23.2 }
• Conversion of sensor readings, e.g., temperature in degree Celsius can be converted to degree Fahrenheit

Usage

Transformations are applicable in Item and Sitemap element labels and inside DSL rules. Be aware, that some Transformation services rely on transformation files, while others work by directly providing the transformation logic. Transformation files need to be placed in the directory $OPENHAB_CONF/transform.

1. Item and Sitemap Labels

   Transformations used in the state/value part of labels are applied on the fly. While the transformed value will (for example) be visible on a Sitemap, the original value is stored in the Item.

   The following example shows a Map transformation (see below) used in the State part of an Item’s label. The technical state of a Contact Item (e.g. “CLOSED”) is translated into a human readable representation in Spanish (“cerrado”).

   Contact Livingroom_Window        "Window [MAP(window_esp.map):%s]"               {/*Some Binding*/}
   Number  Kitchen_Temperature_C    "Temperature [JSONPATH($.temperature):%.1f °C]" {/*Some Binding*/}
   Number  Livingroom_Temperature_F "Temperature [JS(convert-C-to-F.js):%.1f °F]"   {/*Some Binding*/}
   
   

   Usage of Transformations in the label parameter of Sitemap elements works the same way.

2. Rules

   Transformations can also be used in rules to transform/translate/convert data. The following shows three examples:

   var condition = transform("MAP", "window_esp.map", "CLOSED")
   var temperature = transform("JSONPATH", "$.temperature", jsonstring)
   var fahrenheit = transform("JS", "convert-C-to-F.js", temperature)
   

To keep these examples simple, the contents of the referenced files window_esp.map and convert-C-to-F.js were left out. More details regarding this and other Transformation services can be found in the individual transformation articles linked below.

Available Transformations

Be aware that a transformation service just as any other openHAB add-on needs to be installed prior to first usage.

Name	Description
Exec	Execute an external program, substituting the placeholder %s in the given command line with the input value, and returning the output of the external program.
JavaScript	Transform an input to an output using JavaScript.
JsonPath	Extract an element of a JSON string using a JsonPath expression.
Map	Transforms the input by mapping it to another string. It expects the mappings to be read from a file which is stored under the transform folder.
RegEx	Given a source string and a regular expression, use the regular expression to yield a transformed string.
Scale	The Scale Transformation Service is a an easy to handle tool that can help you with the discretization of number inputs.
XPath	Transform XML input using an XPath expression.
XSLT	Transform input using the XML Stylesheet Language for Transformations (XSLT).