User Guide

Contents

Preparation

For information regarding the installation of the Grafana extension please refer to: Installation of Grafana

Details regarding the configuration of the extension may be found here: Configuration of Grafana

Grafana data sources

The HAKOM Time Series Grafana Extension provides the following two data source endpoints:

• Standard data source: a generic data source for all time series tasks. In panels and all queries around Grafana Metrics HAKOM time series are queried / listed
• Trees data source: a node attribute aggregation data source, specifically designed for Trees. In panels and all queries around Grafana Metrics HAKOM Trees are queried / listed. Node attributes are rolled out flat, i.e. main nodes and all subnodes are listed as single entries.

Metric Builder Mode

Note: with SimPod JSON Datasoruce version 0.6.0 a new Builder Mode has been introduced, that provides a user oriented metric query interface. In order to enable it for a given data source as default, select "Default edit mode" to "Builder" in the "Other" section of the data source configuration:

HAKOM Time Series in Grafana

Panels

In Grafana data is organized in dashboards, where each dashboard can contain one or multiple visualization panels and each panel can display several time series from the same data source. Hence to visualize time series, create a new dashboard with an empty panel at first.

Adding time series to a panel

Standard data source

To add time series to a panel follow the below steps:

1. Go to tab Query
2. Select a configured (SimPod JSON) Data source
3. Select a Metric:

   1. by either selecting the desired time series name from the Metric list 

      

      Filtering Metric list

      Note: the Metric list is limited to the first 100 time series names (this can be extended using HAKOM.Config > products > WebTSMServices > Extensions > Grafana > LimitSearchItems).

      With Grafana 9.x / SimPod JSON Datasource 0.6.0 - Builder mode, the Metric list can be refreshed and filtered using the "Metric > Metric Filter:" input box:
      1. Switch to Builder mode (if not already enabled)
      2. Select the first Metric (- Custom Query -) to display Builder UI parameter
      3. Enter some characters in the "Metric > Metric Filter:" input box and click outside the box.
      

      

      4.  The metric list is now being refreshed and filtered by the entered string:
      

      

   2. Or by selecting - Custom Query - to conduct a custom time series search using the Payload section (see Builder Parameter / Payload).

After selecting a time series its data will be immediately displayed in the graph.

Finally, further parameters can be configured using Payload parameter (either using the Builder mode or by entering the according parameters via Code mode). See also Builder Parameter / Payload.

Payload section

Note: Prior to Grafana 8.0 / SimPod 0.3.0 the field "Payload" was named Additional JSON Data.
When migrating dashboards to 8.0, the Additional JSON Data content must be transferred to the new Payload field!

Trees data source

Node aggregates in trees data source can be added in the following simple steps:

1. Select Query datasource (e.g. JSON_DOCKER_POSGRE)
2. Metric: Select the desired tree node, and set unit via Payload field if necessary.

Finally, further parameters can be configured using Payload field. See also Builder Parameter / Payload.

Builder mode vs. Code mode

With Grafana 9.x and SimPod JSON Datasource 0.6.0 a new metric Builder mode has been added. The Builder mode can be used to intuitively browse through all available HAKOM Time Series Grafana parameters. In order to enable Builder mode parameters, select Builder in the Mode section and either select - Custom Query - or any time series name in the Metric list:

Alternatively a JSON Payload can be still provided using Code mode.

Entering relative date patterns

In all date time parameters (such as audit, quotation, search effective attribute from and search effective attribute to dates) besides empty value (no date), and ISO 8601 date, a relative date time pattern can be also entered. To add relative calculated dates, use the following pattern: <ref-date><relative-date-modifiers>
<relative-date-modifiers> can be: none, one or multiple set of <operator><n><date-unit> modifiers chained together.

List of supported <operator>:

List of supported <date-unit>:

Supported <ref-date>:

Examples:

Builder parameter / Payload

The following tables show lists of parameter available in Builder mode and in Code mode Payload section. Column "Parameter name" shows the name of the parameter in Builder mode, column "Code / Legacy Code" property name used in the Payload (visible if Mode is set to Code) section. To use the parameter in the Payload, use the following pattern: "Code": "value". For example to add the parameter searchNames with a list of time series: "searchNames": "time series name 1,time series name 2".

