Custom Dashboard Components¶

The UX supports custom visualizations derived from real objects in your DRP endpoint.

By default, a couple sample dashboards are bundled in community content:

Machines by Endpoint, depicting machines per endpoint a multi-site setup
License Usage, depicting percent usages of license maximums

Concepts¶

Sources¶

A visualization source describes where a visualization will get its data from, and how it will be projected for use. Sources are configured with the ux/viz-sources param.

ux/viz-sources:

# map of source name to source object
my-source:
  # (optional) array of other source names; will cause this source to run *after* any listed sources
  after:
    - another-source
  # path to request data from; supports vars from `vars`
  path: /api/v3/machines
  # (optional) jq-compatible query from result; resulting API data will be at `.result`
  project: "[.result.[].Name]"
  # (optional) map of querystring name to value; supports vars from `vars`
  query:
    Runnable: Eq($myvar)
  # (optional) map of variable name to jq-compatible query
  # these vars can be used like `$myvar`, which can be used in path/query
  vars:
    myvar: "true"

Source objects support jq-compatible querying in the project and vars fields. Using this, you can manipulate the result of the API call and refer to other sources (.sources.otherSourceName, for example).

Context¶

In situations where jq is available, the object used is the "context."

In all contexts, the .sources field is available, allowing you to refer to previously evaluated sources.
In the project context, the .result field contains the data from the successful API call.
Some visualizations support displaying a table of objects. If an object is selected, the .focused field will contain its ID. This allows you to filter your API requests by selected objects.

Panels¶

A visualization panel is a named, self-contained chart or graph that uses context to render.

ux/viz-panels:

my-panel:
  # name of the panel. shown as a title above the chart
  name: My Panel
  # (optional) text to display when hovering ? in the panel title bar
  tooltip: This is a tooltip!
  # type of the panel
  type: recharts/pie # supports recharts/pie, recharts/bar, and recharts/scatter
  # (optional) extra recharts components to attach to the chart component, map from component name to props
  components: { }
  # configuration for the panel type chosen
  data: # see below...

Pie charts (`recharts/pie`)¶

The data field for recharts/pie panels:

# direct props to pass into the Recharts PieChart, see https://recharts.org/en-US/api/PieChart
props: { }
# definitions for each ring of the pie chart. a ring is one "layer" of the pie, you probably only need one
rings:
    # the name of the ring. avoid duplicates
  - name: my-ring
    # jq-compatible query on context
    data: .sources.my-source
    # props to pass into the Recharts pie ring, see https://recharts.org/en-US/api/Pie
    props: { }
    # (optional) props for each cell, if you want to overwite some sectors, see https://recharts.org/en-US/api/Cell
    cells: [ ]

See Recharts' Pie component for details on how your data should be formatted. Most importantly, be sure to set nameKey and dataKey to the keys of your data that represent slice names and values.

Bar charts (`recharts/bar`)¶

The data field for recharts/bar panels:

# direct props to pass into the Recharts BarChart, see https://recharts.org/en-US/api/BarChart
props: { }
# jq-compatible query on context
data: .sources.my-source
# bars per X axis entry. more than one causes these bars to appear for each X axis entry, so you probably only want one
bars:
    # the name of the bar. avoid duplicates
  - name: my-bar
    # props to pass into the Recharts Bar, see https://recharts.org/en-US/api/Bar
    props: { }

See Recharts' Bar component for details on how your data should be formatted. Most importantly, be sure to set dataKey to the key of your data that represents bar values.

Scatter charts (`recharts/scatter`)¶

The data field for recharts/bar panels:

# direct props to pass into the Recharts ScatterChart, see https://recharts.org/en-US/api/ScatterChart
props: { }
# separate scatters. when multiple are provided, they are shown on top of each other
scatters:
    # the name of the scatter. avoid duplicates
  - name: my-scatter
    # jq-compatible query on context
    data: .sources.my-source
    # props to pass into the Recharts Scatter, see https://recharts.org/en-US/api/Scatter
    props: { }

See Recharts' Scatter component. You will also likely want to add the extra components XAxis and YAxis and use their dataKey and name props to define how data is scattered.

Extra Recharts components¶

With the components field on panels, you can add extra Recharts components. A list of supported components are below:

For example, to add a simple tooltip and legend, you may find the following useful:

components:
  Legend: { }
  Tooltip: { }

Viz map¶

The ux/viz-map param allows you to define visualization presets (a collection of sources and panels) to be used in certain contexts, like dashboards or on object pages. A panel cannot be shown without its associated sources, so this allows you to group many sources and many panels together.

ux/viz-map:

# map from preset name to preset
my-preset:
  panels:
    - my-panel
  sources:
    - my-source
  # (optional) object types whose tables should be shown in this visualization context
  # if on a dashboard, renders an embedded table for that object, allowing the user to select objects
  # if on an object view, enforces that the preset is only shown on objects of the specified type
  #   HINT: if you are not making use of the .focused context field, you probably do NOT need this
  objectTypes:
    - machines

Dashboards¶

If you are intending to create a dashboard with a collection of sources and panels, you will want to create a preset in ux/viz-map. Then, you can create a profile to act as your dashboard with the ux/viz-map-preset param, which is simply an array of preset names that will be shown:

- my-preset

Any profiles with ux/viz-map-preset set will show as valid dashboards in the Dashboards view. You can set your dashboard's display name using the ux/alias param.

Built-in dashboards¶

See the viz-ep-machines and viz-license-usage profiles for example usages of these params. These dashboard profiles are bundled in community content and make use of all four aforementioned params.