Widgetkonfiguration

Eine Widget-Konfiguration besteht ebenfalls aus drei unterschiedlichen Teilen.
Durch die widgetId wird das Widget auf dem Dashboard platziert. Der Bereich itemView/chart bestimmt den Titel und Widgettyp. Im Bereich item_query/aggregation_query wird die Query definiert, die anschließend für die Anfrage der Daten an Elasticsearch gesendet wird.

Required Bundles

Um in der Konfiguration eines Dashboards auf die Standard Widgets zugreifen zu können, die Teil der Auslieferung sind, ist es notwendig, in der manifest.json Datei die Bundles einzubinden, in denen sich die Widgets befinden.

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

Wenn Custom Widgets genutzt werden sollen, so sind deren Bundles hier ebenfalls einzubinden.

Beispiel für eine Widget Konfiguration:

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
        }
      }
    }
  ]
}
Die folgenden Eigenschaften können sich in zukünftigen Produktversionen ändern.

Item query widgets

Diese Widgets stellen das Ergebnis von Anfragen zu unmodifizierter Einträgen dar. Die Ergebnisse können in einer Tabelle oder in Form eines Counter dargestellt werden.

item_query

Definiert die Query für die Anfrage an den Elasticsearch-Index.

Property Type Mandatory Default Description

refresh

Boolean | Number

no

true

Bestimmt, ob das Widget automatisch aktualisiert werden soll. Ist der Wert auf true gesetzt, so wird das Widget alle 60 Sekunden neu geladen.

Alternativ kann ein numerischer Wert in Millisekunden angegeben werden.

query

String

yes

Definiert die Elasticsearch-Query.

param1:wert1 AND param2:wert2 OR param2:wert3

Für weitere Information über die Syntax, siehe Elastic Docu .

time

JSON Object

no

Definiert ein Zeitintervall in Millisekunden für den Betrachtungszeitraum der angeforderten Daten.

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

ignorePreProcessor

Boolean

no

false

Wenn true, wird die Query von der Bearbeitung vor der Ausführung ausgeschlossen.

So kann gesteuert werden, ob beispielsweise eine auf dem Dashboard gesetzte Einschränkung der Daten für dieses Widget/diese Query greift

itemView

Definiert die Darstellung der angeforderten Daten.

Property Type Mandatory Default Description

title

String

yes

Definiert einen Titel der über dem Widget angezeigt wird

subtitle

String

no

Kann für die fachliche Beschreibung einer Abfrage eines Widgets verwendet werden.
Text wird über das Info-Icon im Widget-Header eingeblendet (nur Tabellen-Widget).

type

String

yes

Definiert die Darstellung der Daten. Mögliche Werte sind:

"Counter", "Table"

Aggregierterte Query Widgets

Diese Widgets stellen das Ergebnis einer aggregierten Anfrage dar. Die Ergebnisse können als Balken- oder Tortendiagramm dargestellt werden. Eine aggregierte Anfrage ist eine Anfrage der distinkten Werte eines bestimmten Feldes.

aggregation_query

Definiert die Query für die Anfrage an den Elasticsearch-Index.

Property Type Mandatory Default Description

refresh

Boolean | Number

no

true

Bestimmt, ob das Widget automatisch aktualisiert werden soll. Ist der Wert auf true gesetzt, so wird das Widget alle 60 Sekunden neu geladen.

Alternativ kann ein numerischer Wert in Millisekunden angegeben werden.

query

String

yes

Definiert die Elasticsearch-Query.

param1:wert1 AND param2:wert2 OR param2:wert3

Für weitere Information über die Syntax, siehe Elastic Docu

queryField

String

no

Das Indexfeld für die Aggregation.

distinctValues

Number

no

Die Anzahl der unterschiedlich dargestellten Werte. Alle anderen Werte werden unter "others" gruppiert.

order

JSON Object

no

Erlaubt eine aufsteigende oder absteigende Sortierung über ein bestimmtes Feld.

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

time

JSON Object

no

Definiert ein Zeitintervall in Millisekunden für den Betrachtungszeitraum der angeforderten Daten.

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

ignorePreProcessor

Boolean

no

false

Wenn true, wird die Query von der Bearbeitung vor der Ausführung ausgeschlossen.

So kann gesteuert werden, ob beispielsweise eine auf dem Dashboard gesetzte Einschränkung der Daten für dieses Widget/diese Query greift.

chart

Definiert die Darstellung der angeforderten Daten.

Property Type Mandatory Default Description

title

String

yes

Definiert einen Titel der über dem Widget angezeigt wird