The second code is shown in "Code / Legacy Code" column (if applicable), shows the old Payload name of the property, which is still supported, but cannot be assigned to builder parameter and should be migrated to the name shown in Code column.

Builder Control Parameter

Time Series Parameter

Column Parameter

Migration hint

Note: Column parameter were located under "columns" property in pre Builder mode releases e.g. "columns": {"allAttributes": true}. Although the "columns" property is still supported, the Builder mode cannot map it to the builder variables.  Each old property name within columns can (should) be directly referenced as columnsOldPropertyName. E.g. "columns": {"allAttributes": true} → "columnsAllAttributes": true.

To get a migrated payload, post the old payload to the baseUrl/extensions/grafana/payloadconverter endpoint. See chapter Payload Converter.

["Attribute1","Attribute2"]

Short:

Attribute1,Attribute2

TimeSeries1

true

Tree Node Parameter

Migration hint

Note: Tree node parameter were located under "treeNodeSum" property in pre Builder mode releases e.g. "treeNodeSum": {"nodeId": 1}. Although the "treeNodeSum" property is still supported, the Builder mode cannot map it to the builder variables.  Each old property name within columns can (should) be directly referenced as treeNodeSumOldPropertyName. E.g. "treeNodeSum": {"nodeId": 1} → "treeNodeSumNodeId": 1.

To get a migrated payload, post the old payload to the baseUrl/extensions/grafana/payloadconverter endpoint. See chapter Payload Converter.

MyTreeAttribute

10

["attributeName1|Value1",
"attributeName2|Value2",
"attributeName3"]

Short:

attributeName1|Value1,
attributName2|Value2,
attributeName3

true

true

true

true

25

0

Settings Parameter

Search Parameter

Are only visible in standard data source (in Trees, use the Tree Node Parameter to search for objects) if - Custom Query - is selected.

Migration hint

Note: Search parameter were located under "search" property in pre Builder mode releases e.g. "search": {"names": "Time Series"}. Although the "search" property is still supported, the Builder mode cannot map it to the builder variables.  Each old property name within columns can (should) be directly referenced as searchOldPropertyName. E.g. "search": {"names":  "Time Series"} → "searchNames": "Time Series".

Also note, that search > name property has been merged to search > names. Hence please use searchNames instead of search > name.

To get a migrated payload, post the old payload to the baseUrl/extensions/grafana/payloadconverter endpoint. See chapter Payload Converter.

["TimeSeries1",

"TimeSeries%"]

TimeSeries1,TimeSeries%

Begin

Minute

TimeSeries Description

MWh

["attributeName1|Value1",
"attributeName2|Value2",
"attributeName3"]

Short:

attributeName1|Value1,
attributName2|Value2,
attributeName3

[
{"key": "AttributName",
"operator": "!=",
"value": "Wert"},
{...}]

Short:

AttributName!=Wert,...

["Name|asc",
"Description|desc"]

Short:
Name|asc,Description|desc

10

0

true

true

["TimeSeries1",

"TimeSeries%"]

TimeSeries1,TimeSeries%

Annotation Parameter

Migration hint

Note: Annotation required the following changes in order to be cross Grafana version compatible:

• the "formula": {"formula": ..., "interval":... "intervalMultiplier":...} object has been flattened to the main annotation payload, otherwise new time series based annotation queries, where SimPod JSON Datasource calls the query (instead of the annotation) endpoint, would not work. Such annotations must be migrated.
• additionally in order to be able to configure annotations via Builder mode, an "annotation" prefix has been added to each annotation property. So that properties can be referenced by annoationOldPropertyName. E.g. "isRegion": true → "annotationIsRegion": true.

To get a migrated payload, post the old payload to the baseUrl/extensions/grafana/annotationpayloadconverter endpoint. See chapter Payload Converter.

Naming conventions for Table Format

Column names are assigned according to the following rules, but can be renamed to Table Panel:

• Time series keep their respective names (or a formulaAlias is applied as name accordingly)
• Attribute columns:
  • If only one time series was selected and its attributes are displayed: the attribute columns are given the respective attribute name
  • If attributes of several time series are displayed, the attribute columns are named according to the following pattern: Time series name:attribute name
  • If attributes are loaded from a time series specified in the background (sourceTimeseries) and noTimeseriesNameInAttributeHeader=false, the attribute columns are named according to the following pattern: sourceTimeseries:attribute name, otherwise only attribute names
