Hierarchy Tree Widget

A ThingsBoard Latest values widget that renders entities as a collapsible top‑down tree (for example Customer → Sub‑customers → Assets → Devices).

The root of the tree comes from the widget’s datasource entity, so a datasource is required — bind an entity via an alias. Data keys are optional and not used by the widget; you can leave them empty.

Clicking a node highlights it and fires the On node click action, passing the clicked entity plus the full tree in the action’s additionalParams.

Setup

1. Add the widget to a dashboard.
2. In Datasource, bind one entity via an alias (this is the tree root). No data keys needed.
3. In Appearance → Settings, pick a Hierarchy mode (below) and configure it.
4. Optionally toggle Display icons and override icons per entity type.
5. Optionally add an On node click action (Actions tab) to react to node clicks.

Hierarchy modes

There are four ways to build the tree. Pick the one that matches how your data is linked.

1. Owner

Walks the owner hierarchy. Each customer expands into the entities it owns (sub‑customers, assets, devices). Only customers expand recursively; assets and devices are leaves. You choose which child types to show.

Use when your structure follows ThingsBoard ownership (customer owns its sub‑customers and entities).

Acme Corporation            (customer, from datasource)
├── North Region            (sub-customer, owned by Acme)
│   ├── Gateway A           (asset, owned by North Region)
│   └── Sensor 12           (device, owned by North Region)
└── South Region            (sub-customer, owned by Acme)
    └── Sensor 34           (device, owned by South Region)

2. Relation

Builds the tree from entity relations. You define one or more relations (type + direction); a node’s children are the union of all matching relations. Applied the same way to every node.

Use when entities are connected by relations (e.g. Contains) rather than ownership.

Building 1                  (asset, from datasource)
├── Floor 1                 (asset, Building 1 -Contains-> Floor 1)
│   └── Thermostat          (device, Floor 1 -Contains-> Thermostat)
└── Floor 2                 (asset, Building 1 -Contains-> Floor 2)
    └── Air Quality Sensor  (device, Floor 2 -Contains-> Air Quality Sensor)

3. Levels (fixed depth)

One rule per depth level — row 1 = children of the datasource entity, row 2 = their children, and so on. Each level fetches by owner or relation and shows only the selected child types. The first missing level stops that branch.

Use when the hierarchy always has the same, fixed depth in every branch. Simplest and clearest for a predictable structure.

Customer                    (from datasource)
└── level 1: owner → CUSTOMER      → Sub-customer
    └── level 2: owner → ASSET     → Asset
        └── level 3: relation → DEVICE  → Device

Example rules for the tree above:

Note: Levels assumes a fixed depth. Nodes whose type isn’t listed for their level are not shown.

4. Hybrid (rules per type)

One rule per entity type: for each type you decide how its children are fetched (by owner or by relation) and which child types to include. A type without a rule is a leaf.

Use when the same type appears at different depths (variable‑depth hierarchies), where per‑level rules don’t fit. Rules are matched by node type, so recursion adapts to any depth automatically.

Global HQ                   (customer, from datasource)
├── Europe                  (sub-customer)          ← CUSTOMER rule
│   └── Berlin Store        (sub-customer)          ← CUSTOMER rule
│       └── POS Terminal    (device, depth 3)       ← via CUSTOMER rule's children
└── USA                     (sub-customer)          ← CUSTOMER rule
    └── POS Terminal        (device, depth 2)       ← device appears at a different depth

Example rules for the tree above:

CUSTOMER fetches its sub‑customers and its devices, at any depth — so a device shows up under whichever customer owns it, regardless of how deep that customer sits.

Owner vs Levels vs Hybrid, in one line:

• Owner — quick “everything under this customer”.
• Levels — fixed, predictable depth; a rule per level.
• Hybrid — same type at varying depths; a rule per type.

Node labels

• Customers are labeled by their title.
• Other entities show their label when set, otherwise their name.

Icons

Icons are shown per entity type (Material icon names). Toggle Display icons on/off. When on, you can override the icon for specific entity types under Custom icons.

On node click action

Add an action with source On node click (Actions tab). On click, the widget passes:

• entityId / entityName — the clicked entity;
• additionalParams.entity — the full clicked node (with its children, if any);
• additionalParams.tree — the entire tree (array of roots with nested children).

Notes

• A datasource is required; data keys are optional and ignored.
• Owner mode uses ThingsBoard PE owner/entity‑group APIs.
• The tree is built eagerly and expanded by default; recursion is capped for safety and protected against relation cycles.