Azure Service Bus Integration

Azure Service Bus is a fully managed enterprise message broker from Microsoft that supports queues and publish/subscribe topics. The ThingsBoard Azure Service Bus integration subscribes to a topic on your Service Bus namespace, receives device messages, decodes them via an uplink converter, and stores telemetry and attributes in ThingsBoard. In the reverse direction, it encodes Rule Engine messages via a downlink converter and publishes them to a dedicated downlink topic.

Before creating the integration in ThingsBoard, prepare the following in the Azure portal:

1. Open your Service Bus namespace (or create one). A namespace is the scoping container for all messaging components and has a globally unique DNS name in the form <namespace>.servicebus.windows.net.
2. Create a topic for uplink messages (e.g. uplinktopic). Topics implement the publish/subscribe pattern — multiple subscribers can independently consume the same messages.
3. Create a subscription on that topic (e.g. S1). Each subscription maintains its own independent copy of every message published to the topic, so ThingsBoard consumes messages without affecting other consumers.
4. Copy the connection string for the namespace — go to Settings ⇾ Shared access policies, open a policy (e.g. RootManageSharedAccessKey), and copy the Primary Connection String. It has the form Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<policy>;SharedAccessKey=<key>.

The uplink converter decodes incoming Azure Service Bus messages and maps them to the ThingsBoard data model. Azure Service Bus uses a generic uplink converter.

Sample input message:

{
  "devName": "Sensor A1",
  "msg": {
    "temp": 23,
    "humidity": 40
  }
}

The devName field maps to deviceName. The nested msg object provides temperature and humidity telemetry.

Import the uplink converter

1. Download the uplink converter file:

2. Go to Integrations center ⇾ Data converters.
3. Click + Add data converter ⇾ Import converter.
4. Drag and drop the downloaded JSON file into the Import converter window and click Import.

The decoder function used in this tutorial:

var data = decodeToJson(payload);
var deviceName = data.devName;
var deviceType = 'thermostat';

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    telemetry: {
        temperature: data.msg.temp,
        humidity: data.msg.humidity
    }
};

return result;

var data = decodeToJson(payload);
var deviceName = data.devName;
var deviceType = 'thermostat';

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    telemetry: {
        temperature: data.msg.temp,
        humidity: data.msg.humidity
    }
};

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
    var str = decodeToString(payload);
    var data = JSON.parse(str);
    return data;
}

return result;

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to Azure Service Bus.
   • Enter a name for the integration.
   • Click Next.
3. Uplink data converter:
   • Select existing — choose the previously created Azure Service Bus Uplink Converter from the list.
   • Click Next.
4. Downlink data converter:
   • Leave the field empty for now and click Skip.
5. Connection:
   • Connection string — the namespace connection string from Azure.
   • Topic name — the name of the uplink topic (e.g. uplinktopic).
   • Subscription name — the name of the subscription on that topic (e.g. S1).
   See Connection settings for a full description of each parameter.
6. Click Check connection to verify connectivity — the wizard shows Connected when successful.
7. Click Add to save the integration.

Go to Integrations center → Integrations (1), click + Add integration (2), set Integration type to Azure Service Bus (3), enter a name (4), and click Next (5) Click Select existing uplink data converter (7), choose Service Bus Uplink Converter from the list, and click Next (8) Leave the Downlink data converter field empty and click Skip (9) Enter the Connection string (10), Topic name (11), and Subscription name (12); click Check connection (13) to verify, then click Add Check connection result — Connected confirms the integration can reach Azure Service Bus; click Add (14) to save

Connection string

The Azure Service Bus namespace connection string used to authenticate the integration. Found under Settings ⇾ Shared access policies in your namespace — copy the Primary Connection String of any policy that has Listen permission (e.g. RootManageSharedAccessKey). Format: Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<policy>;SharedAccessKey=<key>.

Topic name

The name of the Azure Service Bus topic ThingsBoard subscribes to for uplink messages (e.g. uplinktopic).

Subscription name

The name of the subscription on the uplink topic that ThingsBoard consumes (e.g. S1). Each subscription receives an independent copy of every message published to the topic.

Execute remotely

When enabled, ThingsBoard generates an Integration key and Integration secret that allow the integration to run as a separate process outside the ThingsBoard cluster — useful when the Azure Service Bus endpoint is only reachable from a specific network.

Advanced settings

• Downlink connection string — the connection string for the namespace where the downlink topic resides (can be the same namespace as the uplink); requires Send permission
• Downlink topic name — the name of the Azure Service Bus topic ThingsBoard publishes downlink messages to (e.g. downlinktopic)
• Description — optional text description for this integration
• Metadata — key-value pairs injected into every uplink message as integrationMetadata in converter scripts

To test the integration, send a message to your Azure Service Bus topic using the Service Bus Explorer in the Azure portal:

