Connect to Azure Service Bus from workflows in Azure Logic Apps

Applies to: Azure Logic Apps (Consumption + Standard)

This guide shows how to access Azure Service Bus from a workflow in Azure Logic Apps using the Service Bus connector. You can then create automated workflows that run when triggered by events in a service bus or run actions to manage service bus items, for example:

  • Monitor when messages arrive (auto-complete) or are received (peek-lock) in queues, topics, and topic subscriptions.
  • Send messages.
  • Create and delete topic subscriptions.
  • Manage messages in queues and topic subscriptions, for example, get, get deferred, complete, defer, abandon, and dead-letter.
  • Renew locks on messages and sessions in queues and topic subscriptions.
  • Close sessions in queues and topics.

You can use triggers that get responses from Azure Service Bus and make the output available to other actions in your workflows. You can also have other actions use the output from Service Bus actions.

Connector technical reference

The Service Bus connector has different versions, based on logic app workflow type and host environment.

Logic app Environment Connector version
Consumption Multi-tenant Azure Logic Apps Managed connector (Standard class). For more information, review the following documentation:

- Service Bus managed connector reference
- Managed connectors in Azure Logic Apps
Standard Single-tenant Azure Logic Apps and App Service Environment v3 (Windows plans only) Managed connector (Azure-hosted) and built-in connector, which is service provider based. The built-in version usually provides better performance, capabilities, pricing, and so on.

Note: Service Bus built-in connector triggers follow the polling trigger pattern, which means that the trigger continually checks for messages in the queue or topic subscription.

For more information, review the following documentation:

- Service Bus managed connector reference
- Service Bus built-in connector operations
- Built-in connectors in Azure Logic Apps

Prerequisites

  • An Azure account and subscription. If you don't have an Azure subscription, sign up for a trial Azure subscription.

  • A Service Bus namespace and messaging entity, such as a queue. For more information, review the following documentation:

  • The logic app workflow where you connect to your Service Bus namespace and messaging entity. To start your workflow with a Service Bus trigger, you have to start with a blank workflow. To use a Service Bus action in your workflow, start your workflow with any trigger.

  • If your logic app resource uses a managed identity for authenticating access to your Service Bus namespace and messaging entity, make sure that you've assigned role permissions at the corresponding levels. For example, to access a queue, the managed identity requires a role that has the necessary permissions for that queue.

    Each managed identity that accesses a different messaging entity should have a separate connection to that entity. If you use different Service Bus actions to send and receive messages, and those actions require different permissions, make sure to use different connections.

    For more information about managed identities, review Authenticate access to Azure resources with managed identities in Azure Logic Apps.

  • By default, the Service Bus built-in connector operations are stateless. To run these operations in stateful mode, see Enable stateful mode for stateless built-in connectors.

Considerations for Azure Service Bus operations

Infinite loops

Important

Use caution when you select both a trigger and action that have the same connector type and use them to work with the same entity, such as a messaging queue or topic subscription. This combination can create an infinite loop, which results in a logic app that never ends.

Limit on saved sessions in connector cache

Per Service Bus messaging entity, such as a subscription or topic, the Service Bus connector can save up to 1,500 unique sessions at a time to the connector cache. If the session count exceeds this limit, old sessions are removed from the cache. For more information, see Message sessions.

Send correlated messages in order

When you need to send related messages in a specific order, you can create a workflow using Service Bus connector and the sequential convoy pattern. Correlated messages have a property that defines the relationship between those messages, such as the ID for the session in Azure Service Bus.

When you create a Consumption logic app workflow, you can select the Correlated in-order delivery using service bus sessions template, which implements the sequential convoy pattern. For more information, see Send related messages in order.

Large message support

Large message support is available only for Standard workflows when you use the Service Bus built-in connector operations. For example, you can receive and large messages using the built-in triggers and actions respectively.

For the Service Bus managed connector, the maximum message size is limited to 1 MB, even when you use a premium tier Service Bus namespace.

Increase timeout for receiving and sending messages

In Standard workflows that use the Service Bus built-in operations, you can increase the timeout for receiving and sending messages. For example, to increase the timeout for receiving a message, change the following setting in the Azure Functions extension:

{
   "version": "2.0",
   "extensionBundle": {
      "id": "Microsoft.Azure.Functions.ExtensionBundle.Workflows",
      "version": "[1.*, 2.0.0)"
   },
   "extensions": {
      "serviceBus": {
         "batchOptions": {
            "operationTimeout": "00:15:00"
         }
      }  
   }
}

