Geomap WMS Panel Plugin

💡 This project uses semantic versioning.

About

This plugin evolved from the Orchestra Cities Map Panel-Plugins. It extends the original version by the functionality of the intergration of an OGC Web Map Service (WMS version 1.3.0) as a base map layer. Additionally the plugin ships with an interactive filter tool to query data by spatial relations. Also a minimal implementation of datalinks is provided to update dashboard variables by clicking on a map feature.

Due to Grafana Labs' plugin guidelines it was necessary to remove the Nextzen basemap layer, since it required to store the API key in the config, which should be avoided in panel plugins.

Features

• Integration of mutliple OGC WMS 1.3.0 from different endpoints as base map layer
• Opacity setting for each WMS endpoint
• Collapsable legend of used WNS layers
• Interactive spatial filter
• Minimal data links implementation

Migration from Geomap WMS Panel Plugin v1.0.1

Due to the capability of using multiple WMS endpoints as base map layer a change in the plugin configuration object was required, not being backwards compatible with the configuration object used for plugins of version 1.y.z.

Dashboards using the Geomap WMS Panel Plugin of major version 1 and using a WMS as base map layer that want to use the latest version of the plugin need to migrate their panel's JSON definition.

⚠️ The migration is only mandatory for plugins that use a WMS as a base map layer. Panels that use other base maps than the WMS base map do not require any action. ⚠️

Example of a migration

JSON definition of WMS baselayer in plugin version 1.y.z:

...
"basemap": {
      "type": "wms",
      "config": {
        "layer": [
          "g_stadtkarte_gesamt"
        ],
        "url": "https://geoportal.muenchen.de/geoserver/gsm/wms?"
      }
    },
...

Corresponding JSON definition of WMS baselayer in plugin version 2.y.z:

...
"basemap": {
      "type": "wms",
      "config": {
        "wmsBaselayer": [
          {
            "url": "https://geoportal.muenchen.de/geoserver/gsm/wms?",
            "layers": ["g_stadtkarte_gesamt"],
            "attribution": "",
            "opacity": 1,
            "showLegend": false
          }
        ]
      }
    },
...

The JSON definition of the panel might be edited directly in the Grafana GUI.

⚠️ Make sure to backup your dashboard before editing it or make use of the versioning functionality of Grafana to rollback changes if editing is gone wrong ⚠️

Using the Geomap WMS Panel Plugin

⚠️ Currently only WMS of version 1.3.0 are supported ⚠️

1. In the selection Base layer choose the type OGC Web Map Sevice
2. Click the button + Add WMS to open the WMS dialog
3. In the text field URL type in the base url of the WMS endpoint (NOTE: Only the URL of the service endpoint WITHOUT request parameters, e.g. https://geoportal.muenchen.de/geoserver/gsm/wms)
4. Choose one or multiple layers from the drop down list
5. Adjust the opacity of the WMS entry (affects all layers of the wms entry; to use the same WMS endpoint and apply different opacities to layers add multiple entries via the + Add WMS)
6. Optionally toggle the legend button to display a legend containing the icons of the selected WMS layers
7. Optionally provide an attribution for the WMS endpoint
8. To remove an entry click on the button - Remove WMS

Example 1): WMS Basemap with 3 layers

Layer names:

• g_stadtkarte_gesamt_gtay
• g_stadtspaziergang_moosach_route_a
• baustellen_2_weeks

Example 2): WMS Basemap with 3 layers (layer names have whitespaces)

Layer names:

• Blöcke
• Linie_u_Stadtplanü. bis 150k
• stehende Gewässer generalisiert

⚠️ Troubleshooting data layers when merging multiple datasource queries into one map layer

In some occasions it might be necessary to join mutliple datasource queries into one output dataset to summarize information coming from different sources in a single map layer. This can be achieved by applying transformations on the returned data frames.

This often results in data structure like the following which might be inspected in the debug view in the transformations panel missing the metadata properties like query "name" and "refId".

The above data structure is not compatible with Geomap Panel Plugin's query input which expects a data frame with metadata fields like "refId" or "meta".

A workaround to solve this problem is to use the prepare time series transformation with the setting "Wide time series" as last transformation in the processing chain.

The latter trasnformation a "meta" field to the data object and therefore can now be processed by the Geomap Panel Plugin.

Using the spatial filter tool

An additional feature of the Geomap WMS Plugin is the spatial filter tool that allows drawing a polygon on the map panel to be used as filter for a data query. The polygon is representated as Well-known-text (WKT) and stored in a dashboard variable "geomap_wms_spatial_filter_geometry".

⚠️ It is mandatory to name the dashbaord variable "geomap_wms_spatial_filter_geometry" ⚠️

