/sample-adh-grafana-nodejs

Primary LanguageTypeScriptApache License 2.0Apache-2.0

Grafana Sequential Data Store Sample

📢 Notice: This sample has been Archived. Dependencies will not be updated and pipelines will not be run. Please contact samples@osisoft.com or visit The OSIsoft Feedback Site for comments

Version: ARCHIVED

Build Status

This sample demonstrates how to build a Grafana plugin that runs queries against the Sequential Data Store of AVEVA Data Hub or Edge Data Store. The sample performs normal "Get Values" calls against a specified stream in SDS, using the time range of the Grafana dashboard. See the Grafana Documentation for more information on developing Grafana plugins.

Requirements

  • Grafana 7.0+
  • Web Browser with JavaScript enabled
  • NodeJS
  • Git
  • If using AVEVA Data Hub, register a Client Credentials Client in AVEVA Data Hub; a client secret will need to be provided to the sample plugin configuration
  • If using Edge Data Store, the browser must be running local to a running copy of Edge Data Store

Running the Sample with installed Grafana

  1. Copy this folder to your Grafana server's plugins directory, like .../grafana/data/plugins
  2. (Optional) If using other plugins, rename the folder to aveva-data-hub-sample
  3. Open a command prompt inside that folder
  4. Install dependencies, using npm ci
  5. Build the plugin, using npm run build (or npm run dev for browser debugging)
  6. Restart the Grafana server to load the new plugin
  7. Open the Grafana configuration and set the parameter allow_loading_unsigned_plugins equal to aveva-sds-sample or to the name of the folder set in step 2 (see Grafana docs)
  8. Add a new Grafana datasource using the sample (see Grafana docs)
  9. Choose whether to query against AVEVA Data Hub or Edge Data Store
  10. Enter the relevant required information; if using ADH, the client secret will be encrypted in the Grafana server and HTTP requests to ADH will be made by a server-side proxy, as described in the Grafana docs
  11. Open a new or existing Grafana dashboard, and choose the Sequential Data Store Sample as the data source
  12. Enter your Namespace (if querying ADH) and Stream, and data will populate into the dashboard from the stream for the dashboard's time range

Running the Sample with Docker

  1. Open a command prompt inside this folder
  2. Build the container using docker build -t grafana-adh .
    Note: The dockerfile being built contains an ENV statement that creates an environment variable that overrides an option in the grafana config. In this case, the allow_loading_unsigned_plugins option is being overridden to allow the unsigned plugin in this sample to be used.
  3. Run the container using docker run -d --name=grafana -p 3000:3000 grafana-adh
  4. Navigate to localhost:3000 to configure data sources and view data

Using ADH OAuth login to Grafana

A limitation of this sample is that the use of a Client Credentials Client means that anyone using the Data Source in Grafana receives the same access inside AVEVA Data Hub. Grafana supports generic OAuth login to the Grafana server, and can forward its token to the destination data source, including ADH. See here for more information on this feature of Grafana. This feature could be used to ensure individual users must log in to receive the appropriate permissions in ADH.

However, Grafana's implementation of the Authorization Code Flow does not use Proof of Key Code Exchange, or PKCE, which is an additional security layer required by ADH Authorization Code Clients. Grafana also does not support ADH Hybrid Clients as it does not support a POST back from the authentication server, nor does it support the response_type and response_mode headers required by that flow.

If you are interested in using using ADH OAuth in your Grafana server, please check and comment on this issue in the Grafana GitHub repository.

Using Community Data

  1. Add a new Grafana datasource using the sample (see Grafana docs)
  2. Choose AVEVA Data Hub
  3. Toggle the "Community Data" switch to 'true'
  4. Enter the relevant required information. You can find the Community ID in the URL of the Community Details page.

Running the Automated Tests

  1. Open a command prompt inside this folder
  2. Install dependencies, using npm ci
  3. Run the tests, using npm test

For the main ADH page ReadMe
For the main samples page ReadMe