To increase the timeout for sending a message, add the ServiceProviders.ServiceBus.MessageSenderOperationTimeout app setting.

Service Bus managed connector triggers

  • For the Service Bus managed connector, all triggers are long-polling. This trigger type processes all the messages and then waits 30 seconds for more messages to appear in the queue or topic subscription. If no messages appear in 30 seconds, the trigger run is skipped. Otherwise, the trigger continues reading messages until the queue or topic subscription is empty. The next trigger poll is based on the recurrence interval specified in the trigger's properties.

  • Some triggers, such as the When one or more messages arrive in a queue (auto-complete) trigger, can return one or more messages. When these triggers fire, they return between one and the number of messages that's specified by the trigger's Maximum message count property.

    Note

    The auto-complete trigger automatically completes a message, but completion happens only at the next call to Service Bus. This behavior can affect your workflow design. For example, avoid changing the concurrency on the auto-complete trigger because this change might result in duplicate messages if your workflow enters a throttled state. Changing the concurrency control creates the following conditions:

    • Throttled triggers are skipped with the WorkflowRunInProgress code.

    • The completion operation won't run.

    • The next trigger run occurs after the polling interval.

    You have to set the service bus lock duration to a value that's longer than the polling interval. However, despite this setting, the message still might not complete if your workflow remains in a throttled state at next polling interval.

    However, if you turn on a Service Bus trigger's concurrency setting, the default value for the maximumWaitingRuns property is 10. Based on the Service Bus entity's lock duration setting and the run duration for your workflow, this default value might be too large and might cause a "lock lost" exception. To find the optimal value for your scenario, start testing with a value of 1 or 2 for the maximumWaitingRuns property. To change the maximum waiting runs value, review Change waiting runs limit.

Service Bus built-in connector triggers

Currently, configuration settings for the Service Bus built-in trigger are shared between the Azure Functions host extension, which is defined in your logic app's host.json file, and the trigger settings defined in your logic app's workflow, which you can set up either through the designer or code view. This section covers both settings locations.

  • In Standard workflows, some triggers, such as the When messages are available in a queue trigger, can return one or more messages. When these triggers fire, they return between one and the number of messages. For this type of trigger and where the Maximum message count parameter isn't supported, you can still control the number of messages received by using the maxMessageBatchSize property in the host.json file. To find this file, see Edit host and app settings for Standard logic apps.

    "extensions": {
      "serviceBus": {
          "maxMessageBatchSize": 25
      }
    }
    
  • You can also enable concurrency on the Service Bus trigger, either through the designer or in code:

    "runtimeConfiguration": {
        "concurrency": {
            "runs": 100
        }
    }
    

    When you set up concurrency using a batch, keep the number of concurrent runs larger than the overall batch size. That way, read messages don't go into a waiting state and are always picked up when they're read. In some cases, the trigger can have up to twice the batch size.

  • If you enable concurrency, the SplitOn limit is reduced to 100 items. This behavior is true for all triggers, not just the Service Bus trigger. Make sure the specified batch size is less than this limit on any trigger where you enable concurrency.

  • Some scenarios exist where the trigger can exceed the concurrency settings. Rather than fail these runs, Azure Logic Apps queues them in a waiting state until they can be started. The maximumWaitingRuns setting controls the number of runs allowed in the waiting state:

    "runtimeConfiguration": {
        "concurrency": {
            "runs": 100,
            "maximumWaitingRuns": 50
        }
    }
    

    With the Service Bus trigger, make sure that you carefully test these changes so that runs don't wait longer than the message lock timeout. For more information about the default values, see Concurrency and de-batching limits here.

  • If you enable concurrency, a 30-second delay exists between batch reads, by default. This delay slows down the trigger to achieve the following goals:

    • Reduce the number of storage calls sent to check the number of runs on which to apply concurrency.

    • Mimic the behavior of the Service Bus managed connector trigger, which has a 30-second long poll when no messages are found.

    You can change this delay, but make sure that you carefully test any changes to the default value:

    "workflow": {
        "settings": {
            "Runtime.ServiceProviders.FunctionTriggers.DynamicListenerEnableDisableInterval": "00:00:30"
        }
    }
    
    

