The asset tree says what is inside what. Relations say more: which controller manages a pump, which pump feeds a tank, which camera watches a door. A relation links two ends, each an asset or a device, with a type and a direction.
Relation types
| Type | Read as | Example |
|---|---|---|
| Contains | from an asset to a device | Room 1 contains Sensor 4. This is the device’s placement. |
| Manages | A manages B | A controller manages a pump |
| Feeds | A feeds B | Pump 2 feeds Tank 1; a UPS feeds a site |
| Monitors | A monitors B | A camera monitors a door |
| Your own | as you define it | BACKS_UP, SERVES, METERS |
Your own types have 1 to 32 characters: a letter first, then letters, digits and _. They are stored in capitals.
Rules:
- A relation goes in one direction: from one end to the other. “Pump 2 feeds Tank 1” is not the same as “Tank 1 feeds Pump 2”.
- The two ends must differ: “A relation needs two different ends.”
- The same relation (same ends, same type) exists only once: “This relation already exists.”
- Contains is only from an asset to a device, and that is the device’s placement: one per device. Set it with the placement, not as a relation. See Placing devices.
- An asset inside another asset is never a relation: move the asset instead (“An asset inside another asset is set by moving it, not by a CONTAINS relation.”).
- A relation can carry up to 20 keys (4 KiB) of extra information, for example a pipe size.
See relations
Open an asset on Sites & Assets. The drawer’s Relations section lists the relations to and from the asset:
| Column | Shows |
|---|---|
| Relation | The type |
| From | The first end, Asset or Device, with its name |
| To | The other end |
Use Search relations to find one, and Remove relation to delete it (you need Manage relations and device placement). “No relations.” means there are none.
Create relations
Relations other than placements are created through the API:
POST /tenant/<tenantId>/api/iot/relations
{ "fromType": "DEVICE", "fromId": "<pump id>", "toType": "DEVICE", "toId": "<tank id>", "type": "FEEDS" }Ends are ASSET or DEVICE. List them with GET /api/iot/relations?entityType=DEVICE&entityId=<id> (both directions) and delete them with DELETE /api/iot/relations/<relationId>. See Sites and assets API. Some ready solutions create their relations when you install them, for example a UPS that feeds a remote site.
Deleting an asset ends its relations. A device is different: a device that is placed or has any relation cannot be deleted (“The device is still in use by 1 asset placement or relation (iot_asset).”). Remove its placement and relations first.
Use relations in boards
A dashboard parameter can choose its entities Related to another parameter or entity: for example “the devices a controller manages”, or “every device under this site” through Contains. You choose the relation type, the direction and how many levels to follow (1 to 10). See Data sources and parameters.
The Sites template uses this to offer the devices of a site in its Device picker: it follows Contains from the site down, up to 10 levels.
Use relations in flows
The Related data block adds data of related assets and devices to a message:
| Setting | Meaning |
|---|---|
| direction | from the message’s device (what it manages, its children) or to it (its parents, who manages it) |
| relation types | default Contains; any type, or none for any |
| depth | 1 to 8 levels |
| entity kind, kinds, profiles | keep only assets, only devices, assets of some kinds, devices of some profiles |
| data | attributes, latest values (devices) or fields (name, kind, code, …) |
In flows, the asset tree counts as Contains relations from each parent to its children, and a placement is Contains from the asset to the device. So to, Contains, 3 levels, last level only, kind SITE finds a device’s site three levels up. See IoT data blocks.
Examples
| Goal | Relations |
|---|---|
| Show the pumps of a tank on the tank’s page | Pump Feeds Tank; a parameter “related to the tank, direction to, type Feeds” |
| Add the site’s tariff to every meter reading | Meters placed under the site; site attribute tariff; Related data to the site |
| Know which camera watches a door sensor | Camera Monitors door sensor |
| A controller with its sensors | Controller Manages each sensor |