Widget configuration

A widget configuration consist of three parts.
The widgetId through which the widget can be placed on a dashboard, the itemView/chart that defines a title and a type. The item_query/aggregation_query part defines the query that is sent to elastic in order to fetch the data.

Required Bundles

To use the default widgets that are part of the delivery it is necessary to require the corresponding bundles in the manifest.json file

manifest.json
"Require-Bundle": [
    {
        "name":"usagelog_management_widgets"
    }
]

If custom widgets should be available, its bundles need to be added here, too.

Example of a Widget Configuration:

manifest.json (excerpt)
"config": {
  "dashboards": [
    {
      ...
    }
  ],
  "widgets": [
    {
      "widgetId": "myAppStartsWidget",
      "itemView": {
        "title": "App starts in last hour",
        "type": "Counter"
      },
      "item_query": {
        "refresh": true,
        "query": "event_name:App AND event_action:Started AND app_id:analyticssampleapp",
        "time": {
          "rangetype": "relative",
          "relative": 60
        }
      }
    }
  ]
}
The following property names may change during future releases.

Item query widgets

These widgets display the results of a simple item query which are unmodified. The results may be displayed in a data table or a counter.

item_query

Defines the query that is sent against the elastic search index.

Property Type Mandatory Default Description

refresh

Boolean | Number

no

true

Whether to refresh the widget automatically or not. If set to true, the widget refreshes every 60 seconds.

If set to a number it will refresh accordingly (Number in milliseconds).

query

String

yes

Defines the elastic search query.

param1:wert1 AND param2:wert2 OR param2:wert3`

For further info on syntax refer to Elastic docs .

time

JSON Object

no

Defines a timerange in milliseconds about which data should be respected in the query.

"time": {
    "rangetype": "relative",
    "relative": 10080
}

ignorePreProcessor

Boolean

no

false

If true, the query will not be modified before execution.

In this way it is possible to control, if data restrictions on a dashboard should be applied to these widget/query

itemView

Defines how the query results are displayed.

Property Type Mandatory Default Description

title

String

yes

Defines a title that is displayed above the widget

subtitle

String

no

Displays the functional description of the query of this widget.

Info will be displayed when clicking the info icon in widget header (only table).

type

String

yes

Defines how the data are displayed. Possible values are:

 "Counter", "Table"

Aggregierterte Query Widgets

These widgets display the results of an aggregated item query. The results may be displayed in a pie or column chart. An aggregated query is a query over distinct values of a certain index field.

aggregation_query

Defines the query that is sent against the elastic search index.

Property Type Mandatory Default Description

refresh

Boolean | Number

no

true

Whether to refresh the widget automatically or not. If set to true, the widget refreshes every 60 seconds.

If set to a number it will refresh accordingly (Number in milliseconds).

query

String

yes

Defines the elastic search query.

param1:wert1 AND param2:wert2 OR param2:wert3`

For further info on syntax refer to Elastic docs

queryField

String

no

The index field to aggregate over.

distinctValues

Number

no

How many different values should be displayed separately. All other values will be grouped to "others".

order

JSON Object

no

To allow sorting ascending or descending over a specific index field.

"order": {
 "fieldToSortOver": "desc"
}

time

JSON Object

no

Defines a timerange in milliseconds about which data should be respected in the query.

 "time": {
 "rangetype": "relative",
 "relative": 10080
 }

ignorePreProcessor

Boolean

no

false

If true, the query will not be modified before execution. In this way it is possible to control, if data restrictions on a dashboard should be applied to these widget/query

chart

Defines how the query results are displayed.

Property Type Mandatory Default Description

title

String

yes

Defines a title that is displayed above the widget.

subtitle

String

no

Displays the functional description of the query of this widget.

Info will be displayed when clicking the info icon in widget header (pie and column chart).

type

String

yes

"Pie", "Columns", "Histogram"

openTableOnStartup

Boolean

no

true

Whether to show or not to show the table below the Charting widget.

fillColor

String

no

"#1abc9c"

Defines the background color for histogram charts.

borderColor

String

no

"#ffffff"

Defines the border color for bars in histogram charts.

Separator Widget

The separator widget is a widget without a query. It can be used to group or separate widgets.

itemView

Property Type Mandatory Default Description

type

String

yes

"Separator"

title

String

no

Defines if a title is displayed.

text

String

no

Defines if a text is displayed.

showRuler

Boolean

no

false

Whether to show or not to show a horizontal line.

QueryParamSelector Widget

The QueryParamSelector Widget is used to add specific parameters to all queries on the active dashboard. It may be used to restrict the displayed data to match specific fields (e.g. just display data matching an App-Id).

selector_value_query

With this query it is determined, which possible values can be applied for a field to restrict data.

Property Type Mandatory Default Description

distinctValues

Number

yes

100

Number of distinct field values to be displayed

sort

String

no

<none>

Default sorting of entries is alphabetically ascending. Add "sort":"count" to have a sorting by count descending.

queryField

String

yes

Name of the field to get aggregated values from, I.E. app_id.raw

itemView

Property Type Mandatory Default Description

type

String

yes

"QueryParamSelector"

title

String

no

Show title

defaultValue

String

no

Defines the label for "All Values"

TimeRangeSelector

The TimeRangeSelector Widget allows to define a fixed time range (e.g. the last 7 days) or to choose a custom start and end date (e.g. from 01.01.2015 to 01.04.2015) to filter the displayed data.

Property Type Mandatory Default Description

type

