Configuration
The configuration of a Web Dashboard instance is fully defined in a single YAML file that contains settings for all its components including dashboards, widgets, and the service itself.
Service instance configuration
The WD loads configuration data from a file (typically backed by a Kubernetes config map). If the service is unable to retrieve the configuration data, it will not start. Refer to the configuration for details.
info:
title: <string> # Title of the company displayed in browser window.
logo: <URI> # Path to the graphic file containing a logo for the WD instance. REQUIRED.
favicon: <URI> # Path to the graphic file containing a favicon logo for the WD instance.
theme: night # Website theme. Currently, only "night" is supported.
analyticsId: <string> # Google analytics tracking ID
security: # Authentication configuration. OPTIONAL.
enabled: <boolean> # Defines whether authentication and authorization is turned on on UI.
# Possible values: true, false.
oauth2: # OAuth2 configuration.
authorizationURL: <URL> # Url for authorization request.
logoutURL: <URL> # Logout url.
tokenURL: <URL> # Url for access tokens retrievement.
accountURL: <URL> # User profile url.
baseUrl: <URL> # Identity and access management OAuth2 provider base url.
realm: <URL> # Identity and access management OAuth2 provider realm.
secureAPI: <boolean> # Enables user authorization for data retrievement.
solutionResourceId: <string> # Resource ID matching the OAuth2 provider resource for a Solution.
# Used for displaying a button for downloading configs.
# Users having scope "wd:config:read" for that resource will be able to download WD config files.
# Users having scope "wd:config:update" for that resource will be able to publish WD config changes to other users.
initialLoginPage: # Defines whether to show Kaa login page initially.
show: <boolean> # If set to `true` the Kaa login page will be output. OPTIONAL. Default — `true`.
logo: <URI> # Path to logo image. OPTIONAL. Default — KaaIoT logo shown.
header: <string> # Header of the login window.
subheader: <string> # Subheader. OPTIONAL.
copyright: <string> # Copyright section content. OPTIONAL.
terms: # Array of terms (e.g. terms of use). OPTIONAL.
- name: <string> # Name of the term.
link: <URL> # Link to the term.
style: # Style overrides. OPTIONAL.
backgroundColor: <CSS color> # Color of the body background. OPTIONAL.
backgroundImage: <URI> # Background image. OPTIONAL.
modalBackgroundColor: <CSS color> # Background color of modal window. OPTIONAL.
textColor: <CSS color> # Text content color. OPTIONAL.
buttonBackground: <CSS color> # Background settings of the `Log in` button. OPTIONAL.
buttonLabelColor: <CSS color> # Color of the label of the `Log in` button. OPTIONAL.
dashboards: # Dashboards section. List of dashboards. At least one dashboard must be defined in WD instance. REQUIRED.
- <dashboard config>
To run a WD instance correctly, you must define at least one dashboard in the configuration file. Below is an example of a WD instance configuration file.
info:
title: My solutions
logo:
main:
secondary:
theme: night
dashboards:
- note: "Welcome dashboard"
path: /
isTopLevel: false
dashboardResourceId: dashboard-home
widgets:
- config:
type: rawHTML
content: "<div style='font-size: 18px; color: rgb(250,174,66); padding-bottom: 19px;'>Welcome to Kaa Web Dashboard!</div><div style='color: rgb(166,166,166);'>Here you can set up custom dashboards.</div>"
The result of the configuration looks this way:
Dashboards
The dashboard is one of the basic components of a WD service instance—it’s a web page that contains widgets. Dashboards can be generic and entity-related (endpoint, software, filter, etc.).
Generic dashboards can be listed in the sidebar if isTopLevel specified as true, users can navigate to them by clicking the corresponding sidebar item or by link.
Entity-related dashboards are assigned to the individual entity and are reachable by link or from within the generic dashboard using one of these widgets:
Endpoints:
Filters:
Software:
Dashboard configuration
You can configure the appearance of dashboards. For example, you can change the set of widgets or add a custom icon that will be displayed next to the dashboard title in the sidebar and on the dashboard page. Also, you can change the dashboard header layout, its content and many other. For the details consult the dashboard configuration options below:
dashboardResourceId: <string> # Resource ID matching the Keycloak resource scopes. For root dashboard ('/') default value is 'dashboard-home'.
individualAccessCheck: <boolean> # Indicates whether to check access rights to each instance of current dashboard individually according to resource scopes.
# Applied for non-top level dashboards only.
title: # Dashboard title displayed on the dashboard page. Title can be set up as a string or as an object. REQUIRED.
serviceName: <string> # Name of the service instance that WD will request metadata from, e.g. "epr".
type: <string> # Type of the entity to get metadata for, e.g. 'endpoints' or 'filters'. Default is 'endpoints'.
applicationName: <string> # Application name.
text: <string> # Title template containing text variables. The variables will be assigned by mapping values from the metadata response, e.g. "Thermostat ${serial} at ${location}".
values:
-
name: <string> # Name of the text variable used in the title template, e.g "serial".
path: <string> # Path to the value from the metadata response, e.g. "data.serial".
displayTitle: <boolean> # Indicates whether to display the title at the top of the dashboard.
description: <string> # Dashboard description displayed below the title.
serviceName: <string> # Service name of metadata request, e.g. "epr".
text: <string> # Template of the title where parts will be resolved by mapping values from metadata response, e.g. "Thermostat ${serial} at ${location}".
values:
-
name: <string> # Name of the template part, e.g "serial".
path: <string> # Path to the value from the service metadata response, e.g. "data.serial".
header: # May contain custom HTML for dashboard header block. If defined, it will override the default header/description layout. OPTIONAL
serviceName: <string> # Service name of metadata request, e.g. "epr".
text: <string> # Template of the title where parts will be resolved by mapping values from metadata response, e.g. "Thermostat ${serial} at ${location}".
values:
-
name: <string> # Name of the template's part, e.g "state".
path: <string> # Path to the value from service's metadata response, e.g. "data.state".
icons:
- icon: <file path> # Show icons depending on data value.
condition: <string> # Condition for icon output, e.g. "false".
displayDescription: <boolean> # Show/hide description.
isTopLevel: <boolean> # Indicates whether the dashboard should be listed in the dashboard sidebar. Dashboard sidebar only displays the dashboards that have the property `isTopLevel=true` and sorts them in tghe same order they are defined in the configuration file. REQUIRED.
sidebarTitle: <string> # Title for the sidebar link of the dashboard. If not defined, 'title' is used.
path: <URL> # Relative path to the dashboard in URL. E.g. "/devices", or "/sensor/:id". REQUIRED.
icons: # List of icons used for the dashboard. OPTIONAL. When not defined, default icons will be used.
default: <URI> # Absolute path from the root of the "static/" directory to the graphic file used as a dashboard icon, e.g. 'icons/default.svg'. OPTIONAL.
selected: <URI> # Absolute path from the root of the "static/" directory to the graphic file used as dashboard icon when the dashboard is selected. OPTIONAL.
hover: <URI> # Absolute path from the root of the "static/" directory to the graphic file used as dashboard icon when user hovers over the dashboard on the sidebar.
widgets: # A list of widget configurations. REQUIRED.
- <widget config>
Static assets customization
You can add other assets to your dashboards. To do this:
- Mount custom files into the
static/directory located in the root of the WD project inside the Docker container. - Specify the dashboard custom icons in the dashboard configuration (see the
iconsproperty in the code snippet above).
Visual layout
Dashboard renders all its widgets row by row on the webpage. For each widget, a relative width is specified in percent of the dashboard width. Widgets whose widths total to less than 100% will be displayed in one row. The row height will correspond to the highest widget in that row.
Announcement banner
Announcement banner configuration has the following structure:
announcementBanner:
content: <string> '
<div style="width: 100%">
<span style="font-family: Lato;
font-weight: bold;
font-size: 18px;"
>
This is an axample of announcement your users may receive.
</span>
<a href=""
style="margin-left: 15px;
font-family: Lato;
font-size: 16px;
font-weight: bold;
letter-spacing: normal;
color: #faae43;"
>
Link to the detailed information.
</a>
</div>'
height: <number> 40 # Default value of banner height is 40px(only pixels). OPTIONAL.
backgroundColor: <CSS color> '#262728' # Default value of banner background color is #262728. OPTIONAL.
This is how a banner with the stated above configuration will look like:
Templating within the configuration
Within WD configurations, there is a commonly used templating syntax with the following notation: ${variableName}.
Templating fragment from the EP List widget configuration.
columns:
- display: Location
text: '${location}'
values:
- name: location
path: metadata.location
The ${location} placeholder is replaced with value taken from metadata.location JSON Path.
