Aliases
An alias is a reference to a single entity or group of entities used as a data source in widgets.
Aliases can be static (pointing to fixed entities) or dynamic (resolved at runtime based on entity type, relations, or dashboard state).
Creating an alias
Section titled “Creating an alias”Aliases can be created from the dashboard toolbar or directly while configuring a widget.
From the dashboard toolbar:
- Open the dashboard and switch to Edit mode.
- Click the Entity aliases icon in the upper-right corner of the toolbar.
- In the opened dialog, click Add alias.
- Enter the alias name, select a Filter type, fill in the required fields, and click Add.
- Click Save in the lower-right corner to apply.
To create a new alias while configuring a widget:
- Click the pencil icon on the widget to open its settings.
- Go to the Datasource section and select the Entity alias tab.
- Type the new alias name and click Create a new one!
- Complete the alias configuration and click Add.
- Apply and save the widget — the alias is created and assigned immediately.
Assign an alias to a widget
Section titled “Assign an alias to a widget”In the widget settings, open the Datasource section, switch to the Entity alias tab, and select an alias from the drop-down. Add the required data keys and apply.
Edit / Delete an alias
Section titled “Edit / Delete an alias”To edit an alias:
- Open the dashboard and switch to Edit mode.
- Click the Entity aliases icon in the toolbar.
- Click the pencil icon next to the alias you want to change.
- Update the configuration and click Save.
- Click Save in the lower-right corner to apply.
To delete an alias:
- Open the dashboard and switch to Edit mode.
- Click the Entity aliases icon in the toolbar.
- Click the trash icon next to the alias you want to remove and confirm.
- Click Save in the lower-right corner to apply.
Alias types
Section titled “Alias types”The following alias types are available for use in dashboard widgets.
The Resolve as multiple entities toggle (visible in the alias configuration dialog) controls whether the alias can return more than one entity. It is enabled by default for multi-entity alias types (e.g., Entity list, Entity type) and disabled for single-entity types. Widgets that display a single value (e.g., value cards) work with single-entity aliases; table and chart widgets typically use multi-entity aliases.
Report templates and subreports support all of these, plus their own [additional aliases](#report-template-aliases) specific to notification-triggered and subreport contexts.| Alias type | Description | Availability |
|---|---|---|
| Single entity | Resolves to one specific entity chosen by type and name. | All editions |
| Group entities | Resolves to all entities in a selected entity group. | PE / Cloud |
| Entity list | Resolves to a manually selected list of entities. | All editions |
| Entity name | Resolves to all entities of a given type whose names start with a specified text. | All editions |
| Entity type | Resolves to all entities of a specified type, including customers’ entities. | All editions |
| Entity group list | Resolves to a list of entity groups of a specified type. | PE / Cloud |
| Entity group name | Resolves to entity groups whose names start with a specified text. | PE / Cloud |
| Entities by group name | Resolves to all entities belonging to a group with the specified exact name. | PE / Cloud |
| Entity from dashboard state | Resolves to an entity passed through dashboard state parameters. | All editions |
| Owner of entity from dashboard state | Resolves to the owner of the entity from the current dashboard state. | PE / Cloud |
| Asset type | Resolves to assets of the specified asset profile, optionally filtered by name. | All editions |
| Device type | Resolves to devices of the specified device profile, optionally filtered by name. | All editions |
| Entity view type | Resolves to entity views of the specified type, optionally filtered by name. | All editions |
| Edge type | Resolves to edges of the specified type, optionally filtered by name. | All editions |
| API usage state | Resolves to the platform’s API usage statistics. | All editions |
| Relations query | Resolves to entities connected via relations to a root entity, up to a specified depth and direction. | All editions |
| Asset search query | Resolves to assets of specified profiles connected via relations to a root entity, up to a specified depth and direction. | All editions |
| Device search query | Resolves to devices of specified profiles connected via relations to a root entity, up to a specified depth and direction. | All editions |
| Entity view search query | Resolves to entity views of specified types connected via relations to a root entity, up to a specified depth and direction. | All editions |
| Edge search query | Resolves to edges of specified types connected via relations to a root entity, up to a specified depth and direction. | All editions |
| Scheduler events | Resolves to scheduler events associated with a specified originator. | PE / Cloud |
| Originator entity | The entity that triggered the notification (e.g. the device that raised an alarm). | Only for report templates |
| Owner of originator entity | The customer or tenant that owns the originator entity. | Only for report templates |
| Entity from master report | The entity passed to this subreport by the master report. | Only for Subreports |
| Owner of entity from master report | The customer or tenant that owns the entity passed by the master report. | Only for Subreports |
Single entity
Section titled “Single entity”Resolves to one specific entity chosen by type and name.
Configuration:
Example: An alias filtering one device — Thermometer A1.
Group entities
Section titled Group entitiesResolves to all entities in a selected entity group.
Configuration:
Example: An alias displaying all devices in the Thermostats group.
Entity list
Section titled “Entity list”Resolves to a manually selected list of entities.
Configuration:
Example: An alias displaying three devices — Thermometer A1, Compressor BC-10, and Compressor QA-32.
Entity name
Section titled “Entity name”Resolves to all entities of a given type whose names start with a specified text.
Configuration:
Example: An alias displaying devices whose names start with “Compressor”.
Entity type
Section titled “Entity type”Resolves to all entities of a specified type, including customers’ entities.
Configuration:
Example: An alias displaying all devices, including customers’ devices.
Entity group list
Section titled Entity group listResolves to a list of entity groups of a specified type.
Configuration:
Example: An alias displaying device groups Compressors and Thermostats.
Entity group name
Section titled Entity group nameResolves to entity groups whose names start with a specified text.
Configuration:
Example: An alias displaying device groups whose names start with "Compressor".
Entities by group name
Section titled Entities by group nameResolves to all entities belonging to a group with the specified exact name.
Configuration:
Example: An alias displaying devices from the Compressors group.
Entity from dashboard state
Section titled “Entity from dashboard state”Resolves to an entity passed through dashboard state parameters. Used in drill-down dashboards to display data for the currently selected entity.
When a user interacts with a widget (for example, clicks a table row), a navigation action can pass the selected entity to the next dashboard state as a named parameter. This alias reads that parameter and resolves to the entity it carries, so widgets in the target state automatically display data for the entity the user selected.
Configuration:
Example: A drill-down dashboard where clicking a device row navigates to a detail state showing data for the selected device.
Owner of entity from dashboard state
Section titled Owner of entity from dashboard stateResolves to the owner of the entity from the current dashboard state. Useful for customer hierarchy dashboards.
Every entity in ThingsBoard has an owner — either the tenant or a customer. This alias reads an entity from the current dashboard state and resolves to its owner rather than the entity itself. It is most useful when you want to show information about the customer that owns a selected device without requiring a separate navigation step.
Configuration:
Example: A dashboard showing a device list and resolving the owner of the selected device when a row is clicked.
Asset type
Section titled “Asset type”Resolves to assets of the specified asset profile, optionally filtered by name.
Configuration:
Example: An alias filtering assets with profile “buildings” whose names start with “Build”.
Device type
Section titled “Device type”Resolves to devices of the specified device profile, optionally filtered by name.
Configuration:
Example: An alias filtering devices with profile “thermometers” whose names start with “Therm”.
Entity view type
Section titled “Entity view type”Resolves to entity views of the specified type, optionally filtered by name.
Configuration:
Example: An alias filtering entity views of type “Compressors Entity View Type”.
Edge type
Section titled “Edge type”Resolves to edges of the specified type, optionally filtered by name.
Configuration:
Example: An alias filtering edges of type “edge instance” whose names start with “Edge”.
API usage state
Section titled “API usage state”Resolves to the platform’s API usage statistics.
Configuration:
Example: An alias displaying platform API usage statistics in a widget.
Relations query
Section titled “Relations query”Resolves to entities connected via relations to a root entity, up to a specified depth and in a specified direction.
Configuration:
Example: An alias displaying all assets related to a root entity via a “Contains” relation.
Asset search query
Section titled “Asset search query”Resolves to assets of specified profiles connected via relations to a root entity, up to a specified depth and direction.
Configuration:
Example: An alias displaying assets of a specified profile related to a root entity.
Device search query
Section titled “Device search query”Resolves to devices of specified profiles connected via relations to a root entity, up to a specified depth and direction.
Configuration:
Example: An alias displaying devices of a specified profile related to a root entity.
Entity view search query
Section titled “Entity view search query”Resolves to entity views of specified types connected via relations to a root entity, up to a specified depth and direction.
Configuration:
Example: An alias displaying entity views of a specified type related to a root entity.
Edge search query
Section titled “Edge search query”Resolves to edges of specified types connected via relations to a root entity, up to a specified depth and direction.
Configuration:
Example: An alias displaying edges of a specified type related to a root entity.
Scheduler events
Section titled Scheduler eventsResolves to scheduler events associated with a specified originator, optionally filtered by event type.
Configuration:
Example: An alias displaying scheduler events associated with a selected device.
Subreport aliases
Section titled Subreport aliasesSubreport templates support all standard entity aliases listed above. In addition, they provide two special aliases that resolve to the entity passed from the master report:
| Alias | Resolves to |
|---|---|
| Entity from master report | The entity passed to this subreport by the master report. One subreport instance is generated per entity if the master's datasource returns multiple. |
| Owner of entity from master report | The customer or tenant that owns the entity passed by the master report |
Report template aliases
Section titled Report template aliasesReport templates support all standard entity aliases listed above. In addition, notification-triggered reports provide two extra aliases that resolve to the entity that initiated the report:
| Alias | Resolves to |
|---|---|
| Originator entity | The entity that triggered the notification (e.g. the device that raised an alarm) |
| Owner of originator entity | The customer or tenant that owns the originator entity |