subtitle

String

no

Kann für die fachliche Beschreibung einer Abfrage eines Widgets verwendet werden.

Text wird über das Info-Icon im Widget-Header eingeblendet (Pie Chart und Column Chart).

type

String

yes

"Pie", "Columns", "Histogram"

openTableOnStartup

Boolean

no

true

Bestimmt, ob eine Tabelle der Werte initial unter dem Charting Widget dargestellt werden soll.

fillColor

String

no

"#1abc9c"

Bestimmt die Hintergrund-Farbe einzelner Balken des Histogram Charts

borderColor

String

no

"#ffffff"

Bestimmt die Rand-Farbe einzelner Balken des Histogram Charts

Separator Widget

Das Separator Widget ist ein Widget ohne Query. Es kann genutzt werden um andere Widgets zu gruppieren oder zu trennen.

itemView

Property Type Mandatory Default Description

type

String

yes

"Separator"

title

String

no

Definiert ob ein Titel dargestellt werden soll

text

String

no

Definiert ob weiterer Text eingeblendet werden soll

showRuler

Boolean

no

false

Bestimmt, ob eine horizontale Linie eingeblendet wird.

QueryParamSelector Widget

Das QueryParamSelector Widget wird genutzt, um für ein Dashboard die abgesetzten Queries um bestimmte Parameter zu erweitern und so die dargestellten Daten einzuschränken (z.B. um die Daten eines Dashboards auf bestimmte App-Ids einzugrenzen).

selector_value_query

Über diese Query werden die möglichen Daten für eine Einschränkung auf einem Feld bestimmt,

Property Type Mandatory Default Description

distinctValues

Number

yes

100

Die Anzahl der unterschiedlichen, auswählbaren Werte für ein Feld.

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

Definiert ob ein Titel dargestellt werden soll

defaultValue

String

no

Bestimmt das Label des Wertes für "Alle Werte"

TimeRangeSelector

Das TimeRangeSelector Widget wird genutzt um für ein Dashboard die dargestellten Daten entweder auf relative Zeiträume (z.B. die letzten 7 Tage) oder auf absolute Zeiträume mit einem Start- und Enddatum (z.B. von 01.01.2015 bis 01.04.2015) einzugrenzen.

Property Type Mandatory Default Description

type

String

yes

"TimeRangeSelector"

title

String

no

Definiert ob ein Titel dargestellt werden soll

showRelative

Boolean

no

true

Zeigt oder versteckt die relative Zeitauswahl.

showAbsolute

Boolean

no

true

Zeigt oder versteckt die absolute Zeitauswahl.

preSelectedRelativeTime

String

no

"noRestriction"

Definiert welcher Wert der relativen Zeitauswahl vorausgewählt ist. Diese Eigenschaft wird ignoriert, wenn die Eigenschaft showRelative auf false gesetzt ist.

Auswählbare Werte sind: noRestriction, lastHour, last24h, last7d, last30d, today, yesterday, thisWeek, thisMonth, previousWeek, previousMonth

Heatmap Widget

Das Heatmap Widget stellt eine räumliche Karte dar, welche die angefragten Positionen als Hot Spots darstellt.

Bitte beachten Sie, dass das Widget keine Koordinatentransformation durchführt. Dies bedeutet, dass die definierte Anfrage das Raumbezugssystem der Karte vorgibt. Die karten-spezifische Konfiguration wie center und extent müssen das Raumbezugssystem berücksichtigen.
Beispielkonfiguration
{
    "widgetId": "myheatmap",
    "itemView": {
        "title": "My Heat Map",
        "subtitle": "Shows a map of all map extents",
        "type": "heatmap"
    },
    "item_query": {
        // Karten-Aktualisierung findet alle 60 Sekunden statt.
        // Wenn man eine Nummer angibt, so wird die Zeit in Millisekunden definiert.
        Der Wert "false" definiert keine Updates.
        "refresh": true,

        // Die räumliche Daten-Anfrage
        "query": "event_name:\"Map Extent\" AND event_action:Changed AND extent.lod:[6 TO *]",

        // Das Raumbezugssystem der Anfrage und Karte
        "srs": 3857,

        // Dies wird benötigt da es zusammen mit "itemCount" definiert, das die neuesten 2000 Elemente dargestellt werden
        "sort": {
            "sortField": "event_timestamp",
            "order": "desc"
        },
        // Nur 2000 Elemente sollen durch die Anfrage geliefert werden
        "itemCount": 2000
    }
}

Über den itemView Abschnitt kann auch eine andere Hintergrundkarte definiert werden:

