How HEAT works
HEAT turns recorded data into a dashboard through a graph of processing steps that you define once and run many times. This page introduces every core concept in the order you meet it. Each concept has its own page with the full detail.
The path from data to dashboard
Every HEAT dashboard is the end of the same five steps.
- A developer creates a session template inside a Project.
- Data arrives through an Ingest or the HEAT v2 API. It lands on the template’s input node and creates a Session.
- Each node in the template becomes a node instance. A Runner executes the node’s node template and stores a node output.
- A dashboard node publishes a Dimension, which holds channels grouped by Realm plus a Layout.
- The HEAT dashboard renders the layout’s widgets at
/sessions/<dimensionId>.
The rest of this page explains each term in that order.
Project
A Project is a container for session templates and sessions. Every session template and every session belongs to exactly one project.
Projects keep unrelated work apart inside one HEAT environment. A default project exists in every installation. Administrators create more projects in the Control Centre when different simulators, teams or engagements need their own space.
Session template
A session template is the blueprint. It is a directed acyclic graph (DAG) of named nodes that says how uploaded data becomes a dashboard.
A DAG is a set of steps joined by one-way links with no loops, so processing always runs forward. Each node in the template has a name that is unique in that graph. It points at one node template, carries its own configuration and lists the nodes it depends on. A template usually starts with an input node and ends with a dashboard node.
HEAT ships session templates for common cases, such as tabular CSV dashboards and capture data. You can import one as it is, copy it as a starting point or write your own.
A session template is not a session. The template is the plan and can be run any number of times. Editing a template never changes sessions that already exist.
Node template and runner
A node template is a reusable kind of processing step. A Runner is the deployed container that executes it.
Node template names are unique in one HEAT environment and are long-lived contracts. Each template has a type. Input templates receive uploaded data. Transform templates reshape data. Processing templates compute something new from it. Aggregation templates combine several upstream outputs, and dashboard nodes are aggregations.
A runner executes one or more node templates. It claims a Task for a node instance that is ready, does the work and stores the result. Most runner images are built with heat-runtime, the Python library that claims tasks and stores outputs on the runner’s behalf. HEAT ships runners such as core-utils, dashboard-tools and audio-utils, plus the platform’s built-in system-utils runner. Developers can build their own. Software that talks to HEAT from outside the cluster uses the HEAT v2 API, not a runner runtime.
A node template is not a runner. The template names what a step does. The runner is the software that does it, and a runner can be replaced without changing the templates that use it.
Session
A Session is one run of a session template over one batch of data. It is the unit that a simulator run, a training exercise or a file upload becomes inside HEAT.
When data first arrives, HEAT creates a session from the template and copies every node into it. Sessions run independently of one another, so many can process at the same time. Later uploads can extend an existing session when the ingest is configured to group them.
A session is not a dashboard. The session is the processing run. The dashboard you open is a dimension that the session published.
Node instance and node output
A node instance is one node of a session template as it exists inside one session. A node output is one stored result of processing that node instance.
Node outputs are versioned and append-only. Each time a node instance is processed, HEAT stores a new output and keeps the earlier ones. Downstream node instances read the output of their parents. When a parent gets a new output, its children become eligible to run again.
A node instance is not the node in the template. Changing an instance’s configuration affects that session only.
Dimension
A Dimension is the dashboard-facing result a session publishes. It is what you open when you click a session in the HEAT dashboard.
A dimension carries a name, a dashboard version, a layout, a data payload and the list of users who may see it. The dashboard version is Next for the current dashboard generation or Legacy for older templates that still use per-widget JSON. One session can publish several dimensions, for example one per trainee. The dashboard opens a dimension at /sessions/<dimensionId>.
A dimension is not the session itself. See Dimensions and dashboards for the full detail.
Layout
A Layout is the JSON that says how a dimension is drawn. It is rows of widgets, each bound to channels by id.
The layout is separate from the data. The same layout can be reused across sessions, and the same data can be shown by more than one layout. A Widget is one visual block in a layout row, rendered by a named dashboard component such as a timeline chart or a map.
Realms and channels
A Channel is one named dataset inside a dimension, such as a heart rate series. A Realm is a namespace that groups channels so you can compare runs or trainees side by side.
Channels live inside the data service payload, the $heat-dataservice JSON that a dashboard node publishes and the dashboard reads. Each channel has a shape such as a time series, a snapshot value or a set of events. The same channel id in two realms holds two different datasets, and a widget shows the realm the reader selects.
The plumbing
Two more concepts describe how data enters HEAT and where it is kept.
An Ingest is a managed upload URL bound to a project, a session template and an input node. Posting data to it creates a session, or extends one, without the caller knowing anything about templates. The v2 API offers the same capability for software that needs more control.
A data source is a registered storage or database location that nodes read from and write to. HEAT ships with an in-cluster object store, and administrators can register external S3-compatible storage, Azure Blob Storage or databases. Your data stays in the location you choose. See Where your data lives.
System dashboards
System dashboards, called statics in templates and presets, are platform-owned dashboards backed by hidden sessions that refresh on a schedule.
Resource Monitor is the shipped example. Its backing sessions live in a system project and do not appear in the normal session list. Who can see a system dashboard depends on the minimum view privilege set on its definition.
Where to go next
- Users: Signing in and Reading a session dashboard.
- Administrators: The Control Centre and Deployment.
- Developers: Build your first data flow, Node templates and Dashboards.