Integrations overview

Edge integrations connect ThingsBoard Edge to external brokers and servers, such as MQTT, HTTP, CoAP, OPC-UA, TCP, and UDP. Incoming data is processed on the Edge before it is synchronized with the server.

They work like integrations on the ThingsBoard server, with one key difference: you do not create the integration on the Edge. You create integration templates and converter templates on the server and assign them to one or more Edges. Each Edge receives a copy and runs it.

Each integration can run in one of two modes.

An embedded integration runs inside the main ThingsBoard Edge process.

Advantages:

• No extra packages to install. The integration is deployed in a few clicks from the UI.
• Minimal message delivery latency.

Trade-offs:

• Shares CPU, memory, and network connections with the Edge process.
• Lower isolation from the main Edge process.

A remote integration runs as a separate process on the local network and streams data to the Edge over the network.

This is useful when the broker or server, for example a local MQTT broker or an OPC-UA server, has no external IP address and cannot be reached by the Edge directly. The remote integration is deployed on the same local network as the broker, pulls data from it, and streams it to the Edge whenever a connection is available. See Remote integrations.

Advantages:

• Works with servers that have no external IP address.
• Fully isolated from the Edge process.

Trade-offs:

• Requires installing and maintaining a separate package.

A converter template transforms data. An uplink converter decodes the raw integration payload into ThingsBoard telemetry and attributes. A downlink converter encodes messages from the rule engine into the format the device expects. A tenant administrator creates converter templates on the server:

1. Go to Edge management > Templates and open the Converter tab.
2. Click Add data converter and select Create new converter.
3. Set Converter type to Uplink or Downlink, select the Integration type the converter is made for, and enter a Name.
4. In Main decoding configuration (uplink) or Main encoding configuration (downlink), select the script language, TBEL or JS, and enter the decoder or encoder function. For uplink converters, Advanced decoding parameters holds optional settings such as Update only keys list.
5. Click Add.

You do not assign converter templates to an Edge. When an integration template is assigned to an Edge, its uplink and downlink converters are sent with it.

When the converter templates are ready, create the integration template. Go to Edge management > Templates, open the Integration tab, click Add integration, and follow the wizard:

Step	What to do
Basic settings	Select the Integration type and enter a name.
Uplink data converter	Create new creates a converter template in place. Select existing links a converter template of this integration type. For some types, such as HTTP and ChirpStack, Library offers ready-made converters.
Downlink data converter	The same options plus Skip, which is selected by default. CoAP has no downlink step.
Connection	The connection fields of the integration type, the Execute remotely toggle, and Advanced settings. Click Add.

Integration templates do not run on the server. They run on the Edges they are assigned to.

1. Go to Edge management > Edges and click the Edge.
2. On the Details tab, click Manage integrations.
3. Click Assign to edge (+), select the templates, and click Assign.

For more details, see Assign entities to an Edge.

On the Edge, the assigned integrations and converters appear under Integrations > Integrations and Integrations > Data converters. They are read-only there. To change an integration or converter, edit the template on the server. The change is pushed to every Edge that has the template assigned.

If the same integration template is used on several Edges, but each Edge needs a different value for a field (for example a host address or a base URL), use placeholders.

Add a server attribute to the Edge and reference it in the template as ${{attributeKey}}. When the server sends the integration to that Edge, it replaces the placeholder with the attribute value. The template on the server keeps the placeholder; only the copy on the Edge holds the value. If you change the attribute later, the server sends the integration to the Edge again with the new value.

For example, an HTTP integration needs a different Base URL on every Edge:

1. On the server, go to Edge management > Edges, click the Edge, and open the Attributes tab. With the Server attributes scope selected, click +, enter the key ipAddress and the address of this Edge as the value, and click Add.
2. On the Integration tab of Edge management > Templates, open the template and set Base URL to http://${{ipAddress}}.
3. If the template is not assigned to the Edge yet, assign it as described above.
4. On the Edge, go to Integrations > Integrations and open the integration. Base URL shows the attribute value.

If an Edge does not have the attribute, ThingsBoard warns you in two cases:

• When you assign the template to the Edge. The dialog Edge has missing attribute(s) lists the attributes that are missing.
• When you save a template that is already assigned to Edges. The dialog Edge(s) have missing attribute(s) lists the Edges and the attributes that are missing.

Add the missing attribute to each listed Edge. Until then, the Edge copy keeps the literal placeholder.

The Edge cannot create customers or entity groups. This affects how an uplink converter result is applied on the Edge:

• If the device type referenced in the converter does not exist on the Edge, the Edge creates a device profile with that name and syncs it to the server.
• If the target customer is not available on the Edge, the device is assigned to the tenant.
• If the target entity group does not exist on the Edge, the All group is used.