Widgets

The Kaa Web Dashboard (WD) is pre-shipped with a collection of widgets that receive data from other Kaa services and display them in different visual layouts. The table below summarizes the current collection of Kaa widgets. It describes each widget’s purpose, type, and the Kaa services involved in the widget operation.

Widget name Purpose Services
endpoint list Create and view endpoints endpoint management rest api
software list Create and view software updates and their details over the air updates rest api, endpoint management rest api
software version details View and modify software updates and their details over the air updates rest api, endpoint management rest api
endpoint metadata View, add, edit and delete endpoint metadata endpoint management rest api
configuration View and edit endpoint configuration endpoint configuration rest api
map View location of one or more endpoints endpoint management rest api, time series rest api
multi series chart View time series data in the graphical format time series rest api
time series table View time series data in the table format time series rest api
gauge View the last value in time series time series rest api
raw html Render custom HTML endpoint management rest api
endpoint label Display a custom image with labels that represent data endpoint management rest api, time series rest api
command execution Execute remote commands via a switch time series rest api, endpoint management rest api, commands rest api
filter list View endpoint filters and their details endpoint management rest api
filter details View and modify details of a specific filter endpoint management rest api
endpoint token status Create, activate, suspend and revoke the endpoint token endpoint management rest api
binary blobs list Displays uploaded blobs for individual applications or endpoints binary data rest api
endpoint orientation Displays device orientation in space time series rest api
luminance Displays light level time series rest api
basic client credentials View, add and modify users credentials (username/password) kaa rest api authentication
tls certificates View, add and modify users credentials (TLS certificate) kaa rest api authentication
dashboard controls Set dashboard context which may be used by the dashboard widgets  

Endpoint list

The Endpoint list widget is primarily used to display a list of the available devices for the user.

eplist-view

The second important feature of this widget is enabling the user to create new endpoints.

eplist-view

The widget also supports displaying filtered endpoints.

eplist-view

You can also configure interoperation between this widget and the Map widget to control which endpoint locations are displayed on the map.

eplist-view

This feature may be enabled by selecting the Should rows be selectable? option in the Endpoint list widget settings

eplist-view

as well as the corresponding configuration option in the map widget. You can find more information in the Map widget section.

You can configure the widget to enable the direct link between entities in the table and their dashboards. To learn more, click here.

The Endpoint list widget supports the following interfaces:

Endpoint list interfaces diagram

Filter list

The Filter list widget is used to display a list of the available filters for the user.

filterlist-view

It also enables the user to create new filters as well as delete them:

filterlist-view

You can configure the widget to enable the direct link between entities in the table and their dashboards. To learn more, click here.

The Filter list widget supports the following interfaces:

Filter list interfaces diagram

Software list

The Software list widget is used to display a list of the available software versions for the user.

softwarelist-view

It also enables the user to create new software versions.

You can configure the widget to enable the direct link between entities in the table and their dashboards. To learn more, click here.

The Software list widget supports the following interfaces:

Software list interfaces diagram

Endpoint token status

The Endpoint token status widget is used to manage the status of the endpoint token. The user can create, activate, suspend and revoke the endpoint token.

ep_token_status

The Endpoint token status widget supports the following interfaces:

Endpoint token status interfaces diagram

Configuration

The Configuration widget is used to view and edit configuration of the endpoint or the endpoint group.

configuration-sample

The widget enables the user to:

  1. Display a single integer value and change it.

configuration-sample

  1. Display several endpoint configuration parameters and change them.

configuration-sample

  1. Display configuration as JSON in the text editor area and modify it.

configuration-sample

The Configuration widget supports the following interfaces:

Configuration interfaces diagram

Command execution

The Command execution widget is used to execute commands on an endpoint.

Command execution widget

The Configuration widget supports the following interfaces:

Command execution interfaces diagram

Endpoint label

The Endpoint label widget is used to display endpoint dynamic data over a custom image.

example

The Endpoint label widget supports the following interfaces:

Endpoint label interfaces diagram

Filter details

The Filter details widget is used to view and edit filter details.

filterDetails

It supports the following interfaces:

filterDetails interfaces diagram

Gauge

The Gauge widget is used to display the last time series data for an endpoint. This widget has different representations depending on its type. Here are some of the gauge layouts available in WD.

gauge-sample

It supports the following interfaces:

filterDetails interfaces diagram

Endpoint metadata

The widget is used to monitor the endpoint metadata information stored in the endpoint management rest api service.

example

It supports the following interfaces:

