heat-dataservice-merge
The heat-dataservice-merge transform reads the latest output from each of several parents and combines their data service payloads into one $heat-dataservice document. It exists so that many small producers can each build part of a dashboard and one node can publish the whole.
The node runs on the dashboard-tools runner (container image dashboard-utils). It accepts multiple parents, needs no configuration and writes one JSON output with a $heat-dataservice object and a dashboard_users list. Realms with the same name are joined, groups are deduplicated by id, and user ids are deduplicated in first-seen order.
It is not a general JSON merge. It understands the data service envelope and nothing else. For arbitrary JSON objects use json-merge.
When to use it
Use it when several transforms each emit $heat-dataservice for the same dimension. A typical case is one entity-state-to-* node per widget, or one Arbex script per realm. Wire every producer into heat-dataservice-merge, then wire the merge node into dashboard-v2.
Each producer keeps its own configuration and its own output, so you can reprocess one branch without touching the others.
Merge rules
The node takes the first valid payload as the base and folds every later payload into it.
| Part of the payload | Rule |
|---|---|
groups | Concatenated, then deduplicated by id. The first group with a given id wins, including its name. |
realms | Joined by name. A realm that appears in several payloads gets the union of their channels, in parent order. |
channels within one realm | Appended. Two channels with the same id in the same realm fail the node. |
dashboard_users | Concatenated and deduplicated, first occurrence kept. |
Other keys under $heat-dataservice | Taken from the first valid payload. Later payloads do not override them. |
A parent output is skipped, not failed, when it is empty, is not valid JSON or has no $heat-dataservice object. The node fails when no parent supplies a valid payload at all.
Duplicate channel ids
A channel id must be unique within its realm, because widgets bind to channels by id. When two parents emit the same channel id into the same realm the node fails with a message naming the realm and the id.
Fix this at the producers. Give each producer a distinct channelId (most entity-state-to-* templates expose one in configuration), or place the producers in different realms.
Configuration
The manifest declares an empty configuration schema. The node accepts no properties and rejects any that are supplied.
Output
One JSON document with the shape below. The inner object is a normal data service payload that dashboard-v2 accepts without change.
{
"$heat-dataservice": {
"version": "1.0",
"groups": [{ "id": "g-map", "name": "Map" }, { "id": "g-chart", "name": "Chart" }],
"realms": [
{ "name": "overview", "channels": [{ "id": "mapdisplay-overview", "name": "mapdisplay-overview", "groupId": "g-map", "shape": "mapdisplay", "data": {} }] },
{ "name": "maritime", "channels": [{ "id": "depth", "name": "depth", "groupId": "g-chart", "shape": "value", "data": {} }] }
]
},
"dashboard_users": ["user-1", "user-2"]
}Compared with json-merge
json-merge on core-utils merges any JSON objects key by key and has no idea what a realm is. Two $heat-dataservice payloads passed through it would collide on the realms array rather than join by name. heat-dataservice-merge reads the envelope structurally, so it is the right choice whenever the inputs are data service payloads. Use json-merge for everything else.