Azure Service Bus Integration

Azure Service Bus Integration receives messages from a topic subscription in Azure Service Bus. An uplink data converter transforms each message into device or asset data, including telemetry and attributes. ThingsBoard can also publish downlink messages to a separate Service Bus topic.

Use Azure Service Bus Integration when:

• Your applications or IoT platforms already publish device data to a Service Bus topic.
• Several consumers must read the same data: each topic subscription receives its own copy of every message.
• Backend services must receive commands or data from ThingsBoard through a Service Bus topic.

1. Receive data. A producer sends a message to the uplink topic. The integration receives it from its subscription on that topic.
2. Decode the payload. The uplink converter identifies the target device or asset from the payload and extracts attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard can create an entity that does not exist yet.
4. Send downlink data (optional). The Rule Engine passes a message to the integration. The downlink converter encodes it, and the integration publishes it to the downlink topic.

• Access to ThingsBoard or ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• An Azure account with an active subscription and permission to create a Service Bus namespace.
• Outbound TCP port 5671 (AMQP) open from the ThingsBoard server to *.servicebus.windows.net.

Create a namespace, the uplink and downlink topics with their subscriptions, and copy the connection string. For details, see Create Service Bus topics and subscriptions.

1. In the Azure portal, click + Create a resource, search for Service Bus, and click Create.
2. On the Basics tab, select or create a Resource group, enter a globally unique Namespace name, and choose a Location.
3. Set Pricing tier to Standard or Premium. The Basic tier does not support topics.
4. Click Review + create, then Create.
5. When the deployment finishes, click Go to resource.

The integration reads from a topic subscription, not from a queue. Downlinks go to a second topic. A message sent to a topic without subscriptions is discarded, so the downlink topic also needs a subscription for its consumer.

1. In the namespace, go to Entities ⇾ Topics and click + Topic.
2. Enter the name uplinktopic and click Create.
3. Open uplinktopic, click + Subscription, enter S1, and click Create. ThingsBoard reads from this subscription.
4. Repeat steps 1–3 for the downlink: a topic downlinktopic with a subscription S2. Skip this if you do not need downlink.

Each subscription keeps its own copy of every topic message. Give ThingsBoard a subscription that no other application reads.

1. In the namespace, go to Settings ⇾ Shared access policies.
2. Click + Add, enter a Policy name, for example thingsboard, select Send and Listen, and click Create. Listen is needed for uplink, Send for downlink.
3. Open the policy and copy the Primary Connection String. It has the form Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=thingsboard;SharedAccessKey=<key>.

For a quick test, the default RootManageSharedAccessKey policy also works, but it grants full control of the namespace.

You now have the values for the integration:

Create the uplink converter, assign it to a new Azure Service Bus integration, and send a test message.

The uplink converter receives each message body as a byte array, resolves the target device, and returns its telemetry and attributes. Azure Service Bus Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

This guide uses the sample payload that ThingsBoard provides for Azure Service Bus converters, with a recent timestamp:

{
  "deviceId": "8F4A2C6D",
  "deviceType": "Packing machine",
  "temperature": 25.5,
  "pressure": 1013.25,
  "vibration": {
    "x": 0.02,
    "y": 0.03,
    "z": 0.015
  },
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 10
  },
  "timestamp": "2026-10-14T10:30:00Z",
  "status": "ALARM",
  "alarms": [
    {
      "type": "temperature",
      "severity": "high",
      "message": "Temperature exceeds threshold."
    },
    {
      "type": "vibration",
      "severity": "critical",
      "message": "Excessive vibration detected."
    }
  ],
  "metadata": {
    "version": 1,
    "batteryLevel": 100,
    "batteryStatus": "Charging",
    "manufacturer": "Example corporation"
  }
}

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select Azure Service Bus.

4. Name — enter a name, for example Azure Service Bus Uplink Converter.

