Skip to Content
This documentation is provided with the HEAT environment and is relevant for this HEAT instance only.
RunnersDashboard ToolsDashboard 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")
  • failOnRealmCountExceeded — optional boolean, default false. If true, the node fails when the normalized realm count exceeds the 50-realm soft cap; otherwise the runner only logs a warning.

Authoritative contract: See dashboard-v2 upstream contract for canonical $heat-dataservice (nested realms), channel shapes, realm semantics, and layout merging.

Key differences from dashboard (v1):

  • Payload format: Input must contain $heat-dataservice with structured channel data (canonical realms array; flat channels is accepted and normalized before storage)
  • Layout format: Uses object structure with components.rows instead of array format; stored layout includes realms and defaults for configuration when multiple realms exist
  • 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. Canonical storage uses nested realms (aligned with the Next dashboard data service). You may send legacy flat channels (and optional realm / per-channel realm); the runner normalizes to canonical form before persisting.

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

Required fields (canonical):

  • $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)
    • realms: Non-empty array; each item has name and channels (see contract)
  • dashboard_users: Array of user external GUID strings (snake_case; same role as v1 dashboard_users)

Supported channel shapes: series, timestamps, value, events, ranges — see the contract for when to use each shape (including non-time-series data via value).

For the UI-oriented reference, see 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: Prefer canonical nested realms; flat channels is still accepted and normalized. See the contract.
  • 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

  • Normalizes legacy flat channels to canonical nested realms when needed

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

  • Warns if realm count exceeds 50; optionally fails if failOnRealmCountExceeded is set

  • Merges payload realm names into layoutConfiguration.realms and sets sensible layout configuration defaults when appropriate

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

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

    1. Submits the canonical JSON output (normalized $heat-dataservice and merged layout stored on the dimension)
    2. Parses dashboard_users 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 Nodedashboard-v2 upstream contract