Step 1: Check access to Service Bus namespace

To confirm that your logic app resource has permissions to access your Service Bus namespace, use the following steps:

  1. In the Azure portal, open your Service Bus namespace.

  2. On the namespace menu, under Settings, select Shared access policies. Under Claims, check that you have Manage permissions for that namespace.

    Screenshot showing the Azure portal, Service Bus namespace, and 'Shared access policies' selected.

Step 2: Get connection authentication requirements

Later, when you add a Service Bus trigger or action for the first time, you're prompted for connection information, including the connection authentication type. Based on your logic app workflow type, Service Bus connector version, and selected authentication type, you'll need the following items:

Managed connector authentication (Consumption and Standard workflows)

Authentication type Required information
Access Key The connection string for your Service Bus namespace. For more information, review Get connection string for Service Bus namespace
Microsoft Entra integrated The endpoint URL for your Service Bus namespace. For more information, review Get endpoint URL for Service Bus namespace.
Logic Apps Managed Identity The endpoint URL for your Service Bus namespace. For more information, review Get endpoint URL for Service Bus namespace.

Built-in connector authentication (Standard workflows only)

Authentication type Required information
Connection String The connection string for your Service Bus namespace. For more information, review Get connection string for Service Bus namespace
Active Directory OAuth - The fully qualified name for your Service Bus namespace, for example, <your-Service-Bus-namespace>.servicebus.chinacloudapi.cn. For more information, review Get fully qualified name for Service Bus namespace. For the other property values, review Microsoft Entra ID Open Authentication.
Managed identity The fully qualified name for your Service Bus namespace, for example, <your-Service-Bus-namespace>.servicebus.chinacloudapi.cn. For more information, review Get fully qualified name for Service Bus namespace.

Get connection string for Service Bus namespace

To create a connection when you add a Service Bus trigger or action, you need to have the connection string for your Service Bus namespace. The connection string starts with the sb:// prefix.

  1. In the Azure portal, open your Service Bus namespace.

  2. On the namespace menu, under Settings, select Shared access policies.

  3. On the Shared access policies pane, select RootManageSharedAccessKey.

  4. Next to the primary or secondary connection string, select the copy button.

    Screenshot showing the Service Bus namespace connection string and the copy button selected.

    Note

    To check that the string is for the namespace, not a specific messaging entity, search the connection string for the EntityPath parameter. If you find this parameter, the connection string is for a specific entity, and isn't the correct string to use with your workflow.

  5. Save the connection string for later use.

Get endpoint URL for Service Bus namespace

If you use the Service Bus managed connector, you need this endpoint URL if you select either authentication type for Microsoft Entra integrated or Logic Apps Managed Identity. The endpoint URL starts with the sb:// prefix.

  1. In the Azure portal, open your Service Bus namespace.

  2. On the namespace menu, under Settings, select Properties.

  3. Under Properties, next to the Service Bus endpoint, copy the endpoint URL, and save for later use when you have to provide the service bus endpoint URL.

Get fully qualified name for Service Bus namespace

  1. In the Azure portal, open your Service Bus namespace.

  2. On the namespace menu, select Overview.

  3. On the Overview pane, find the Host name property, and copy the fully qualified name, which looks like <your-Service-Bus-namespace>.servicebus.chinacloudapi.cn.

Step 3: Option 1 - Add a Service Bus trigger

The following steps use the Azure portal, but with the appropriate Azure Logic Apps extension, you can also use the following tools to create logic app workflows:

  1. In the Azure portal, open your Consumption logic app resource with blank workflow in the designer.

  2. In the designer, follow these general steps to add the Azure Service Bus trigger that you want.

    This example continues with the trigger named When a message is received in a queue (auto-complete).

  3. If prompted, provide the following information for your connection. When you're done, select Create.

    Property Required Description
    Connection name Yes A name for your connection
    Authentication Type Yes The type of authentication to use for accessing your Service Bus namespace. For more information, review Managed connector authentication.
    Connection String Yes The connection string that you copied and saved earlier.

    For example, this connection uses access key authentication and provides the connection string for a Service Bus namespace:

    Screenshot showing Consumption workflow, Service Bus trigger, and example connection information.

  4. After the trigger information box appears, provide the necessary information, for example:

    Property Required Description
    Queue name Yes The selected queue to access
    Queue type No The type for the selected queue
    How often do you want to check for items? Yes The polling interval and frequency to check the queue for items

    Screenshot showing Consumption workflow, Service Bus trigger, and example trigger information.

  5. To add any other available properties to the trigger, open the Add new parameter list, and select the properties that you want.

  6. Add any actions that your workflow needs.

    For example, you can add an action that sends email when a new message arrives. When your trigger checks your queue and finds a new message, your workflow runs your selected actions for the found message.

  7. When you're done, save your workflow. On the designer toolbar, select Save.