5. Main decoding configuration — the editor opens with the default Azure Service Bus template. Replace it with the decoder below. The decoder maps measurements and state to telemetry and static device properties to attributes. It also reads timestamp, location, and vibration when the payload carries them. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   var data = decodeToJson(payload);
   
   var deviceName = data.deviceId != null ? data.deviceId : "Device A";
   var deviceType = data.deviceType != null ? data.deviceType : "default";
   
   // ISO 8601 timestamp; fall back to server time.
   var ts = data.timestamp != null ? new Date(data.timestamp).getTime() : Date.now();
   
   // Static device properties become attributes.
   var attributes = {};
   if (data.location != null) {
       attributes.latitude = data.location.latitude;
       attributes.longitude = data.location.longitude;
       attributes.altitude = data.location.altitude;
   }
   

   ▼Expand

   To adapt:

   • Device name in another field — replace data.deviceId, for example with data.serialNumber.
   • Device name in a message property — if the producer sets a custom property, for example deviceId, read it with metadata["sysProp:deviceId"].
   • Optional fields — remove the location, vibration, status, or alarms mappings your devices never send.
   • Other telemetry — add keys to telemetry, for example humidity: data.humidity.
   • Other device properties — add them to attributes, for example model: data.model.
   • Update-only keys — for Azure Service Bus, ThingsBoard pre-fills the Update only keys list in Advanced decoding parameters with manufacturer, receivedAlarms, status, batteryLevel, batteryStatus, and version. These keys are stored only when their value changes. Edit the list to match your keys.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

Built-in helpers:

For field renaming, nested values, and non-JSON payloads, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. Replace the content of Payload with the sample payload. Click Test. The Output panel shows:

{
  "deviceName": "8F4A2C6D",
  "deviceType": "Packing machine",
  "attributes": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 10,
    "version": 1,
    "manufacturer": "Example corporation"
  },
  "telemetry": {
    "ts": 1791973800000,
    "values": {
      "temperature": 25.5,
      "pressure": 1013.25,
      "status": "ALARM",
      "receivedAlarms": [
        {
          "type": "temperature",
          "severity": "high",
          "message": "Temperature exceeds threshold."
        },
        {
          "type": "vibration",
          "severity": "critical",
          "message": "Excessive vibration detected."
        }
      ],
      "vibrationX": 0.02,
      "vibrationY": 0.03,
      "vibrationZ": 0.015,
      "batteryLevel": 100,
      "batteryStatus": "Charging"
    }
  }
}

ts is the payload’s timestamp, 2026-10-14T10:30:00Z, in milliseconds.

Check that deviceName is set and telemetry holds the expected keys. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select Azure Service Bus.
   • Name — keep the default or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose Azure Service Bus Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to publish to Service Bus.
5. Connection:
   • Connection string — paste the Primary Connection String.
   • Topic name — enter uplinktopic.
   • Subscription name — enter S1.
   • See Connection Settings for details.
6. Click Add.

Advanced settings

Check connection validates only the format of the connection string. It does not connect to the topic, so wrong names or keys show up as missing uplinks.

The integration removes each message from the subscription after processing it, including messages the converter fails to decode. Check Error events in the converter to catch them.

Send a message to the uplink topic, then confirm that ThingsBoard decoded it and created the device.

Send the sample payload without timestamp. The decoder then uses the current server time; with a fixed timestamp, the data would fall outside the recent time windows of your dashboards as time passes.

1. In the namespace, go to Entities ⇾ Topics and open uplinktopic.

2. Click Service Bus Explorer in the topic menu, then click Send messages.

3. Set Content Type to Application/Json.