String

yes

"TimeRangeSelector"

title

String

no

Defines if a title is displayed.

showRelative

Boolean

no

true

Show or hide the relative time selector which allows to set a fixed time range (e.g. the last 7 days).

showAbsolute

Boolean

no

true

Show or hide the absolute time selector which allows to set a custom start and end date (e.g. from 01.01.2015 to 01.04.2015)

preSelectedRelativeTime

String

no

"noRestriction"

Defines which relative time range option is pre-selected. This property is skipped if showRelative is set to false. Applicable values are:

noRestriction, lastHour, last24h, last7d, last30d, today, yesterday, thisWeek, thisMonth, previousWeek, previousMonth

Heatmap Widget

The Heatmap widget shows a spatial map which renders the hot spots of the query items.

Note the widget is not performing any coordinate transformation. This means the query definition defines the spatial reference system of the map. All map specific configuration like center and extent must be in this spatial reference system.
Sample Configuration
{
    "widgetId": "myheatmap",
    "itemView": {
        "title": "My Heat Map",
        "subtitle": "Shows a map of all map extents",
        "type": "heatmap"
    },
    "item_query": {
        // the map updates all 60seconds, define a number in milliseconds or false for no updates
        "refresh": true,

        // the item query
        "query": "event_name:\"Map Extent\" AND event_action:Changed AND extent.lod:[6 TO *]",

        // the spatial reference system of the queried items
        "srs": 3857,

        // required so that together with itemCount the newst 2000 items are displayed
        "sort": {
            "sortField": "event_timestamp",
            "order": "desc"
        },
        // only the last 2000 items should be returned
        "itemCount": 2000
    }
}

Via the itemView section a custom basemap can be defined:

Custom basemaps
{
    "itemView": {
            ...
        "type": "heatmap",
        "map" : {
                // a name of a wellknown basemap , note these basemaps require a srs of 3857 (webmercator).
                // see: https://developers.arcgis.com/javascript/3/jsapi/esri.basemaps-amd.html
                // for a list of basemap names, the default used is "dark-grey".
                "basemap": "ocean",

                // the basemap property can also be an URL to a MapServer
                "basemap": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Population_World/MapServer"

                // if the basemap is defined as an URL and is a tiled map service then it is required to set this property to true.
                // Otherwise a tiled service will be loaded as dynamic map service
                "basemapIsTiled": true
        }
    }
}

Via the itemView section ist is possible to deactivate the automatic zooming to the calculated extend of the heat map and to define a custom initial extent:

Custom map confguration
{
    "itemView": {
            ...
        "type": "heatmap",

        // deactivate the zooming to the full extent of the heatmap features, this is enabled by default
        "zoomToExtent": false,

        "map" : {
            // use a combination of center and zoom or scale
            "center": {
                "x": 1100000,
                "y": 6600000
            },
            // define the zoom level, only valid if tiled map service
            "zoom": 5,
            // define the target map scale, use only one of zoom or scale!
           "scale" : 50000

            // or define an explicite extent
            "extent" : {
                "xmax": 1494955.3992009945,
                "xmin": 0,
                "ymax": 7252478.179392477,
                "ymin": 5685740.342497744
            }
        }
    }
}

Eventstream Widget

The Eventstream Widget provides a visualization of interaction flows of users inside different apps. It is recommended to use this widget type in combination with one ore more QueryParamSelector widgets to ensure a meaningful result.

itemView

Defines how the query results are displayed.

Property Type Mandatory Default Description

type

String

yes

"Eventstream"

title

String

no

Defines if a title should be displayed

subtitle

String

no

Displays the functional description of the query of this widget. Info will be displayed when clicking the info icon in widget header (pie and column chart).

streamWidth

Number

no

1500

Defines the width of the graphic inside the widget

streamHeight

Number

no

600

Defines the height of the graphic inside the widget

widgetWidth

Number

no

1530

Defines the width of the the widget

widgetHeight

Number

no

620

Defines the height of the graphic widget

session_query

Defines the query for the query to the Elasticsearch index.

Property Type Mandatory Default Description

refresh

Boolean | Number

no

true

Whether to refresh the widget automatically or not. If set to true, the widget refreshes every 60 seconds.

If set to a number it will refresh accordingly (Number in milliseconds).

query

String

yes

 
event_topic:\"ct/tool/CLICK*\" OR event_topic:\"ct/map/EXTENT_CHANGE\" OR event_topic:\"omnisearch/QUERY\"

Defines the elastic search query.

param1:wert1 AND param2:wert2 OR param2:wert3

For further info on syntax refer to Elastic Doku

returnFields

String Array

yes

["event_topic"]

The returned fields of the query.

displayFields

String Array

yes

["event_name", "event_action"]

The displayed fields of the query

eventMapping

Array of JSON Objects

no

 
[{
    "description": "Undo",
    "event": "ct/tool/CLICK/undoTool"
},
{
    "description": "RemoveAll",
    "event": "ct/tool/CLICK/removeAllTool"
}]

Maps unknown events to a speaking name

user_key

String

yes

"session.raw"

Index field to map a user identifikator

session_key

String

yes

"session.raw"

Index field to map an session identifikator

max_users

Number

no

100

Filter attribute

max_usersessions

Number

no

100

Filter attribute

max_sessionevents

Number

no

100

Filter attribute

sort

JSON Object

no

 
{
    "sortField": "event_timestamp",
    "order": "desc"
}

To allow sorting ascending or descending over a specific index field.