1. In the Azure portal, open your Service Bus namespace and navigate to the uplink topic (e.g. uplinktopic).
2. Click Service Bus Explorer in the left menu.
3. Click Send messages, set Content type to application/json, and paste the payload below into the Message Body field.
4. Click Send.

{
  "devName": "Sensor A1",
  "msg": {
    "temp": 23,
    "humidity": 40
  }
}

Go to Integrations center ⇾ Integrations, open the Azure Service Bus integration, and check the Events tab — you should see an Uplink event confirming that ThingsBoard received and processed the message.

Received data can be viewed in the Uplink converter. In the In and Out blocks of the Events tab:

Go to Data converters (1), open Service Bus Uplink Converter (2), and navigate to its Events tab (3) — the Uplink event row shows the converter was invoked In — the raw JSON payload passed to the decoder: devName, msg.temp, and msg.humidity Out — the decoded result: deviceName, deviceType, and telemetry fields ready for ThingsBoard ingestion

The device Sensor A1 is created automatically on the first uplink. Click the notification bell at the top — ThingsBoard notifies you that the device has become active. Go to Entities ⇾ Devices, open Sensor A1, and navigate to the Latest telemetry tab to verify the received values.

Click the notification bell (1) — ThingsBoard notifies you that device Sensor A1 has been created and is active (2); click Go to device to open it Navigate to the Latest telemetry tab (3) — humidity = 40 and temperature = 23 are stored from the uplink message

To send messages from ThingsBoard back to Azure Service Bus, create a dedicated downlink topic in Azure, add a downlink converter, configure the integration’s advanced settings, and wire the Root Rule Chain to forward attribute updates.

The downlink converter encodes Rule Engine messages into Azure Service Bus payloads. The output must include:

• contentType — how data is encoded: TEXT, JSON, or BINARY
• data — the payload to publish to the downlink topic
• metadata.deviceId — identifier passed as a message property to route the message to the correct device

Import the downlink converter

1. Download the downlink converter file:

2. Go to Integrations center ⇾ Data converters.
3. Click + Add data converter ⇾ Import converter.
4. Drag and drop the downloaded JSON file into the Import converter window and click Import.

The encoder function used in this tutorial:

var result = {
    contentType: "JSON",
    data: JSON.stringify(msg),
    metadata: {
        deviceId: metadata.deviceName
    }
};

return result;

var result = {
    contentType: "JSON",
    data: JSON.stringify(msg),
    metadata: {
        deviceId: metadata.deviceName
    }
};

return result;

1. Go to Integrations center ⇾ Integrations and open the Azure Service Bus integration.
2. Click the edit (pencil) icon.
3. In the Downlink data converter field, select Service Bus Downlink Converter.
4. Expand Advanced settings and fill in:
   • Downlink connection string — the namespace connection string (copy from the uplink settings if you use the same namespace)
   • Downlink topic name — the name of the downlink topic (e.g. downlinktopic)
5. Click Apply changes.

Add an Integration Downlink node to the Root Rule Chain to forward attribute updates to Azure Service Bus.

1. Go to Rule chains and open the Root Rule Chain. Click the edit icon.
2. Find Integration Downlink in the node panel and drag it onto the canvas.
3. In the Add rule node dialog, enter a name (e.g. Service Bus downlink node), select Azure Service Bus Integration, and click Add.
4. Connect the Message Type Switch node to the Integration Downlink node using both the Post attributes and Attributes Updated relations.
5. Click Apply changes.

In the Root Rule Chain, add an Integration Downlink node (1), name it Service Bus downlink node (2), select Azure Service Bus Integration (3), and click Add (4) Connect Message Type Switch to the Service Bus downlink node via Post attributes and Attributes Updated (5), then click Apply changes (6)

Trigger a downlink by adding a shared attribute to device Sensor A1:

1. Go to Entities ⇾ Devices and open device Sensor A1.
2. Navigate to the Attributes tab, switch to Shared attributes, and click +.
3. Enter key firmware and value 01052020.v1.1, then click Add.

Adding the attribute triggers the rule chain, which forwards the message to the Azure Service Bus integration. Go to Integrations center ⇾ Integrations, open the Azure Service Bus integration, and check the Events tab — a Downlink event appears with the payload sent to the downlink topic.

To confirm the message reached Azure Service Bus, open the Azure portal, navigate to the downlink topic subscription (e.g. downlinktopic / S2), and use Service Bus Explorer to receive messages:

Open the downlinktopic subscription in Service Bus Explorer (1), select Receive mode (3), and click Receive messages (4) to pull messages from the subscription The downlink message appears in the subscription — Message Text shows the firmware attribute value forwarded from ThingsBoard

• Integration Overview
• Uplink Converters
• Downlink Converters
• Rule Engine
• ThingsBoard Expression Language (TBEL)