metadata interfaces diagram

Multi series chart

The Multi series chart widget is used to display a chart that shows time series data for one or more endpoints. Below is an example of a line chart.

icon

Multi series chart widget supports display of data as a bar chart as well.

icon

Moreover, it is possible to configure output of different data series in all available modes at once: line, bar and step.

icon

The Multi series chart widget supports the following interfaces:

 interfaces diagram

Raw HTML

The Raw HTML widget is used to embed custom HTML into the dashboards. This widget supports totally static HTML content

-screenshot-static-html

as well as dynamic endpoint data stored in the endpoint management rest api service.

-screenshot-epr-response

There are two ways to embed an image into the HTML content: encoding it into Base64 or referencing it from the WD external static resources.

The Raw HTML widget is capable to handle with following advanced templates:

Conditional rendering:

${ @if (number < 0) }
	'number' is less than 0
${ #elif (number > 0) }
	'number' is bigger than 0
${ #else }
	'number' is 0
${ /if }

Iterating over an array:

${ @each(someArray) => val, index }
	The current array item is ${val}, the current index is ${index}
${ /each }

Iterating over an object:

${ @foreach(someObject) => key, val } 
	The current object key is ${key}, and the value is ${val}
${ /foreach }

Sort by specific key with optional parameter to specify the order as asc / desc:

${ @sortBy(collection, key, order) => sortedCollection }
  ${ @each(sortedCollection) => val, index }
	The sorted value is ${val[key]}
  ${ /each }
${ /sortBy }

Find by accepts the key and value and return found item or null:

${ @findBy(collection, 'key', 'value') => foundItem }
  The found item's name is ${foundItem[key]}
${ /sortBy }

Filter by accepts the key and value and returns filtered array. Nested objects are supported:

${ @filterBy(collection, 'key', 'value') => filteredCollection }
  The filtered collection is ${filteredCollection}
${ /filterBy }

<!-- Find item by nested key -->
${ @findBy(collection, 'sensor.type', 'temperature') => foundItem }
  The found item's name is ${foundItem.name}
${ /findBy }

<!-- Find item by deeply nested key -->
${ @findBy(collection, 'device.sensor.readings.latest', '25.5') => foundItem }
  The found device is ${foundItem.device.name}
${ /findBy }

try…catch structures:

${ @try }
	This won't work: ${unknownVariable}
${ #catch => err }
	Uh-oh, error! Message: "${err.message}"
${ /try }

There is also support for pipe expressions to manipulate the value.

For example with given json assigned to metadata variable in the widget configuration:

{
  "name": "Device 1",
  "sensors": [
    {"name": "Sensor 1"},
    {"name": "Sensor 2"}
  ] 
}

json(spacing?): output json string. Optionally accepts white space counter for better readability.

<!-- Output json string. Useful for debugging -->
<pre>${metadata | json}</pre>
<!-- renders -->
<pre>{ "name": "Device 1", "sensors": [ {"name": "Sensor 1"}, {"name": "Sensor 2"} ] }</pre>

<!-- json pipe accepts optional number of spaces to prettify json   -->
<pre>${it | json('2')}</pre>

mapBy(key): creates array iterating by each element and returns the value of key during iteration

<!-- Map values by specified key -->
<span>${metadata.sensors | mapBy('name')}</span>
<!-- renders -->
<span>Sensor 1,Sensor 2</span>

findBy(key, value): finds the first item by the given key and value. Supports nested objects.

<!-- Find the first item by the given key and value. Suppose the object is:
{
  "sensors": [
    {"name": "Sensor 1"},
    {"name": "Sensor 2"}
  ]
} -->
<span>${metadata.sensors | findBy('name', 'Sensor 1')}</span>
<!-- renders -->
<span>Sensor 1</span>
<!-- Find the first item by the given nested key and value. Suppose the object is nested like:
{
  "sensors": [
    {
      "name": "Sensor 1",
      "customer": {
        "name": "KaaIoT",
        "id": 123
      }
    },
    {
      "name": "Sensor 2", 
      "customer": {
        "name": "Acme Corp",
        "id": 456
      }
    }
  ]
} -->
<span>${metadata.sensors | findBy('customer.name', 'KaaIoT')}</span>
<!-- renders -->
<span>KaaIoT</span>

filterBy(key, value): filters the array by the given key and value. Supports nested objects.

<!-- Filter the array by the given key and value. Suppose the object is:
{
  "sensors": [
    {"name": "Sensor 1"},
    {"name": "Sensor 2"}
  ]
} -->
<span>${metadata.sensors | filterBy('name', 'Sensor 1')}</span>
<!-- renders -->
<span>[{"name": "Sensor 1"}]</span>
<!-- Filter the array by the given nested key and value. Suppose the object is nested like:
{
  "sensors": [
    {
      "name": "Sensor 1",
      "customer": {
        "name": "KaaIoT",
        "id": 123
      }
    },
  ]
} -->
<span>${metadata.sensors | filterBy('customer.name', 'KaaIoT')}</span>

join(separator?): joins array with given separator

<!-- Join array by optional separator  -->
<span>${metadata.sensors | mapBy('name') | join('=')}</span>
<!-- renders -->
<span>Sensor 1=Sensor 2</span>

formatDate(format?): converts the date according to current timezone, to specific format. By default format is YYYY-MM-DD HH:mm:ss

<!-- With default format  -->
<span>${createdDate | formatDate}</span>
<!-- renders -->
<span>2023-01-20 10:00:00</span>

<!-- With specific format Day Month name, Year -->
<span>${createdDate | formatDate('DD MMMM, YYYY')}</span>
<!-- renders -->
<span>20 January, 2023</span>

timeAgo(): accepts date and returns the time ago moment processed date. When data is empty current date is returned.

<!-- With timestamp -->
<span>${createdDate | timeAgo}</span>
<!-- renders -->
<span>an hour ago</span>

duration(format?): optionally accepts units like “ms”, “s”, “h”, “m” and returns the user friendly value of duration

<!-- With seconds -->
<span>${600 | duration}</span>
<!-- renders -->
<span>10 minutes</span>

<!-- With minutes -->
<span>${600 | duration(m)}</span>
<!-- renders -->
<span>10 hours</span>

translate(variables?): translates given string. Optionally accepts the variables as JSON string.

<!-- Suppose we have translation defined as { "custom": { "Temperature": "Temperature EN" } } -->
<span>${'custom.Temperature' | translate}</span>
<!-- renders -->
<span>Temperature EN</span>

<!-- Suppose we have translation with dynamic variable defined as { "custom": { "Temperature value": "Temperature is " } } -->
<span>${'custom.Temperature value' | translate('{"value": 30 }')}</span>
<!-- renders -->
<span>Temperature is 30</span>

split(separator?): splits the string by the given separator and returns an array

<!-- Splits the string by the given separator -->
<span>${'1,2,3' | split(',')}</span>
<!-- renders -->
<span>['1', '2', '3']</span>

get(path): gets the value from the given path

<!-- Gets the value from the given path -->
<span>${metadata | get('name')}</span>
<!-- renders -->
<span>Device 1</span>
<!-- Gets the value with default value if path is not found -->
<span>${metadata | get('name', 'default value')}</span>
<!-- renders -->
<span>default value</span>

slice(start, end): slices the array from the start to the end index

<!-- Slices the array from the 1st to the 3rd element -->
<span>${['1', '2', '3'] | slice(0, 3)}</span>
<!-- renders -->
<span>['1', '2', '3']</span>

fade(coefficient): changes the opacity of the specified color according to the given coefficient.

<!-- Make color half transparent -->
<span style="background-color: ${'#1f8efa' | fade(0.5)}"></span>
<!-- renders -->
<span style="background-color: rgba(31, 142, 250, 0.5) "></span>

darken(coefficient): decreases the brightness of the specified color according to the given coefficient..

<!-- Darken the color by 50% -->
<span style="background-color: ${'#1f8efa' | darken(0.5)}"></span>
<!-- renders -->
<span style="background-color: rgb(15, 71, 125);"></span>

lighten(coefficient): increases the brightness of the specified color according to the given coefficient.

<!-- Lighten the color by 50% -->
<span style="background-color: ${'#1f8efa' | lighten(0.5)}"></span>
<!-- renders -->
<span style="background-color: rgb(143, 198, 252);"></span>

emphasize(coefficient): adjusts the brightness and contrast of the specified color according to the given coefficient.

<!-- Emphasize the color by 50% -->
<span style="background-color: ${'#1f8efa' | emphasize(0.5)}"></span>
<!-- renders -->
<span style="background-color: rgb(143, 198, 252);"></span>

executeCommand(endpointId, commandType, commandPayload, refreshTemplateContent, refreshDashboardContext, queryParams): this helper adds a specific attribute to an HTML element, which enables sending a command when the element is clicked.

<!-- executeCommand with dynamic endpointId and payload -->
<div ${@executeCommand(ctx.ep, 'remote_toggle', `{"lock": "${+!lock.status}"}`, true, true, '{"awaitTimeout": 5, "commandTtl": 60000}')/}>Toggle lock</div>

convertUnits(fromUnit, toUnit = 'best', precision = 1): converts the value from one unit to another. For the list of supported units check convert-units npm package.

<!-- Convert value from Celsius to Fahrenheit -->
<span>${100 | convertUnits('C', 'F')}</span>
<!-- renders -->
<span>212</span>

<!-- Convert value from Wh to kWh with precision 2 -->
<span>${1120 | convertUnits('Wh', 'kWh', 2)}</span>
<!-- renders -->
<span>1.12</span>

<!-- Convert value from ms to h with precision 2 -->
<span>${10000 | convertUnits('ms', 'h', 2)}</span>
<!-- renders -->
<span>0.03</span>

currency(currencyCode = 'USD', locale = 'en-US'): converts the value to the specified currency.

<!-- Convert value to USD with precision 2 -->
<span>${1120 | currency}</span>
<!-- renders -->
<span>$11.20</span>

<!-- Convert value to EUR with locale en-GB -->
<span>${1120 | currency('EUR')}</span>
<!-- renders -->
<span>€11.20</span>

<!-- Convert value to JPY with locale ja-JP -->
<span>${1120 | currency('JPY', 'ja-JP')}</span>
<!-- renders -->
<span>¥1,120</span>

The Raw HTML widget supports the following interfaces:

Raw HTML interfaces diagram

Also the widget supports applying UI theme colors in the widget contents. You can find the available colors listing on the Branding page. To use these colors, you need to refer to the variable uiTheme, select a color category from the branding section, write the desired category and color in the form of a camelCase. For example, if you want to set the secondary color for some text in the widget, the configuration would look like this:

<span style="color: ${uiTheme.textColors.colorSecondary};">some text</span>

Some more examples of the theme color variables:

Branding - Text colors - Color-primary-variant => ${uiTheme.textColors.colorPrimaryVariant}

Branding - Element colors - Color-surface-1 => ${uiTheme.elementColors.colorSurface1}

Time series table

The Time series table widget is used to display endpoint time series data in real time.

Time series table example

The Time series table widget supports the following interfaces:

Raw HTML interfaces diagram

Software version details

The Software version details widget is used to view and edit software version details.

Software version details

The widget supports the following interfaces:

Software version details

Map

A map widget is used to display the current location of one or multiple endpoints. It also allows tracking the endpoints movement over the specified period of time.

map-sample

It is also possible to reflect the endpoint status on the map.

map-sample

In our example configuration, the green marker indicates that the enpoint is active and the yellow one that the endpoint is stalled.

This widget may interoperate with the Map widget in terms of selection which locations to display on map. This can be enabled by selecting the Show only selected endpoints option in the Mapwidget settings.

map-sample

You can find more information here.

The Map widget supports the following interfaces:

Map interfaces diagram

Binary blobs list

The Binary blobs list widget displays a list of the blobs uploaded from your devices with binary data rest api service.

binary-blobs-sample

Endpoint orientation

The Endpoint orientation widget displays device orientation in space. You can set URL to your custom 3D model in widget configuration.

ep-orientation-sample

Luminance

The Luminance widget displays light level.

luminance-sample

Basic client credentials

The Basic client credentials widget is used to display, add and modify users credentials. It interacts with kaa rest api service.

client-creds-sample

TLS certificates

The TLS certificates widget is used to display, add and modify users credentials. It interacts with kaa rest api service.

x509-sample

Dashboard controls

The Dashboard controls widget is used to set the shared dashboard context which may be used by the widgets placed on it. The shared context includes time and date range as well as any static value. Currently, Multi series chart and Gauge support usage of the shared dashboard context.

You can configure the table widget to enable the direct link between entities in the table and their dashboards. In this case, you can click on an entity record in the table and get redirected to the entity dashboard.

The configuration flow:

  1. Create an entity dashboard, to which you would like to setup the redirects. It can be an endpoint, filter or software dashboard depending on the entity type of widget you are setuping (see Endpoint list, Filter list and Software list widgets details).

  2. Select the target dashboard in widget settings:

eplist-view

Here’s an example with the endpoint list widget.

  1. Click on a row in the list.

eplist-view

  1. Immediately get redirected to the corresponding entity dashboard.

eplist-view