Authoring session templates

A session template is a JSON document that describes a directed acyclic graph (DAG) of named nodes. Each node names the node template it runs, the default configuration it runs with and the nodes it waits for.

You author a template as a file, import it into a HEAT environment and point an Ingest or an API caller at it. From then on every upload creates a Session from the template and runs the graph. The file is the whole of what you author. There is no code beside it unless a node is an Arbex script.

A session template is not a .heat manifest. A manifest registers runners and node templates as a Feature. A template uses node templates that a manifest has already registered.

The JSON shape

This is the preset system-tabular-dashboard-autodetect-next as shipped, trimmed only in the layout block.

{
  "$schema": "https://heatcommon.blob.core.windows.net/schema/session-template/v1.json",
  "TemplateVersion": "1.0.0",
  "Name": "system-tabular-dashboard-autodetect-next",
  "Description": "Upload any CSV on input-node: auto-detect time column and numeric series, build $heat-dataservice, emit suggested Next layout, and open a dashboard dimension.",
  "Configuration": {},
  "Nodes": [
    {
      "Name": "tabular-upload",
      "NodeTemplateName": "input-node",
      "DefaultConfiguration": {},
      "Parents": []
    },
    {
      "Name": "tabular-autodetect",
      "NodeTemplateName": "system-tabular-to-dataservice",
      "DefaultConfiguration": {
        "autoDetectTimeColumn": true,
        "emitSuggestedLayout": true,
        "whenNoOutputs": "complete",
        "realmPerFile": false,
        "defaultRealm": "default",
        "maxAutodetectSampleRows": 200
      },
      "Parents": ["tabular-upload"]
    },
    {
      "Name": "tabular-dashboard",
      "NodeTemplateName": "heat-system-next-dimension",
      "DefaultConfiguration": {
        "dataSourceName": "HEAT Managed Object Store",
        "dashboardName": "CSV autodetect dashboard",
        "autoCreateScenarioInstance": true,
        "scenarioName": "csv-autodetect",
        "layoutFromParentOutput": true,
        "layoutConfiguration": {
          "version": "1.0.0",
          "configuration": { "enableGlobalPlaybackControls": true, "defaultRealm": "default", "showRealmFilterDropdown": false },
          "realms": ["default"],
          "components": { "rows": [] }
        }
      },
      "Parents": ["tabular-autodetect"]
    }
  ]
}

Key casing follows the presets. Name, NodeTemplateName, DefaultConfiguration and Parents are written in PascalCase at the template level, while the keys inside DefaultConfiguration follow whatever the node template’s schema defines, which is usually camelCase.

Naming rules

Node names must be unique within one template. They are how parents are referenced, how the Control Centre labels the Nodes tab and how ingests pick an input node.

Input nodes follow a convention that tells a reader what the template expects. The convention is described on the input node page.

Name processing nodes after what they do, not after the node template. to-dataservice reads better than node-2, and publish reads better than dashboard-v2.

How a template becomes sessions

A template is a blueprint and does nothing by itself. Two things create sessions from it.

• An Ingest binds a project, a template and one input node to an upload URL. Every post creates a session, or appends to one when the ingest is configured to look sessions up.
• An API caller creates a session through the HEAT v2 API, naming the project and the template, then uploads to a node instance of that session.

When a session is created, every node in the template becomes a node instance carrying a copy of its DefaultConfiguration. When a node instance receives or produces a node output, its children become eligible to run. A Runner claims each unit of work, reads the parent outputs and stores a new output. Outputs are never overwritten, so reprocessing a node appends rather than replaces.

Templates are registered per environment, not per project. Any project can create sessions from any template. The binding to a project happens at the ingest or at session creation.

Import and export

Templates enter an environment as JSON files. HEAT applies the same rules to every import, whichever tool performs it. The full table of outcomes and validation errors is on the Control Centre Templates page. The rules that shape authoring are these.

• A new Name creates a new template.
• An existing Name is rejected unless the file carries "updateIfExists": true, and then only when the graph is unchanged. Only the description, Configuration and each node’s DefaultConfiguration may change in place.
• A graph change (a node added, removed or rewired, or a node template swapped) needs a new Name. The convention is a revision suffix, for example my-flow-r2.
• Every NodeTemplateName must be registered and its feature enabled, or the import fails with “unknown node templates”.

Sessions that already ran keep pointing at the template they were created from. That is why a graph change must never overwrite a template in place.

Shipped presets

The platform ships these templates. Some are meant to be used as they are, some are samples to copy from, and some are system pipelines that back platform dashboards and are not meant for user sessions.

System pipelines run as system dashboards (called statics in templates and presets) on a schedule. See system dashboards.

Guides

Related

• Build your first data flow
• Node template catalog
• Session template concept
• Templates in the Control Centre

HEAT documentation team. Last updated 2 October 2026.