⚠️ The spatial filter tool uses the geographic coordinate system urn:ogc:def:crs:OGC::CRS84 with the axis order longitude, latitude. Openlayers (dependency of the geomap plugin) uses the CRS CSR:84 as alias for EPSG:4326 (source), even if the official axis order of EPSG:4326 defines latitude, longitude. This is because the Proj4Js-Library uses the order [x=longitude,y=latitude] by default. ⚠️

To enable the spatial filter tool follow the steps below:

1. Create a dashboard variable of type "Textbox" or "Custom" (eventually set the display property to "Nothing" to hide the variable from the user) and the name "geomap_wms_spatial_filter_geometry" (the spatial filter tool will update this variable internally and as for now does not provide the functionality of setting a different variable name externally). As initial value use e.g. POLYGON((-180 -90,180 -90,180 90,-180 90,-180 -90)), to selec all, if no polygon is drawn.

1. Use the dashboard variable in a datasource query, e.g. the SensorThings API, which allows the filtering by providing a WKT in the geometry function:

/Things?$expand=Locations&$filter=substringof(name,'${tree_sensor:csv}') and st_intersects(Locations/location, geography'${geomap_wms_spatial_filter_geometry}')

1. Enable the tool in the panel editor, press save or apply and leave edit mode

1. Activate the tool in the panel

1. Draw a polygon as spatial filter geometry. To apply the geometry set the last point on the starting point. After that the panels and datasources which use the variable "geomap_wms_spatial_filter_geometry" are updated automatically. To delete the geometry click on the cross symbol.

Using data links

The Geomap WMS Panel Plugin allows the use of dataLinks to update a dashboard variable with data of the clicked feature. This enables interactions between the map panel and other panels in the dashbaord, which use the same dashboard variable in their data queries. To make use of this functionality a datalink has to be created (see the official documentation) on how to do that.

⚠️ As of now the plugin is only able to handle 1 (the first) data link ⚠️

This example demonstrates how to configure the Geomap WMS Panel Plugin to update a dashboard variable "ladestationen" with the value of the data field of name "name" by clicking on a feature on the map.

Clicking on a certain feature on the map results in both, updating the map as well as all the panels which use the dashboard variable "ladestationen" in their queries.

Before:

After:

Development

Status of the original repository

This repository refers to the following version of its original: https://github.com/orchestracities/map-panel/tree/c0d3a19ce910b9c3ab8416f5a609afb10ff8c0fe

Technical setup

• Grafana >= 10.0.2 as Docker container with bind mounts to host filesystem mounting following conatiner directory /var/lib/grafana/plugins
• node v20.3.1
• npm 10.5.0
• Linux-based OS Windows with WSL

Run the tests

Unit/integration tests

npm run test:all

E2E tests

Requires a Docker container of grafana running at localhost:3000 with default credentials (user: admin, password: admin).

npm run e2e

Building the plugin

1. Clone the repository

git clone https://github.com/felix-mu/geomap-wms-panel.git

1. Navigate in the directory geomap-wms-panel

cd ./geomap-wms-panel

1. Install the node modules

npm install

1. Run build script

npm run build

Building the plugin for development/debugging

Repeat the steps 1 to 3 from Building the plugin.

Then run:

npm run dev

Deploy the (unsigned) plugin to the docker container (for debugging)

The packed plugin (either production build or development build) is found in the output folder ./felixrelleum-geomapwms-panel. To allow grafana to load an unsigned plugin the container environment variable GF_PLUGINS_ALLOW_UNSIGNED_PLUGINS=<comma separated list of plugin-ids> must be set to "felixrelleum-geomapwms-panel". Additionally it is required to configure a bind mount of the plugins container directory to the host filesystem where the bundled Geomap WMS Panel Plugin is located.

Shortcut: Run the docker-compose.yaml with docker compose up

If the plugin was build with npm run dev the Webpack directories are loaded to the browser. This enables the use of developmer tools of the browser to set breakpoints and debug the plugin source code (it is recommended to deactivate the cache).

⚠️ Troubleshooting

After each build the Docker-Container must be restarted to reload the new version of the plugin. If the changes of the plugin are not noticed it might help to clear the browser cache and refresh the page.

Validate the plugin

npm run validate

Use automatic generation of changelog

At first bump the version of the npm package (package.json and package-lock.json):

npm --no-git-tag-version version <version>

Run the automatic changelog generation:

npm run release

Commit the changelog changes, tag the latest commit and push everything:

git add . && npm run commit

git push origin main

git tag v<version> && git push origin main v<version>

Contributing

See Contributing guide for how to contribute to the project.

Further resources

• Grafana and Docker
• Configure Grafana in Docker
• Build tools for plugins
• Create a panel plugin
• Sample plugins
• Grafana UI catalog