• Flag columns:
  • If only one time series is displayed, the column is called Flag
  • If multiple time series are displayed, the column names will follow the following pattern: Time series name:Flag

Payload Converter

For migrating metric and annotation payloads the Grafana Extension offers two endpoints. Both endpoints will deserialize the provided payloads to the according internal objects and output all properties that were used. 

Converting time series metric payloads

To convert any time series metric payload to a Builder mode compatible payload, POST the according payload via REST request body (e.g. using Postman) to the following endpoint: baseUrl/extensions/grafana/payloadconverter

Example input:

POST /api/extensions/grafana/payloadconverter HTTP/1.1
Host: localhost:22200
Content-Type: application/json
Content-Length: 78

{"search": {"names": ["timeseries1", "timeseries2" ] }}

Example output:

{ "searchNames": "timeseries1,timeseries2"}

Disabling Array Simplification

Note: the converter stringifies and simplifies array objects out of the box.

In some cases, e.g. for MSCONS type attributes with comma in the object value, this approach leads to incorrect list splits when deserializing the stringified result to the actual array. In such cases the array stringification behaviour can be turned off by passing the query parameter "dontStringifyObjects":

Example input:

XML

POST /api/extensions/grafana/payloadconverter?dontStringifyObjects=true HTTP/1.1
Host: localhost:22200
Content-Type: application/json
Content-Length: 78

{"search": {"names": ["timeseries1", "timeseries2" ] }}

Example output:

XML

{"searchNames": ["timeseries1", "timeseries2"]}

Also note: when entering array objects in Builder mode, it will escape them to strings, this behavior is handled, since the extension supports all three variants (array object, array object in escaped string and stringified comma separated string).

Converting annotation payloads

To convert any old annotation payload (having desupported formula: {formula ...} objects) to a Builder mode compatible payload, POST the according annotation payload via REST request body (e.g. using Postman) to the following endpoint: baseUrl/extensions/grafana/annotationpayloadconverter

Example input:

POST /api/extensions/grafana/annotationpayloadconverter HTTP/1.1
Host: localhost:22200
Content-Type: application/json
Content-Length: 143

{"timeseries": "My Time Series", "formula": {"formula": "[this].Flag", "interval": "Hour" }, "isRegion": true}

Example output:

{"annotationTimeseries": "My Time Series", "annotationIsRegion": true, "annotationFormula": "[this].Flag", "annotationInterval": "Hour"}

Disabling Array Simplification

Note: the converter stringifies and simplifies array objects out of the box.

In some cases, e.g. for MSCONS type attributes with comma in the object value, this approach leads to incorrect list splits when deserializing the stringified result to the actual array. In such cases the array stringification behaviour can be turned off by passing the query parameter "dontStringifyObjects":

Payload Examples

Basic examples

Retrieve time series in unit MWh with exact audit date 2019-11-14T23:00:00Z as total aggregate

{"unit":"MWh", "audit": "2019-11-14T23:00:00Z", "exactAudit": true, "aggregation": "Sum"}

Retrieve time series in 15 minute intervals exactly at 0-15-30-45 minute grid points

{"interval":"Minute", "intervalMultiplier":15, "exactInterval":true}

Retrieve Ad Hoc formula (time series*-1) with unit "MWh" in 15 minutes interval exactly on the 0-15-30-45 minutes grid points

{"formula":"[this,0,MWh]*-1","formulaAlias":"My Inverse Time Series","interval":"Minute", "intervalMultiplier":15, "exactInterval":true}

Define time series names as a list. (For queries using timeseriesNames, you must select Metric - Custom Query -)

{"searchNames": "MyTimeSeries1,MyTimeSeries2"}

Time series from time series search with limit and attribute search. (For queries using search, you must select Metric - Custom Query -)

{"searchNames": "MyTestTimeS%", "searchType": "Begin", "searchInterval": "Hour", "searchDescription": "My time series description", "searchUnit": "MWh, 
 "searchAttributes": "MyAttribute1,MyAttribute2|Value", "searchLimit": 100, "searchOffset": 0}

Display Name usage examples

Simple query with display name

{"interval": "Hour", "displayName": "[Name]+ (+[Description]+)"}

