philips-labs / grafana-bpm-plugin

A Grafana plugin which allows for the visualisation of business process monitoring

Grafana Phlowchart Panel

Description: Phlowchart Grafana panel can be used to render interactive flow charts from directed graph data. Directed graphs have vertices and edges. Phlowchart supports different types of vertices. Details of the types can be found below. This panel has dependency on the Infinity data source plugin.

• Technology stack: ReactJS, NodeJS, Grafana toolkit, Yarn, ReactFlow, DagreJS.
• Key concepts Grafana does offer Node graph panel as a way to visualize a directed graph data however it is currently in Beta and also the visualization supported is very basic. There is a need to develop visualization panel that can offer rich visualization capability for directed graph. This panel attempts to do that uusing ReactFlow and DagreJS.
• Status: Initial release supporting 10 different types of vertices.

Screenshot:

See the nodes.json and edges.json in the sample_data folder for data behind the above graph.

Dependencies

• ReactJS
• NodeJS
• Grafana toolkit
• Yarn
• ReactFlow
• DagreJS

Installation

Installng plugin on Grafana Cloud / Local Grafana - https://grafana.com/docs/grafana/latest/plugins/installation/

Configuration

Build a web service with two API end points - one that provides the vertices data and another that provided the edges that link the vertices in a directed graph:

The vertices API end point should return a response similar to below:

[
   {
      "id": "1",
      "type": "twoTextFourNumber",
      "title": "Vertex title 1",
      "sub_text": "Vertex sub text 1",
      "number1": 80,
      "number2": 45,
      "number3": 39,
      "number4": 4,
      "url": "http://www.domain.com/path/subpath/1"
   },
   {
      "id": "2",
      "type": "twoTextTwoNumber",
      "title": "Vertex title 2",
      "sub_text": "Vertex sub text 2",
      "number1": 116,
      "number2": 5,
      "number3": null,
      "number4": null,
      "url": "http://www.domain.com/path/subpath/2"
   },
   {
      "id": "3",
      "type": "oneTextThreeNumber",
      "title": "Vertex title 3",
      "sub_text": null,
      "number1": 93,
      "number2": 44,
      "number3": 32,
      "number4": null,
      "url": "http://www.domain.com/path/subpath/3"
   }
]

The following table describes attributes of the vertex JSON object model:

Attribute Name	Type	Description
id	string	Unique identifier of the vertex. This identifier is used as source and destination attributes when defining edges that connect vertices of a directed graph.
type	string	This is the most important attribute of the vertex. It defines how the specific vertex is rendered. See Vertex Types Supported section below for supported values.
title	string	This attribute specifies the primary text of the vertex.
sub_text	string	This attribute specifies the secondary text of the vertex. This attribute is applicable for vertex types that have two text attributes.
number1	number	This attribute specifies the first number of the vertex. This attribute is applicable for vertex types that have one or more numbers to display.
number2	number	This attribute specifies the second number of the vertex. This attribute is applicable for vertex types that have one or more numbers to display.
number3	number	This attribute specifies the third number of the vertex. This attribute is applicable for vertex types that have one or more numbers to display.
number4	number	This attribute specifies the fourth number of the vertex. This attribute is applicable for vertex types that have one or more numbers to display.
url	string	This attribute will contain the URL where the user will be directed on click of the vertex. This provides a way for user looking at the directed graph visualization to “drill down”.

Important Note: All the 9 attributes have to be present for all vertices irrespective of the type of the vertices. Attributes that are not applicable for a vertex type should be assigned a "null" value as shown in the sample above. Even if a non-null value is assigned to such attributes, they will not be rendered as part of the vertex.

The edges API end point should return a response similar to below:

[
   {
      "id": "1-2",
      "source": "1",
      "target": "2"
   },
   {
      "id": "2-3",
      "source": "2",
      "target": "3"
   }
]

The following table describes attributes of the edge JSON object model:

Attribute Name	Type	Description
id	string	Unique identifier of the edge. This must be a unique value in the edge collection.
source	string	The "id" attribute of the vertex that is the source of the edge. The arrow connector will flow from source to target vertex.
target	string	The "id" attribute of the vertex that is the target of the edge. The arrow connector will flow from source to target vertex.

The above will be rendered as following with default configuration of the panel:

The the infinity plugin to invoke the web service and pass the data to the Phlowchart plugin. Within the infinity data source, configure the vertices API end point as the first series and configure the edges API end point as second series. The Phlowchart plugin will render the directed graph based on the attributes of the vertex.

Infinity Data Source Configuration

The above diagram shows a sample configuration of the Infinity data source. Following are points to be considered:

• The type has to be selected as JSON
• Two series have to be created - one for vertices and another for edges. The configuration of the HTTP request (HTTP method, headers, query parameters) will depend on the implementation of the web service being consumed.
• Select Table or Data Frame as the format

Vertex Types Supported

Following vertex types are supported and can be specified in the "type" attribute of the vertex JSON data:

Type Name	Description	Sample Image
twoTextFourNumber	Display two text values and four number values
twoTextThreeNumber	Display two text values and three number values
twoTextTwoNumber	Display two text values and two number values
twoTextOneNumber	Display two text values and one number value
oneTextFourNumber	Display one text values and four number values
oneTextThreeNumber	Display one text values and three number values
oneTextTwoNumber	Display one text values and two number values
oneTextOneNumber	Display one text values and one number value
oneText	Display one text value
twoText	Display two text values

Usage

Install the Infinity data source and Phlowchart plugin on Grafana. As shown above implement a web services that provides directed graph data. Use Infinity data source plugin to invoke the web service and fetch the directed graph data. Use the Phlowchart panel plugin to render the directed graph.

How to test the software

Please have a look at the following link to know how to setup the environment for development as well as usage.

Build a panel plugin tutorial

1. Install dependencies

   yarn install --pure-lockfile

2. Build plugin in development mode or run in watch mode

   yarn dev

   or

   yarn watch

3. Build plugin in production mode

   yarn build

Known issues

No open issue.

Contact / Getting help

Write an email to MAINTAINERS

License

Link to LICENSE

Credits and references

1. ReactFlow
2. DagreJS
3. Build a panel plugin tutorial
4. Grafana documentation
5. Grafana Tutorials - Grafana Tutorials are step-by-step guides that help you make the most of Grafana
6. Grafana UI Library - UI components to help you build interfaces using Grafana Design System

grafana-bpm-plugin's Issues

How to display boxes color in black

Hello,
I'm trying to use this very interesting plugin but I didn't found the way to change the boxes color.
Using the Light Theme the boxes are not visible.

Can you suggest me the way?

Thank you,
Fabrizio

Does this not work with MySQL?