Definiere eine Basemap
{
  "itemView": {
    ...
    "type": "heatmap",
    "map" : {
      // Der Name einer bekannten Basemap.
      // Diese Variante benötigt das Raumbezugssystem 3857 (Webmercator).
      // Siehe: https://developers.arcgis.com/javascript/3/jsapi/esri.basemaps-amd.html
      // für eine Liste von Namen.
      // Der Standard ist "dark-grey".
      "basemap": "ocean",

      // Der Wert kann auch eine URL auf einen MapServer sein
      "basemap": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Population_World/MapServer"

      // Wenn basemap als URL definiert ist und es sich um einen gekachelten Dienst handelt, so muss dies hier extra definiert werden.
      // Ansonsten wird der Dienst immer als dynamischer Kartendienst eingeladen.
      "basemapIsTiled": true
    }
  }
}

Über den itemView Abschnitt kann auch der automatische Zoom, sowie die initiale Ausdehnung verändert werden:

Spezielle Kartenkonfigurationen
{
  "itemView": {
    ...
    "type": "heatmap",

    // Deaktivierung des automatischen Zooms auf die Elemente.
    "zoomToExtent": false,

    "map" : {
      // Um die initialen Ausschnitt zu definieren kann eine Kombination aus "center" und "zoom" oder "scale" verwendet werden
      "center": {
        "x": 1100000,
        "y": 6600000
      },
      // Der Zoom-Level, dies benötigt einen gekachelten Hintergrund-Dienst
      "zoom": 5,
      // Dies definiert den Kartenmaßstab.
      // Bitte immer nur "zoom" oder "scale" verwenden!
      "scale" : 50000,

      // Alternativ zu "center" kann explizit ein Ausschnitt definiert werden
      "extent" : {
        "xmax": 1494955.3992009945,
        "xmin": 0,
        "ymax": 7252478.179392477,
        "ymin": 5685740.342497744
      }
    }
  }
}

Eventstream Widget

Das Eventstream Widget ermöglicht die Darstellung von Interaktionsabfolgen eines Nutzers in einer Art Fluss-Diagram. Es wird empfohlen, dieses Widget in Kombination mit einem oder mehreren QueryParamSelector Widgets zu verwenden, um eine sinnvolle Darstellung zu ermöglichen.

itemView

Definiert die Darstellung der angeforderten Daten.

Property Type Mandatory Default Description

type

String

yes

"Eventstream"

title

String

no

Definiert ob ein Titel dargestellt werden soll

subtitle

String

no

Kann für die fachliche Beschreibung einer Abfrage eines Widgets verwendet werden.

Text wird über das Info-Icon im Widget-Header eingeblendet

streamWidth

Number

no

1500

Definiert die Breite der Anzeigegrafik innerhalb des Widgets

streamHeight

Number

no

600

Definiert die Höhe der Anzeigegrafik innerhalb des Widgets

widgetWidth

Number

no

1530

Definiert die eigentliche Breite des Widgets

widgetHeight

Number

no

620

Definiert die eigentliche Höhe des Widgets

session_query

Definiert die Query für die Anfrage an den Elasticsearch-Index.

Property Type Mandatory Default Description

refresh

Boolean | Number

no

true

Bestimmt, ob das Widget automatisch aktualisiert werden soll. Ist der Wert auf true gesetzt, so wird das Widget alle 60 Sekunden neu geladen.

Alternativ kann ein numerischer Wert in Millisekunden angegeben werden.

query

String

yes

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

Definiert die Elasticsearch-Query.

param1:wert1 AND param2:wert2 OR param2:wert3

Für weitere Information über die Syntax, siehe Elastic Doku

returnFields

String Array

yes

["event_topic"]

Die Rückgabefelder der Abfrage

displayFields

String Array

yes

["event_name", "event_action"]

Die Anzeigefelder der Abfrage

eventMapping

Array of JSON Objects

no

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

Ordnet unbekannten Events eine "sprechende" Beschreibung zu.

user_key

String

yes

"session.raw"

Index-Feld zur Zuordnung des Nutzeridentifikators

session_key

String

yes

"session.raw"

Index-Feld zur Zuordnung des Sessionidentifikators

max_users

Number

no

100

Filter-Attribut zur Dateneinschränkung

max_usersessions

Number

no

100

Filter-Attribut zur Dateneinschränkung

max_sessionevents

Number

no

100

Filter-Attribut zur Dateneinschränkung

sort

JSON Object

no

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

Erlaubt eine aufsteigende oder absteigende Sortierung über ein bestimmtes Feld.