4. Paste the payload into Message body:

   {
     "deviceId": "8F4A2C6D",
     "deviceType": "Packing machine",
     "temperature": 25.5,
     "pressure": 1013.25,
     "vibration": {
       "x": 0.02,
       "y": 0.03,
       "z": 0.015
     },
     "location": {
       "latitude": 37.7749,
       "longitude": -122.4194,
       "altitude": 10
     },
   

   ▼Expand

5. Click Send.

Service Bus Explorer needs the Service Bus Data Owner or Service Bus Data Sender role on the namespace.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK. Click ⋅⋅⋅ in the Message column to see the message: systemProperties (the custom properties) and payload.
• Converter events — open Azure Service Bus Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the received payload, Out shows the decoded result, and Metadata shows the integration name and any sysProp: values.
• Device — go to Devices & assets ⇾ Devices. The integration has created 8F4A2C6D with the Packing machine profile. Open it and check the Latest telemetry tab for temperature, pressure, status, receivedAlarms, vibrationX–vibrationZ, batteryLevel, and batteryStatus, and the Attributes tab for latitude, longitude, altitude, version, and manufacturer.

ThingsBoard publishes a downlink when the Rule Engine routes a message to the integration — for example, after a shared attribute update. The integration sends it to the Downlink topic name. Every subscription on that topic receives a copy, and your backend reads it from its subscription.

Each downlink message carries:

• Body — the encoder’s data.
• Content type — the encoder’s contentType: JSON, TEXT, or BINARY.
• To — the encoder’s metadata.deviceId. Consumers can filter or route on it.
• Custom properties — every key of the encoder’s metadata.

The downlink converter turns a Rule Engine message into the published message. For the full encoder reference, see Downlink data converter.

The encoder must set metadata.deviceId. Without it, the integration skips the message.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and Azure Service Bus integration type are preselected.
3. Enter a name, for example Azure Service Bus Downlink Converter.
4. In Main encoding configuration, replace the default encoder with the one below.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add.
7. In Advanced settings, fill in:
   • Downlink connection string — the connection string of a policy with Send permission. With the thingsboard policy, paste the same string as for uplink.
   • Downlink topic name — enter downlinktopic.
8. Click Apply changes.

Encoder used in this guide (TBEL and JavaScript):

/** Encoder **/

// Publish the Rule Engine message as the message body.
var result = {
  // Payload content type: JSON, TEXT, or BINARY (Base64).
  contentType: 'JSON',
  data: JSON.stringify(msg),
  metadata: {
    // Required. Becomes the message's To property
    // and the custom property deviceId.
    deviceId: metadata.deviceName
  }
};

return result;

To check the encoder, click Test encoder function. Message type is already ATTRIBUTES_UPDATED. Set Message to {"temperatureUploadFrequency":60} and deviceName in Metadata to 8F4A2C6D, if they differ, then click Test. The Output shows:

{
  "contentType": "JSON",
  "data": "{\"temperatureUploadFrequency\":60}",
  "metadata": {
    "deviceId": "8F4A2C6D"
  }
}

To adapt:

• Another envelope — build data in the structure your consumer expects, for example { "device": metadata.deviceName, "config": msg }.
• Routing properties — add keys to metadata, for example type: 'config'. Subscription filter rules on the downlink topic can route on these custom properties.
• Other message types — branch on msgType, for example to handle RPC_CALL_FROM_SERVER_TO_DEVICE with msg.method and msg.params. See Rule Engine message types.

The encoder reads deviceName from the message metadata, so the rule chain first adds the device name.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Enrichment section, drag an originator fields node onto the canvas.
3. Enter a Name (for example, Retrieve device name) and map the source fields:
   • Name ⇾ deviceName
   • Add mapped originator fields to ⇾ Metadata
   • Click Add.
4. Connect the message type switch node to the originator fields node with the Attributes Updated relation.
5. From the Action section, drag an integration downlink node onto the canvas.
6. Enter a Name (for example, Downlink to Azure Service Bus), select your Azure Service Bus integration, and click Add.
7. Connect the originator fields node to the integration downlink node with the Success relation.
8. Click Apply changes.

1. Go to Devices & assets ⇾ Devices, select 8F4A2C6D, and open the Attributes tab.
2. Select Shared attributes and click +.
3. Set Key to temperatureUploadFrequency, Type to Integer, Value to 60, and click Add. ThingsBoard publishes the downlink.

• Integration events — the integration’s Events tab shows a Downlink event with deviceId, payload ({"temperatureUploadFrequency":60}), and properties.
• Service Bus Explorer — open downlinktopic, click Service Bus Explorer, and select the subscription S2. Select Peek Mode and click Peek from start. Select the message to see its body; the Message Properties tab shows To and the deviceId property.

Open the downlink topic subscription in Service Bus Explorer The message body holds the downlink payload from ThingsBoard

Peek Mode leaves the message in the subscription. Receive Mode with ReceiveAndDelete removes it.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• Service Bus queues, topics, and subscriptions — messaging model and subscription filters.
• Service Bus Explorer — send, peek, and receive messages in the Azure portal.