Step 3: Option 2 - Add a Service Bus action

The following steps use the Azure portal, but with the appropriate Azure Logic Apps extension, you can also use the following tools to create logic app workflows:

  1. In the Azure portal, open your Consumption logic app and workflow in the designer.

  2. In the designer, follow these general steps to add the Azure Service Bus action that you want.

    This example continues with the Send message action.

  3. If prompted, provide the following information for your connection. When you're done, select Create.

    Property Required Description
    Connection name Yes A name for your connection
    Authentication Type Yes The type of authentication to use for accessing your Service Bus namespace. For more information, review Managed connector authentication.
    Connection String Yes The connection string that you copied and saved earlier.

    For example, this connection uses access key authentication and provides the connection string for a Service Bus namespace:

    Screenshot showing Consumption workflow, Service Bus action, and example connection information.

  4. After the action information box appears, provide the necessary information, for example:

    Property Required Description
    Queue/Topic name Yes The selected queue or topic destination for sending the message
    Session Id No The session ID if sending the message to a session-aware queue or topic
    System properties No - None
    - Run Details: Add metadata property information about the run as custom properties in the message.

    Screenshot showing Consumption workflow, Service Bus action, and example action information.

  5. To add any other available properties to the action, open the Add new parameter list, and select the properties that you want.

  6. Add any other actions that your workflow needs.

    For example, you can add an action that sends email to confirm that your message was sent.

  7. When you're done, save your workflow. On the designer toolbar, select Save.

Service Bus built-in connector app settings

In a Standard logic app resource, the Service Bus built-in connector includes app settings that control various thresholds, such as timeout for sending messages and number of message senders per processor core in the message pool. For more information, review Reference for app settings - local.settings.json.

Read messages from dead-letter queues with Service Bus built-in triggers

In Standard workflows, to read a message from a dead-letter queue in a queue or a topic subscription, follow these steps using the specified triggers:

  1. In your blank workflow, based on your scenario, add the Service Bus built-in connector trigger named When messages are available in a queue or When a message are available in a topic subscription (peek-lock).

  2. In the trigger, set the following parameter values to specify your queue or topic subscription's default dead-letter queue, which you can access like any other queue:

    • When messages are available in a queue trigger: Set the Queue name parameter to queuename/$deadletterqueue.

    • When a message are available in a topic subscription (peek-lock) trigger: Set the Topic name parameter to topicname/Subscriptions/subscriptionname/$deadletterqueue.

    For more information, see Service Bus dead-letter queues overview.

Troubleshooting

Delays in updates to your workflow taking effect

If a Service Bus trigger's polling interval is small, such as 10 seconds, updates to your workflow might not take effect for up to 10 minutes. To work around this problem, you can disable the logic app resource, make the changes, and then enable the logic app resource again.

No session available

Occasionally, operations such as completing a message or renewing a session produce the following error:

{
  "status": 400,
  "message": "No session available to complete the message with the lock token 'ce440818-f26f-4a04-aca8-555555555555'. clientRequestId: facae905-9ba4-44f4-a42a-888888888888",
  "error": {
    "message": "No session available to complete the message with the lock token 'ce440818-f26f-4a04-aca8-555555555555'."
  }
}

The Service Bus connector uses in-memory cache to support all operations associated with the sessions. The Service Bus message receiver is cached in the memory of the role instance (virtual machine) that receives the messages. To process all requests, all calls for the connection get routed to this same role instance. This behavior is required because all the Service Bus operations in a session require the same receiver that receives the messages for a specific session.

The chance exists that requests might not get routed to the same role instance, due to reasons such as an infrastructure update, connector deployment, and so on. If this event happens, requests fail because the receiver that performs the operations in the session isn't available in the role instance that serves the request.

As long as this error happens only occasionally, the error is expected. When the error happens, the message is still preserved in the service bus. The next trigger or workflow run tries to process the message again.

Next steps