Here is new documentation version.
You are reading outdated documentation, which will be shutdown soon!

EP Location

Overview

A map widget that displays a current location of one or multiple endpoints. Allows viewing the history of the endpoints movement over the specified period of time.

map-sample

config:
    type: EPLocation

Widget configuration

EP Location widget has the following configuration:

config:
  type: EPLocation           # Widget type. Must always equal "epLocation" for this type of widget. REQUIRED.
  header:
    title:                   # Widget title text.
    displayTitle: true       # Indicates whether to display widget title text.
    iconPath:                # Path to icon.
  serviceIntegration:
    serviceName:             # Name of service to get location data from. REQUIRED.
    timeSeriesName:          # Time series name to get location data from. If serviceType=EPTS, then REQUIRED.
    applicationVersionName:  # Application version name to filter endpoints.
                             # Applicable only if location data is from EPR.
    lat:                     # JSON path to latitude value in data point for EPTS, or in endpoint metadata for EPR.
                             # For EPTS: one of the value field.
                             # For EPR: "metadata.field_name"
    lon:                     # JSON path to longitude value in data point for EPTS, or in endpont metadata for EPR.
                             # For EPTS: one of the value field.
                             # For EPR: "metadata.field_name"
    pollingInterval:         # Interval for polling current or historical location. REQUIRED.
    showOnlySelectedMarkers: # In combination with EP List widget with enabled endpoints select option on the same dashboard, map may show only selected in EP List endpoints.
  mapOptions:
    urlTemplate:             # This property must equal this value: "http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png". REQUIRED.
    urlTemplateSubdomains:   # Comma separated list of tiles layer provider subdomains. Will replace {s} value in the tileLayout property.
                             # Boosts tile layer loading speed. Default value is 'a'.
    copyright:               # Tile provider copyright information etc.
    zoom:                    # Default map zoom level.
    clusterization:          # Boolean that switches clusterization of markers. Is false by default.
    forceRenderOnMoving:     # Boolean that controls markers rendering when map moves. If set to false, it will boost perfomance on large amounts of data.
                             # Only works with webGL renderer. Is true by default.
    repeatWorld:             # Boolean that enables rendering of world map copies. If set to true, tiles will be loaded repeatedly outside the current world 
                             # projection. Is true by default.
    historical: false        # Indicates whether to display movement history.
    historicalPeriod:        # If historical=true, specifies for how long a period, in milliseconds,
                             # the widget will display data on start up.
                             # If not specified, will display data for the last 1 hour.
  infoWindow:                # Fields for data card on hover over historic location marker.
                             # More info available in 'Markers and location cards' section.
    title:                   # Static title for info window. If not defined, endpointId value would be used.
    titlePath:               # String, object, or array with paths and labels to parse metadata service response.
    isAlertStatusVisible:    # Boolean. Should EP Status be visible in Info window. Used in case when alerts timeseries is configured. Default `true`.
    alertStatusPath:         # Path to alert value in EPTS alert timeseries. Default, `value`.
    content:                 # Static text for info window content section.
    contentPath:             # String, object or array with paths and labels to parse metadata service response.
      - tag:                 # Static string used as field label.
        path:                # JSON path to the field value. REQUIRED.
  itemLink:                  # Redirection link for clickable location marker.
    label:                   # Label for redirection link (default is the 'EP Details' page).
    path:                    # Path to endpoint dashboard. E.g. /sensors/{sensor_id}. REQUIRED.
    parameters:              # URI parameters. REQUIRED.
      itemJsonPath:          # JSON path to endpoint description field to take parameter from. REQUIRED.
  markerStatus:              # Get ability to display different image on map marker depending on the field in response.
    serviceName:             # Service name to get status from.
    path:                    # JSON path to status from response.
    timeSeriesName:          # Time series name.
    statusTypes:             # Conditional array of statuses and markers
      - value:               # Status value
        img:                 # Icon in base64 format
  endpoints:                 # List of predefined endpoint ids. Supports '${dashboard.id}' placeholder

Location data

EP Location widget can get endpoint location from EPTS service (time series), or from EPR service (endpoint metadata).

To get location data from a time series in EPTS, specify the following in configuration:

serviceType: EPTS
serviceName: epts_instance_name
timeSeriesName: location
lon: longitude
lat: latitude
pollingInterval: 10000

To get location data from endpoint metadata in EPR, set your configuration like this:

serviceType: EPR
serviceName: epr_instance_name
lon: metadata.lo
lat: metadata.la
pollingInterval: 50000

Endpoint data is periodically retrieved with interval specified in the pollingInterval property. If this property is not specified, default interval of 7200 ms is used.

Markers and location cards

EP Location widget can show marker card when user clicks on the device’s current location marker. Data for this marker can be taken from EPR server, EPTS server (last received data point), or both.

infoWindow
  contentPath:
    - path: foo.bar             # JSON path to field value. Can be a string JSON path.

infoWindow
  contentPath:
    - path:                     # JSON path to field value. Can be an array.
      - foo
      - bar

infoWindow
  contentPath:                  # contentPath can be an object.
    path: foo.bar
    tag: foobar

infoWindow
  contentPath: foo.bar          # contentPath can be a string JSON path.

By default, the EP Location widget works in current location mode, i.e. displays current location of the endpoint(s).

User can specify a redirection link for a marker card. When user clicks on a link inside the marker card, they get redirected to an endpoint dashboard dedicated to that endpoint.

To enable this functionality, add the following section to the configuration:

itemLink:          # Redirection link for clickable location marker.
  path:            # Path to endpoint dashboard. E.g. /sensors/{sensor_id}. REQUIRED.
  parameters:      # URI parameters. REQUIRED.
    itemJsonPath:  # JSON path to endpoint description field to take parameter from. REQUIRED.

User can specify custom marker icon use property markerStatus. Icon will depending on a response status:

markerStatus:
    path: status                      # JSON path to status field value in response.
    statusTypes:                      # Array with available statuses
      - value: error                  # Status value
        img: data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNTEy # image in base64 format

Interfaces

EP Location supports a number of service interfaces to perform its functional role. The key supported interfaces are summarized in the following diagram.

EP Location interfaces diagram

For service communication, WD widgets mainly use REST APIs.