Send and receive Azure Service Bus messages in Jitterbit Studio

Introduction

Azure Service Bus is a managed messaging service that supports two messaging patterns:

• Queues: Point-to-point messaging where each message is consumed by a single receiver.
• Topics and subscriptions: Publish-subscribe messaging where each message is delivered to multiple subscribers through topic subscriptions.

The Microsoft Azure Service Bus connector provides activities for both patterns. This guide covers the most common workflows:

• Sending a message to a queue or topic using the Send Message activity.
• Retrieving messages from a queue using the Get Queue Message activity.
• Retrieving messages from a topic subscription using the Get Topic Message activity.

For event-driven consumption (where Studio listens continuously for incoming messages), see the Consume Queue and Consume Topic activity references, which require a private agent cluster with specific network configuration.

This guide assumes the following:

• An Azure Service Bus namespace is configured with the required queues or topics.
• The service principal or policy used for authentication has the appropriate role or rights, as described in Azure Service Bus prerequisites.

Part 1: Configure the Azure Service Bus connection

The connector supports two authentication types. Use Microsoft Entra ID when connecting via an Azure app registration (recommended for production). Use Shared Access Signatures for simpler setups or where Entra ID is not available.

1. In Studio, open your project and go to the Project endpoints and connectors tab in the design component palette.

2. Click the Microsoft Azure Service Bus connector to open the connection configuration.

3. Connection Name: Enter a unique name (for example, Azure Service Bus). The name cannot contain forward slashes or colons.

4. Authentication Type: Select one of the following:

   Microsoft Entra ID:

   • Namespace / Hostname: Enter the Service Bus namespace name (for example, my-namespace) or the full hostname (for example, my-namespace.servicebus.windows.net).
   • Tenant ID: Enter the directory (tenant) ID of your Azure Active Directory.
   • Client ID: Enter the application (client) ID of the app registration.
   • Client Secret: Enter the client secret value for the app registration.

   Shared Access Signatures:

   • Namespace / Hostname: Enter the namespace name or full hostname.
   • Policy Name: Enter the name of the Shared Access Policy configured on the namespace or queue.
   • Primary Key: Enter the primary key value for the policy.

5. Click Test to verify the connection.

6. Click Save Changes.

Part 2: Send a message

The Send Message activity is a target activity that writes a message to a queue or topic. Use it when Studio needs to publish events or data to downstream systems.

Design pattern

Step 1: Configure the Send Message activity

1. On the design canvas, drag a Send Message activity from the Azure Service Bus connection onto the canvas.

2. Name: Enter a descriptive name (for example, Send Order to Queue).

3. Choose Queue/Topic: Select Select Existent Queue/Topic to choose from a list, or Inform Queue/Topic Manually to enter the name directly.

4. Enter or select the queue or topic name.

5. Click Next, review the request schema, then click Finished.

Step 2: Map the transformation

1. Add a Transformation step between the source activity and the Send Message activity.

2. Open the transformation and map data fields to the Send Message request schema. The schema includes a body field for the message content. For structured data, serialize to JSON before mapping:

   JSONStringify($record_data)
   

   The schema also includes optional fields for message properties such as contentType, correlationId, and sessionId. Set these if your downstream consumers rely on them for routing or filtering.

Part 3: Retrieve messages from a queue

The Get Queue Message activity is a source activity that polls a queue for pending messages. Studio processes each retrieved message through a transformation and writes it to the target.

Design pattern

Step 1: Configure the Get Queue Message activity

1. On the design canvas, drag a Get Queue Message activity from the Azure Service Bus connection onto the canvas.

2. Name: Enter a descriptive name (for example, Get Orders from Queue).

3. Choose Queue: Select or enter the queue name.

4. Receive Mode: Select one of the following:

   • Peek Lock: The message is locked for a configurable period while Studio processes it. The message remains in the queue until explicitly deleted. Use this mode when reliable processing matters: if the operation fails, the lock expires and the message becomes available again.
   • Receive and Delete: The message is deleted from the queue immediately when retrieved. Use this mode only when message loss on failure is acceptable.

5. Number of Messages: Enter the number of messages to retrieve per run (1–100, default 1).

6. Wait Time: Enter the maximum time in seconds to wait for messages if the queue is empty (default 10, maximum 245).

7. Click Next, review the response schema, then click Finished.

Step 2: Process and delete the message

When using Peek Lock mode, messages must be explicitly deleted after successful processing to remove them from the queue. Add a Delete Queue Message operation chained on success of the processing operation:

1. On the design canvas, create a second operation containing a Delete Queue Message activity.

2. In the Get Queue Message processing operation, store the message's lock token in a global variable during the transformation:

   $lock_token = Source.lockToken;
   

3. Configure the Delete Queue Message activity with the same queue name, and map lock_token to the delete request schema.

4. In the processing operation's settings, configure the Delete Queue Message operation to run On Success.

Part 4: Retrieve messages from a topic subscription

Retrieving from a topic subscription follows the same pattern as queue retrieval, but requires selecting both a topic and a subscription.

1. On the design canvas, drag a Get Topic Message activity from the Azure Service Bus connection onto the canvas.

2. Configure the activity the same way as Get Queue Message (see Part 3), but:

   • Select a Topic name.
   • After selecting the topic, select a Subscription within that topic.

3. To delete processed messages, use a Delete Topic Message activity instead of Delete Queue Message, and select the same topic and subscription.

Verify the integration

Sending: Run the send operation and verify in the Azure portal that the message count on the queue or topic increased. Use the Service Bus Explorer feature in the portal to inspect the message body and properties.

Receiving: Send a test message to the queue or topic using the Azure portal's Service Bus Explorer. Run the Get Queue Message or Get Topic Message operation and check the operation logs to confirm the message was retrieved. Verify the target was written with the expected data. If using Peek Lock, confirm the message was deleted from the queue by checking the message count in the portal.

If the connection test fails, verify that the service principal or Shared Access Policy has the Azure Service Bus Data Owner role or the appropriate send/listen rights, as described in Azure Service Bus prerequisites.