How to do custom data transformations on GenKPI objects

KPI objects in the KPI Model can be configured to perform custom data transformations on values requested by Visual KPI or other clients using the Web API. The purpose of this is to give users the ability to display KPIs with custom aggregations or to perform calculations on data prior to display.

Data Transformation Properties are configured in GenKPI objects in the KPI Model.

Data Transformation Properties

Data Transformation compound it’s made up of the following 3 properties:

  • ReadValue: gets the real time value for the actual field in VisualKPI.

  • ReadHistory: gets the historical data for a specified time range.

  • ReadHistoryAtTime: gets the historical data for a specific timestamp.

For this section, we will be setting the ReadValue property as the example. In order to do that, we will use a Lua Script example in this field to get real time values that can be display in Visual KPI.

In this example we will be using DemoData Examples. For more information please visit Configuring the Examples.

How Data Transformation works

Web API requests from clients using the Read, Read Historical Data and Read Historical Data at Time functions will be overloaded by any Lua scripts configured in the Data Transformation Properties the Gen KPI object. The original arguments entered for the Web API request are used as arguments for the Lua function configured in the custom script. If no Data Transformation scripts are configured then the original Web API request is returned.

Configuration of the Data Transformation

  1. In the Data Transformation compound, look for the ReadValue Property and click on the …​ button to open the ScriptEditor.

  2. For this example we will use the following example Script to describe how we will transform the RealValue in real time into a custom calculation.

    return function()
	local p = "/System/Core/Examples/DemoData/ProcessData/DC4711"
	local v, q, t = syslib.getvalue(p)
	return {v = v*20, q = q, t = t)
end

  3. Remember to place the correct path (for the Generic Item in the I/O Model) of the object you want to make the custom calculation, then click Ok and at last click the Apply. button to perform the changes.

As you may figured the actual value will be multiplied by 20, this new value will be displayed in Visual KPI as the Actual Value.

Congratulations!.By now, you have made a successful custom calculation with Data Transformation.

Visualization of the Data Transformation

After setting all the custom calculation in DataStudio, the following steps will allow to visualize all the setup you just have made.

For visualization of this setting, you must have previously configured Visual KPI, for more information please check the JumpStart on Instaliling Visual KPI.

  1. Open Visual KPI, and click onto the Group that the KPI is placed.

  2. Look for the Density KPI and click on in.

    Visualization of Data Transformation on Visual KPI

  3. You can compare this value on the Visual KPI to the value that is display in the Faceplate in the Object Properties of th Generic KPI and see the custom calculation changes the Real Value.