Cross-session analysis

Cross-session analysis in HEAT is a session template, not a query API. The template queries many sessions with a filter, processes what it finds with ordinary nodes and stores the result as a node output.

The analysis runs as a Session of its own. Its first node finds the sessions to analyse, for example every session of one trainee or every session of one template. Later nodes aggregate, compare or reshape what the query returned. The final output is the report, stored as an artefact that your software can download. The same session can also publish a Dimension that shows the results as a summary or comparative dashboard.

This is not the Reports API. The Reports API returns a high-level table of sessions and reads only what each session wrote into its own session metadata. An analysis template can read further, and it does the work inside the platform instead of inside an HTTP request.

Reports API or analysis template

Need	Use	Why
A list of sessions with a few key metrics for each one	Reports API	One CSV or XLSX download. Each originating session template writes its key metrics into the session metadata.
A comprehensive analysis of one trainee’s sessions over time	Analysis template	The work is more than one row for each session
A comparison across every session of one kind, such as one scenario or one session template	Analysis template	Needs aggregation and grouping, which the Reports API does not do
Statistics over the uploaded data itself, across sessions	Analysis template with Bulk analytics	The Reports API cannot read node outputs

Reasons to use a session template

A session template puts the analysis on the same processing architecture as every other HEAT workload.

A Runner does the work as a Task. No HTTP request waits for it, so the analysis can take minutes without a timeout.
Each run stores an immutable node output. Earlier reports stay available until session retention removes them.
A failed node can be reprocessed without repeating the nodes before it.
The analysis is a portable template. It moves between environments by export and import, like any other template.
One graph can feed a downloadable report and a dashboard from the same query.

Building blocks

These node templates run on system-utils, the platform’s built-in runner hosted inside the Core API.

Node template	Role in the analysis
session-dimension-query	Finds sessions by filter. Returns one row for each session with its session metadata and its matching dimensions.
node-output-query	Finds the stored outputs of one named node across sessions. It is the discovery step for Bulk analytics.
system-bulk-tabular-writer and system-bulk-analytics-query	Load CSV and JSON outputs into the HEAT Bulk Analytics database and run read-only SQL over them
system-arbex-js	Shapes the query result into the report artefact, a dashboard payload or both
heat-system-next-dimension	Optional. Publishes a Next dashboard from the same session.

Session filters

session-dimension-query requires at least one filter. The filters combine, so one node can select a narrow set of sessions.

Analysis	Filter
One trainee’s sessions	`userId`
One kind of session	`sessionTemplateName`, `scenarioName` or `sessionSimulationName`
One project	`projectId` or `projectName`
One dashboard	`dimensionName`
A time window	`from` and `to`, or a `dateRangeSource` that resolves the window when the node runs

The query returns the session metadata of every match. A rollup of metrics that the originating templates already wrote into session metadata needs no other data source.

userId is the numeric core user id. The query does not return names or email addresses. HEAT resolves those only when a person views a dashboard.

Graph shapes

A metadata rollup needs a query node and an Arbex node.


session-dimension-query → system-arbex-js (report artefact)

Add a sibling branch when the same results should also appear as a dashboard.


session-dimension-query → system-arbex-js (report artefact)
                        → system-arbex-js → heat-system-next-dimension (summary dashboard)

Use the Bulk analytics chain when the analysis must read the uploaded rows and not only the session metadata.


node-output-query → system-bulk-tabular-writer → system-bulk-analytics-query → system-arbex-js (report artefact)

Keep the report branch and the dashboard branch as siblings. A change to the dashboard then never alters the report. See Authoring principles.

Report artefact

The report is the node output of the last node on the report branch. An Arbex node with dataserviceOutput.enabled set to false returns any JSON shape, so the template decides the report format. See Outputs and pipelines.

Your software collects the artefact through the HEAT v2 API in three calls.

Find the session. For a scheduled analysis, GET /api/v2/dashboard/statics lists each system dashboard with the sessionId of its backing session. For a session your software created, you already hold the id.
Find the report node. GET /api/v2/session/{id}/node-instances lists the node instances of the session with their names, ids and states. Pick the report node by the name the template gave it.
Download the report. GET /api/v2/node-instance/{nodeInstanceId}/outputs/latest/data returns the newest output of that node.

Every run appends a new output. GET /api/v2/node-instance/{nodeInstanceId}/outputs lists all of them, and GET /api/v2/node-instance/outputs/{nodeOutputId}/data downloads an earlier report.

The platform can rotate the backing session of a system dashboard. Read the sessionId from the statics route on each collection instead of storing it.

Analysis on demand

An analysis does not need a schedule. Create a session from the analysis template with POST /api/v2/session, then start its query node with POST /api/v2/node-instance/{nodeInstanceId}/reprocess. The nodes below it run in turn. Poll GET /api/v2/session/{id}/node-instances until the report node is Succeeded, then download its newest output.

The reprocess route needs the Administrator or Developer role and refuses offline tokens, because it starts work on the cluster. The same call refreshes a scheduled analysis ahead of its next run.

Scheduled analysis

System dashboards (called statics in templates and presets) run a session template on a schedule. A static definition names the template and the refresh interval. The platform keeps a backing session for it and reprocesses the nodes on each refresh.

This suits a recurring analysis such as a daily or weekly summary.

Do not hard-code dates in a scheduled query. Set dateRangeSource to utcNowDay or sessionCreatedAtDay so each run resolves its own window.
Backing sessions of system dashboards are excluded from query results by default, so an analysis does not count itself.
When the template publishes a dimension, the system dashboard can appear in the HEAT dashboard navigation. Who sees it follows the minimum view privilege on the static definition.
A frequent refresh produces many outputs. Set a retentionPolicy on the template to archive old ones.

Defining a system dashboard through the v2 API is not available today. Your deployment team registers the static definition for an analysis template. Once it exists, GET /api/v2/dashboard/statics lists it for every caller its minimum view privilege allows.

Limitations

session-dimension-query returns at most 1000 sessions for each page and needs at least one filter.
node-output-query has no paging. A very large match produces a large output and a long ingest.
The Bulk analytics chain needs the HEAT Bulk Analytics database deployed in the environment.
A report is as fresh as the last run of the analysis. It is not computed at request time.
Reports carry user ids, never names or email addresses.

HEAT documentation team. Last updated 2 October 2026.

Opens your browser's print dialog. Choose "Save as PDF" as the destination.