Attributes

Attributes on ThingsBoard Edge are stored and processed locally. They stay available to dashboards and rule chains even when the connection to the server is lost. Attribute changes are not synchronized automatically: to sync them, you configure the rule chain on each side.

For an overview of how attributes work on Edge, see Edge attributes.

You can add attributes directly on the Edge. The steps below use Server attributes, the scope for metadata that you set manually and that the device does not report.

1. On the Edge, go to the entity section, for example Devices & assets > Devices, and click the entity.

2. On the Entity details page, select the Attributes tab and choose Server attributes in the Entity attributes scope dropdown.

3. Click Add (+). In the Add attribute dialog, enter the attribute name in the Key field, select the value type (String, Integer, Double, Boolean, or JSON), enter the value, and click Add.

The attribute appears in the list.

If an attribute is set on an entity on the server, and the entity is then assigned to an Edge, the attribute is pushed to the Edge automatically.

Attributes add context to telemetry on dashboards. They show static or dynamic metadata of a device, or act as parameters that filter or annotate widgets.

1. Open a dashboard and enter edit mode.

2. Add a widget. Cards, input widgets, and entity table widgets work well for attributes.

3. In the widget datasource, create an entity alias that points to the entity whose attributes you want to show.

4. Select the attribute keys to display and click Add.

Attribute changes are not synchronized automatically between Edge and the server. Each direction needs a push node in the rule chain on the sending side.

1. On the server, go to Data processing > Rule chains and open the rule chain that processes your device messages, for example the root rule chain.

2. Find the push to edge node in the Search nodes field and drag it onto the rule chain sheet. In the Add rule node dialog, enter a name, select Server attributes in the Attributes scope field, and click Add.

3. Connect the message type switch node to the push to edge node with the Attributes Updated and Attributes Deleted labels. Click Apply changes.

1. On the server, go to Edge management > Templates, open the Rule chain tab, and open the rule chain template assigned to your Edge.

2. Find the push to cloud node in the Search nodes field and drag it onto the rule chain sheet. In the Add rule node dialog, enter a name, select Server attributes in the Attributes scope field, and click Add.

3. Connect the message type switch node to the push to cloud node with the Attributes Updated and Attributes Deleted labels. Click Apply changes.

The default Edge Root Rule Chain template already contains this node, with the Server attributes scope and these two connections. You only need to add it to your own rule chains.

Since release 3.9, you can set attributes on the Edge instance itself. In a rule chain, these attributes work as placeholders: one rule chain template can serve many Edges, and each Edge fills in its own values at runtime.

1. On the server, go to Edge management > Edges and click the Edge.

2. On the Edge details page, select the Attributes tab and click Add (+). In the Add attribute dialog, enter the key and value, for example the key token with the value edgeAccessToken, and click Add.

3. Select the Relations tab and click Add (+). In the Add relation dialog, select Manages in the Relation type field, select Device in the Type field, add the devices of this Edge to the entity list, and click Add.

The example below reads the token attribute of the Edge and uses it as a request header in a REST API call.

1. On the server, go to Edge management > Templates, open the Rule chain tab, and open the rule chain. On Edge 4.0 or later, you can edit the rule chain directly on the Edge under Data processing > Rule chains.

2. Find the related entity data node in the Search nodes field and drag it onto the rule chain sheet. Fill in the fields:

   • Name: Enter the node name.
   • Direction: Select To originator. The Edge manages the device that sends the message.
   • Relation type: Select Manages.
   • Entity types: Add Edge.

3. In the Data to fetch block, select the Attributes tab and configure the Attributes mapping:

   • Source attribute key: Enter the Edge attribute key, for example token.
   • Target key: Enter the target key name, for example edgeAccessToken.

   Set Add mapped attributes to to Metadata and click Add.

4. Find the rest api call node, drag it onto the sheet, and configure it:

   • Name: Enter the node name.
   • Endpoint URL pattern: Enter the URL of the external service.
   • Headers: Enter the header name and value, for example token and ${edgeAccessToken}. The value can be a static string or a pattern resolved from the message metadata.

   Click Add.

5. Connect message type switch > related entity data with the Post telemetry label. Connect related entity data > rest api call with the Success label. Click Apply changes.

This section shows how to use the attributes of a related entity in rule chain logic. In the example, the Edge raises an alarm when an attribute of a device changes, and adds an attribute of the related asset to the message metadata.

Before you start:

• Add a device to the Edge. See Entities and relations.
• Add a custom attribute to the device. See Assigning attributes to entities.
• Create an asset, add an attribute to it, for example location, and set a Contains or Manages relation between the asset and the device.

1. On the server, go to Edge management > Templates, open the Rule chain tab, and open the rule chain. On Edge 4.0 or later, you can edit the rule chain directly on the Edge under Data processing > Rule chains.

2. Find the related entity data node, drag it onto the sheet, and fill in the fields:

   • Name: Enter the node name.
   • Direction: Select To originator if the related entity has the relation to the device (for example, an asset that Contains the device). Select From originator if the device has the relation to the related entity.
   • Relation type: Select Contains or Manages, matching the relation you created.
   • Entity types: Add the entity type of the related entity, for example Asset.

3. In the Data to fetch block, select the Attributes tab and configure the Attributes mapping:

   • Source attribute key: Enter the attribute of the asset, for example location.
   • Target key: Enter the metadata key for its value, for example assetLocation.

   Click Add.

4. Find the create alarm node, drag it onto the sheet, and enter a name. Keep the default Alarm type (General Alarm) or enter your own. Click Add.

5. Connect message type switch > related entity data with the Attributes Updated and Attributes Deleted labels. Connect related entity data > create alarm with the Success label. Click Apply changes.

6. On the Edge, go to Devices & assets > Devices, open the device, select the Attributes tab, and change the custom attribute of the device. The alarm is listed on the Alarms tab of the device.