Time series search combined with display name

{"searchNames": "Consumption%", "displayName": "[Name]+ (+[Description]+)"}

TreeNodeSum including time series combined with display name

{"displayName": "[Name]+ (+[ID]+)", "treeNodeSumName": "$rootNodes", "treeNodeSumIncludeTimeSeries": true, "treeNodeSumIncludeSum": false, "treeNodeSumExtendByAdhocFilter": "$extendByAdhocFilter", "exactInterval":"$controlExactInterval", "unit": "MWh"}

Tree Node examples

Loads a TreeNodeSum aggregate (that is, the sum of the selected TreeNode):

{"unit":"KWh", "treeNodeSumName": "MyTree"}

Loads a subnode aggregate (that is, the sum of the selected subnode ID):

{"unit":"KWh", "treeNodeSumName": "MyTree", ""treeNodeSumNodeId":10}

Loads all time series data in the selected TreeNode:

{"unit":"KWh", "treeNodeSumName": "MyTree", "treeNodeSumIndludeSum": false, "treeNodeSumIncludeTimeSeries": "true"}

Loads all time series data in the selected subnode:

{"unit":"KWh", "treeNodeSumName": "MyTree", "treeNodeSumNodeId":10, "treeNodeSumIndludeSum": false, "treeNodeSumIncludeTimeSeries": "true"}

Loads all sub-subnode totals inside the selected subnodes:

{"unit":"KWh", "treeNodeSumName": "MyTree", "treeNodeSumNodeId":10, "treeNodeSumIndludeSum": false, "treeNodeSumIncludeSubNodes": "true"}

Loads both the subnode total and all time series data and sub-subnodes inside the selected subnodes:

{"unit":"KWh", "treeNodeSumName": "MyTree", "treeNodeSumNodeId":10, "treeNodeSumIncludeTimeSeries": true, "treeNodeSumIncludeSubNodes": "true"}

Loads a TreeNodeSum aggregate, which can be switched to a subnode via Grafana AdHocFilter Variable.

{"unit":"KWh", "treeNodeSumName": "MyTree", "treeNodeSumExtendByAdhocFilter": true}

Loads 5 time series data and skips 10 time series in the selected TreeNode.

{"unit": "KWh", "treeNodeSumName": "MyTree", "treeNodeSumIndludeSum": false, "treeNodeSumIncludeTimeSeries": "true", "treeNodeSumLimitTimeSeries": 5, "treeNodeSumOffsetTimeSeries": 10}

Columns examples

Display time series with flags (as flag name)

{"columnsShowFlag": "Name"}

Display time series with all attributes and flags

{"columnsShowFlag": "Name", "columnsAllAttributes": true}

Define time series names as list, get flags as id (Result: for all listed time series the flags are displayed, in both line graphs and table panels. The flags are listed under "time series name:flag").
Note: to retrieve flags as name, use "showFlag": "name" instead. (For queries using timeseriesNames, you must select Metric - Custom Query -)

{"searchNames": "MyTimeSeries1,MyTimeSeries2", "columnsShowFlag": "id"}

Define time series names as list, retrieve only specific attributes (result: for both time series the listed attributes are loaded if any assigned)

{"searchNames": "MyTimeSeries1,MyTimeSeries2", 
 "columnsCustomList": "MyAttribute1,MyAttribute2"}

Define time series names as a list, retrieve only specific attributes from only one specific time series (result: data is loaded for both time series, attributes are loaded from the designated sourceTimeseries)

{"searchNames": "MyTimeSeries1,MyTimeSeries2",
 "columnsCustomList": "MyAttribute1,MyAttribute2", "columnsSourceTimeseries": "MyTimeSeriesWithAttribute"}

Retrieve time series from time series search with limit and attribute search and specific attributes defined (result: all time series found within the specified limit and the specified attributes, if assigned, are loaded)

{"searchNames": "MyTestTimeS%", "searchType": "Begin", "searchInterval": "Hour", "searchDescription": "My time series description", "searchUnit": "MWh, 
 "searchAttributes": "MyAttribute1,MyAttribute2|Value", "searchLimit": 100, "searchOffset": 0,
 "columnsCustomList": "MyAttribute1,MyAttribute2"}

Annotations

Time-related information with textual context, such as certain events in Grafana, can be recorded and displayed. Such events can also be retrieved from an external JSON data source via /annotations path. Individual annotations can be visualized as individual points in time or time ranges (region).

In HAKOM TSM such events can be displayed via attributes and time slices or directly via time series containing category values. 

NOTE: with Grafana 8.0 / SimPod 0.3.0 the definition of annotations are all unified using time series queries.

Annotation query

The annotation query works (since Grafana 8.0) similar to time series metric query. With the latest version you can also use the Builder mode, to configure the necessary parameters. 

Annotation from TSM attribute

Grafana - Dashboard - Settings - Annotations - New Query

1. Select a name in the Annotations dialog under Name
2. Select a JSON data source in Data source
3. Define, whether the annotation is displayed and with which display color to select
4. Under Query - Mode, select Builder (if available, otherwise add the according annotation payloads manually)
5. Select a Metric e.g. - Custom Query - (and search for a time series using Search Parameter see chapter Search Parameter), or select a time series name. The Builder parameter are displayed.
6. Turn "Show Annotation Parameter" on, to display all annotation specific parameter.
7. Finally configure the annotation parameter accordingly:
   

   

   
   
   

   1. To get an attribute:
      Set Annotation > Attribute Name and Value to the required attribute name: attribute_name
      or add the following Payload:

      XML

      {"annotationAttribute": "attribute_name"}

   2. To get an attribute and filter by a specific attribute value: 
      Set Annotation > Attribute Name and Value to the required attribute name|value pair: attribute_name|attribute_value
      or add the following Payload:

      XML

      {"annotationAttribute": "attribute_name|attribute_value"}

   3. To get an attribute displayed as region (colored time span while the attribute value is valid): 
      Set Annotation > Attribute Name and Value to the required attribute name: attribute_name
      Set Annotation > Is Region to true
      or add the following Payload:

      XML

      {"annotationIsRegion":true,"annotationAttribute":"attribute_name"}

   4. To get an attribute and filtering by a specific attribute value displayed as region (colored time span while the attribute value is valid): 
      Set Annotation > Attribute Name and Value to the required attribute name|value pair: attribute_name|attribute_value
      Set Annotation > Is Region to true
      or add the following Payload:

      XML

      {"annotationIsRegion":true,"annotationAttribute":"attribute_name|attribute_value"}

Annotation from TSM time series

Grafana - Dashboard - Settings - Annotations - New Query

1. Select a name in the Annotations dialog under Name
2. Select a JSON data source in Data source
3. Define, whether the annotation is displayed and with which display color to select
4. Under Query - Mode, select Builder (if available, otherwise add the according annotation payloads manually)
5. Select a Metric e.g. - Custom Query - (and search for a time series using Search Parameter see chapter Search Parameter), or select a time series name. The Builder parameter are displayed.
6. Turn "Show Annotation Parameter" on, to display all annotation specific parameter.
7. Finally configure the annotation parameter accordingly:
   

   

   
   
   

1. 1. To get time series values of the selected metric:
      Set Annotation > Exact Interval to true (optional)
      or add the following Payload:

      XML

      {"annotationExactInterval": true}

   2. To get time series values of the selected metric filtered by a specific value:
      Set Annotation > Exact Interval to true (optional)
      Set Annotation > Value to the required value
      or add the following Payload: 

      XML

      {"annotationValue":1, "annotationExactInterval": true}

   3. To get time series values of the selected metric displayed as region (colored time span while the time series value is unchanged): 
      Set Annotation > Exact Interval to true (optional)
      Set Annotation > Is Region to true
      or add the following Payload:

      XML

      {"annotationIsRegion":true, "annotationExactInterval": true}

   4. To get time series values of the selected metric filtered by a specific value displayed as region (coloured time span while the time series value is unchanged):
      Set Annotation > Exact Interval to true (optional)
      Set Annotation > Value to the required value
      Set Annotation > Is Region to true
      or add the following Payload:
      

      XML

      {"annotationIsRegion":true,"annotationValue":1, "annotationExactInterval": true}

   5. To get time series values of the selected metric mapped to specific text values:
      Set Annotation > Exact Interval to true (optional)
      Set Annotation > Value Map using the following pattern: <value to be mapped>|<map value>,<further value>|<further map value>... e.g.: 1|Mapping Text,2|Mapping Text 2
      or add the following Payload: 

      XML

      {"annotationValueMap": "1|Mapping Text,2|Mapping Text 2", "annotationExactInterval": true}

   6. To get ad hoc calculated time series values (based on the selected metric) mapped to specific text (e.g. to display flags as annotation colours):
      Set Annotation > Exact Interval to true (optional)
      Set Annotation > Formula to the required calculation formula, e.g. to get Flags of the selected time series: [this].Flag
      Set Annotation > Interval to the required calculation interval, e.g.: Hour
      Set Annotation > Interval Multiplier (optional)
      Set Annotation > Value Map using the following pattern: <value to be mapped>|<map value>,<further value>|<further map value>... e.g.: 1|Mapping Text,2|Mapping Text 2
      or add the following Payload: 

      XML

      {"annotationFormula": "[this].Flag", "annotationInterval": "Hour", "annotationIntervalMultiplier": 1, 
       "annotationValueMap": "9|Valid,19|Missing", "annotationExactInterval": true}

      Sample:
      

      

      
      
      

Note: the tag "annotationExactInterval": true in the above examples is used to roll out the time series values exactly on the interval defined on the time series. If this is not set, the interval is shifted by the start time given by Grafana.

Grafana Variables

Using Tags and the Ad hoc Filters Variables

To use tags and ad hoc filters in Grafana, a Grafana variable of the type "Ad hoc filters" must be defined (for each data source). This can be done in the Dashboard Settings - Variables:

An AdhocFilters control is then displayed on the dashboard, where the list of available tags and, next to the comparison operator, the list of available tag values (i.e. distinct values from all time series attribute assignments) are listed:

Note: AdhocFilters are applied to all existing data. If time series searche defined in Payload has to be extended by further attributes selected in the AdhocFilter, the searchExtendByAdhocFilter:true parameter (see chapter Search Parameter → Search > Extend Results by Ad Hoc Filter) must be configured to true.

Using Interval Variable

In Grafana, intervals can be predefined to group time periods according to the selected interval across dashboards.

To use Grafana Interval variables a Grafana variable of type "Interval" with the name "Interval" (or with the name specified in HAKOM.Config > products > WebTSMServices > Extensions > Grafana > IntervalVariableName) must be defined. If another text is to be displayed instead of "Interval", this can be achieved by using the "Label" field:

The following interval identifiers are supported:

• ms: Milliseconds - Example: 1ms
• s: seconds - Example: 1s
• m: minute - example: 15m
• h: hour - example: 1h
• d: Days - Example: 1d
• w: weeks - Example: 1w
• M: months - Example: 1M
• q: Quarters - Example: 1q
• y: years - Example: 1y

After configuring the variable, it appears on the dashboard and can be used accordingly:

Note: Interval variable overrides the interval calculated by Grafana, but it does not override intervals configured in Payload parameters, unless it is explicitely enabled via overrirdeWithGreaterInterval: true (see chapter Settings Parameter → Settings > Override with Greater Interval).

Using Custom Variable to model Interval Variable

In case there are issues with the Interval Variable behaviour (e.g. like in Grafana 7.x) alternatively a Custom Variable can be used to model an Interval Variable.

For this, a Grafana variable of type "Custom" with the name "Interval" (or with the name specified in HAKOM.Config > products > WebTSMServices > Extensions > Grafana > IntervalVariableName) must be defined. If another text is to be displayed instead of "Interval", this can be achieved with the help of the "Label" field:

In Cusom Options the same interval names as described above under Interval Variable can be used:

• ms: Milliseconds - Example: 1ms
• s: seconds - Example: 1s
• m: minute - example: 15m
• h: hour - example: 1h
• d: Days - Example: 1d
• w: weeks - Example: 1w
• M: months - Example: 1M
• q: Quarters - Example: 1q
• y: years - Example: 1y

Additionally, the option "auto" can be added (as shown above). This corresponds somewhat restricted to the "Auto Option" of the Interval variable, i.e. if this is selected, the interval suggested by Grafana depending on the selected period is used.

After configuring the variable, it appears on the dashboard and can be used accordingly:

Note: the variable overrides the interval calculated by Grafana, but it does not override intervals configured in Payload parameters, unless it is explicitely enabled via overrirdeWithGreaterInterval: true (see chapter Settings Parameter → Settings > Override with Greater Interval).

Using Text Box and Custom Variable Types in Payload

To display additional variables on the dashboard that can be mapped to Payload parameters, it is also possible to use text box or custom variable types.

In Code mode the variable name must currently be inserted between quotes as value in the according Payload parameters entry using following pattern: "$VariableName". In Builder mode, the $VariableName can be entered in any input field.

Enter variables in lists

Note: to enter Grafana Variable names in Builder modes selection lists (e.g. aggregation, unit or interval), set Param > Grafana Variable Entry Mode to true (see chapter Builder Control Parameter)

Example

To perform a time series search with name, description, etc. via Payload Search Parameter we create a variable for each time series search parameter:

• SearchName - Type: Text Box
• SearchType - Type: Text Box
• SearchInterval - Type: Text Box
• SearchDescription - Type: Text Box
• SearchUnit - Type: Text Box
• SearchAttributes - Type: Text Box
• SearchAdvancedAttributeFilter - Type: Text Box
• SearchextendByAdhocFilter - Type: Custom (without multiple selection), List: true,false
• ControlExactInterval - Type: Custom (without multiple selection), List: true,false

The variable names can be referenced in Payload between quotation marks (or in Builder parameter without quotation marks), each starting with a $ character:

{"exactInterval":"$ControlExactInterval",
 "searchNames": "$SearchName", "searchType": "$SearchType", "searchInterval": "$SearchInterval",
 "searchDescription": "$SearchDescription","searchUnit": "$SearchUnit", 
 "searchAttributes": "$SearchAttributes","searchAdvancedAttributeFilter":"$SearchAdvancedAttributeFilter",
 "searchLimit": 25,"searchOffset": 0, "searchExtendByAdhocFilter": "$SearchextendByAdhocFilter"}

The same way Tree Node Parameter (both in Standard and Trees Datasource) can be configured:

{"exactInterval":"$ControlExactInterval",
 "treeNodeSumTimeSeriesName": "$SearchName", "treeNodeSumAttributes": "$SearchAttributes", "treeNodeSumIncludeTimeSeries": true,
 "treeNodeSumLimitTimeSeries": 25, "treeNodeSumOffsetTimeSeries": 0, "treeNodeSumExtendByAdhocFilter": "$SearchextendByAdhocFilter"}

Note: Tree Node Parameter do not support the properties "interval", "description" and "unit".

Using the filters in the GUI:

• Text: can be entered as simple text (e.g.: time series name1)
• Integer: can be entered as simple text (e.g.: 25)
• Boolean: can be entered as simple text (e.g. true)
• Lists: can be entered as comma separated values (e.g. time series name1,time series name2) without space
• Attributes: see lists, attribute|value pairs can be entered using the pipe '|' separator (e.g.: attribute1|value1,attribute2|value2,attribute3)
• AdvancedAttributFilter: see lists, attribute+operator+value combinations can easily be written together (e.g. attribute1=value1,attribute2!=value3)

Using Query Variables in Payload

Using Query Variables a multi selection list for prefiltered time series names can be configured and used them in Payload (e.g. Search > Names List aka "searchNames"). If required, the list can be filtered using regex patterns.

Defining a Query Variable:

Gereral:

• Name: any name can be chosen
• Type: Query
• Label: any label can be chosen

Query Options:

• Data source: any JSON Data Source
• Refresh: either "On Dashboard Load" or "On Time Range Change" → since time series list does not change with time range change, "On Dashboard Load" shall be preferred.
• Query: Enter any part of the time series (with wildcards) to filter the list of time series. (If HAKOM.Config > products > HAKOMFramework > settings > TimeSeriesSearchExact setting is true, the search wildcard % must be inserted at the end of the time series name to use wildcard search).

• Regex: to hide the Custom Query entry ("- Custom Query -") from the time series names query, use the following Regex pattern:

  /^(?!- Custom Query -$).*$/

Selection Options:

• Multi-Value: if several time series are to be selected simultaneously: yes (Attention, multiple selection variables require with JSON Datasource 0.1.7 the HAKOM.Config entry "UseJsonDataSourceQueryFix" = true being enabled, otherwise the interface cannot process the request)
• Include All option: due to a Grafana bug in some Grafana versions (e.g. 6.4.4) Multi-Value Lists can not be emptied from the dashboard again to no selection. As such clear selection leads to the first entry being selected. If Multi-Value is activated, this option should be activated as well, so that "All" is being displayed as first item, and as such the selection jumps to "All" when the list is emptied. Note: please also read "Custom all value" option below.
• Custom all value: In combination with "Multi-Value" and "Include All", you can define what the variable should transmit when "All" is selected. By default the complete time series list available from /Search path (i.e. the first 100 entries) is selected. This makes only limited sense. We recommend to use the "Custom all value" to solve the problem described issue regarding unable to empty multi-value list selections. To do this, enter a blank entry, i.e. " " (including quotation marks) here. Because HAKOM TSM does not allow time series with only one " " space, these are automatically filtered out in the search, so that a space entry (contrary to All) does not apply any filtering. If the user wants to list all entries, an empty query can be forced to list all time series with the search parameter "executeEmptySearch".

Using Query Variable

Note: there is a limitation in the latest Grafana 9.x SimPod JSON Datasource 0.6.0 plugin, which removes Query Variables from Payload, when correctly referencing them using $QueryVariableName pattern.

To bypass this limitation, ensure that HAKOM.Config > products > WebTSMServices > Extensions > Grafana > UseJsonDataSourceVariableReplaceFix is not disabled and use "§" instead of "$" as variable name marker: §QueryVariableName.

Note: the Query Variable name marker can be configured in HAKOM.Config > products > WebTSMServices > Extensions > Grafana > QueryVariableMarker, however the value "$" should not be used, since this will cause the above mentioned issue.

The query variable is best used in "searchNames" parameter:

{"exactInterval":"$ControlExactInterval",
 "searchNames": "§Query", "searchType": "$SearchType", "searchInterval": "$SearchInterval",
 "searchDescription": "$SearchDescription","searchUnit": "$SearchUnit", 
 "searchAttributes": "$SearchAttributes","searchAdvancedAttributeFilter":"$SearchAdvancedAttributeFilter",
 "searchLimit": 25,"searchOffset": 0, "searchExtendByAdhocFilter": "$SearchextendByAdhocFilter"}

Other Grafana Panels

Configuring Geomap panel

The Geomap panel provides a simple way to visualize geographically distributed time series values on a selected map.

Modelling geo-specific data

In HAKOM Time Series Management for each location a separate time series has to be created. Each time series will contain data for its specific location. In order to configure the location of the time series, two time series attributes, "Lat" and "Lon" must be assigned, which contains the actual latitude and longitude positions of a given location. 

Loading geo-specific data into Geomap

Geomap plugin requires time series tables containing one time stamp, only one value column, and one Lon and Lat column. As such if multiple time series are added to Geomap without further configuration, Geomap will only pick up the first time series values.

To add multiple time series to Geomap, the data model of those time series must be merged into a single value stream, using Column > Merge Series for Geomap aka "columnsMerge" parameter (see Columns Parameter).

Configuration steps:

1. Create a new panel
2. Select Geomap plugin (on the right top - plugins list)
3. In Query section create a single query for all time series (preferred way).
4. Set Metric to - Custom Query -

5. Enable Show Time Series Parameters and
   Set TS > Interval
   Set TS > Interval Multiplier
   Set TS > Exact Interval parameters (if necessary)
   or add to payload the following code (replace ... with your interval):

   CODE

   {"interval": "...", "intervalMultiplier": 1, "exactInterval": true }

6. Enable Show Search Parameters and
   Set Search > Names List or any other parameter to find the according time series. E.g. Search > Attributes
   or add to payload the according code. E.g. to search for time series with Attribute "Lon" use the following:

   CODE

   {"searchAttributes": "Lon", "interval": "...", "intervalMultiplier": 1, "exactInterval": true }

7. Enable Show Columns Parameters and
   Set Columns > Merge Series for Geomap to true
   or add to payload the following code:
   

   CODE

   {"columnsMerge": true, "searchAttributes": "Lon", "interval": "...", "intervalMultiplier": 1, "exactInterval": true }

Using multiple queries

In case metrics are selected via multiple queries, each query must have the "columnsMerge" parameter.