Skip to Content
This documentation is provided with the HEAT environment and is relevant for this HEAT instance only.
RunnersDashboard Tools Runner

Dashboard Tools Runner

The Dashboard Tools Runner enables specialized node templates used for filtering and visualizing data within a session context:

1. json-filter (Transform Node)

This node uses a JMESPath  expression to extract a specific subset of JSON from its input.
Typical usage: Isolate data related to the current session, user, or any scoped variable before passing it to downstream nodes.

2. dashboard (Aggregation Node) - Legacy V1

This node aggregates the filtered input and publishes a dashboard dimension to the backend using the legacy format.

It requires the following configuration properties:

  • dataSourceName — a unique key identifying the data source
  • layoutConfiguration — an array describing the layout and components of the dashboard (legacy format)
  • dashboardName — a human-readable name for the resulting dashboard

Note: This node creates dimensions with DashboardVersion="Legacy" and is compatible with ui/legacy dashboard frontend.

3. dashboard-v2 (Aggregation Node) - Next V2

This node aggregates filtered input and publishes a dashboard dimension using the Heat Next format, suitable for the modern ui/dashboard frontend.

It requires the following configuration properties:

  • dataSourceName — a unique key identifying the data source
  • layoutConfiguration — an object with components.rows structure (v2 format, see layout schema)
  • dashboardName — a human-readable name for the resulting dashboard
  • dashboardVersion — optional, defaults to "Next" (can be "Next" or "Legacy")

Key differences from dashboard (v1):

  • Payload format: Input must contain $heat-dataservice key with structured channel data
  • Layout format: Uses object structure with components.rows instead of array format
  • Dashboard version: Creates dimensions with DashboardVersion="Next" by default
  • Frontend compatibility: Designed for ui/dashboard (not ui/legacy)

Integration in a Session Template

Here’s how you can incorporate these nodes into your session template:

  1. Insert a json-filter node immediately after your data ingestion or transformation node.

  2. Set the expression field using session-scoped variables. Example: records[?userId=='$SESSION.userId']

  3. Connect a dashboard node to consume the filtered output.

  4. Provide the dataSourceName, define the layoutConfiguration, and specify the dashboardName.

This pipeline ensures the dashboard reflects only the data relevant to the active session.

Input Payload Requirements

V1 Dashboard (dashboard node)

To assign proper access controls, the JSON passed to the dashboard node must include a dashboardUsers field — an array of GUIDs representing users who should have access:

{
  "map": {
    /* widget-specific or component-specific data */
  },
  "dashboardUsers": ["<user-guid-1>", "<user-guid-2>"]
}
  • map: Arbitrary data keyed by component or widget name. This structure must be compatible with your dashboard panel definitions.
  • dashboardUsers: An array of user GUIDs granted visibility to the resulting dashboard dimension.

Note: If dashboardUsers is omitted, the dashboard will only be visible to the runner’s internal service account.

V2 Dashboard (dashboard-v2 node)

The dashboard-v2 node requires input in the $heat-dataservice format:

{
  "$heat-dataservice": {
    "version": "1.0",
    "realm": "optional-realm-name",
    "groups": [
      {
        "id": "performance",
        "name": "Performance Metrics"
      }
    ],
    "channels": [
      {
        "id": "cognitive-load",
        "name": "Mental Workload",
        "groupId": "performance",
        "shape": "series",
        "data": [
          { "timeMs": 1000, "value": 0.75 },
          { "timeMs": 2000, "value": 0.82 }
        ]
      }
    ]
  },
  "dashboardUsers": ["<user-guid-1>", "<user-guid-2>"]
}

Required fields:

  • $heat-dataservice: Object containing structured channel data
    • version: Schema version string (e.g., “1.0”)
    • groups: Array of channel group definitions (each with id and name)
    • channels: Array of channel data (each with id, name, groupId, shape, and data)
  • dashboardUsers: Array of user GUIDs (same as v1)

Supported channel shapes:

  • series: Time-series data [{timeMs: number, value: number|string|boolean}]
  • timestamps: Point-in-time events [{timeMs: number, annotation: string}]
  • value: Static values {value: any}
  • events: Boolean state changes [{timeMs: number, occurred: boolean}]
  • ranges: Time ranges [{startTimeMs: number, endTimeMs: number, durationMs: number}]

For detailed information on the $heat-dataservice format, see the Direct Ingestion documentation.

Example: Filtering with JMESPath

Below is a basic example showing how the json-filter node processes input:

Input JSON:

[
  { "userId": "u1", "score": 10 },
  { "userId": "u2", "score": 15 },
  { "userId": "u1", "score": 20 }
]

JMESPath Expression:

[?userId=='u1']

Filtered Output:

[
  { "userId": "u1", "score": 10 },
  { "userId": "u1", "score": 20 }
]

Configuration Tips

  • Use $SESSION.* variables in JMESPath expressions for dynamic filtering.
  • Keep layout definitions minimal — specify only what is necessary (row/column span, widget types, etc.).
  • Give dashboards meaningful names to help users distinguish between multiple visualizations.
  • For v2 dashboards: Ensure your payload follows the $heat-dataservice format exactly. The processor validates the structure and will fail if requirements aren’t met.
  • For v2 dashboards: Use the v2 layout schema with components.rows structure. Component-specific requirements (e.g., TimelineChart requires timelineItems) must be satisfied.

Runtime Behavior

At runtime, the Dashboard Tools Runner performs the following:

V1 Dashboard (dashboard node)

  • Evaluates the JMESPath expression against the raw payload in the json-filter node.

  • Passes the filtered data to the dashboard node, which:

    1. Submits the full output payload
    2. Parses dashboardUsers to define access controls
    3. Publishes a new dashboard dimension with DashboardVersion="Legacy" using the provided name and layout

V2 Dashboard (dashboard-v2 node)

  • Validates that the input payload contains $heat-dataservice key

  • Validates the $heat-dataservice payload structure (version, groups, channels)

  • Validates the v2 layout configuration structure (components.rows format)

  • Passes the validated data to the dashboard-v2 node, which:

    1. Submits the full output payload
    2. Parses dashboardUsers to define access controls
    3. Publishes a new dashboard dimension with DashboardVersion="Next" using the provided name and layout

All nodes are idempotent — re-running them will append new outputs without overwriting previously published data.

Example Workflows

V1 Dashboard Workflow

V2 Dashboard Workflow

Tabular Remap NodeIntroduction