Skip to main content

Service Bus Trigger

Start a Process by receiving a message from a Service Bus.

Ossi Galkin avatar
Written by Ossi Galkin
Updated over a year ago

Service Bus Triggers are similar to Queue Triggers in that they allow you to trigger Processes on messages received from a message queue. In this case, the messages are from an Azure Service Bus or Service Bus for Windows Server queue or subscription.

Note: The Service Bus Trigger cannot accept message sessions, so it cannot listen to queues or subscriptions requiring sessions. However, it can send replies to session queues, as described below.

Configuring Service Bus Triggers

  • Queue (required)
    Name of the queue or subscription to listen to.

  • Connection string (required; if not set, it will default to the system Service Bus namespace)
    The full Service Bus connection string.

  • Max concurrent connections
    Limit on how many messages will be processed at a time. Essentially, this will limit the number of Processes running at the same time on a single Agent.

  • Message prefetch count
    If set, message prefetching for the receiver will be enabled. If you are receiving a lot of messages from the queue, it is recommended to turn prefetching on. Note that the prefetch count should still be low enough so that the messages can be processed in time.

  • Consume message immediately
    If set, the message will be consumed from the queue immediately upon receipt. If not set, the listener will use the PeekLock receive mode and acknowledge the message only if it was processed successfully. The lock will be refreshed according to the lock duration defined for the queue. However, if the connection string does not have management access to the Service Bus, the lock duration cannot be read, and the lock is assumed to have a duration of one minute. If the lock is shorter than a minute, the lock might get released before the Process has finished executing. For example, if the Agent crashes before the Process finishes, the message will be returned to the queue and will be processed again. In this case, the Trigger will retry processing the message after the lock expires, until the max delivery count on the queue or subscription is reached.

  • Retry message processing if an exception is thrown (from 5.1.1)
    If the 'Consume message immediately' option is set, it will not by default return messages to the queue if the Process execution ends in an exception. This is to reduce problems with messages being processed again inadvertently. If you turn this option on, and the Process ends in an exception (e.g., due to a query timeout in a Task), the message lock will be released immediately. Therefore, the message will be returned to the queue and will be processed again by a new Process instance. If the next Process instance also fails, the lock will not be released, but it is left to expire. This means the message will be processed again after the lock interval (1-5 minutes) has passed. If the message processing fails for the fifth time, the message will be put into the dead-letter queue and will not be processed again automatically.

  • Reply
    If set, the Process response will be sent to a reply queue, usually defined by the ReplyTo property in the request message. See Reply messages below for more information.

  • Reply errors
    If set and the Process fails with an exception, the exception message will be serialized and sent to the reply queue. See Reply messages below for more information.

  • Default reply queue
    Needed if the 'Reply' option is set. The default queue or topic where the reply message will be sent if the request did not specify it with the ReplyTo property in the request. See Reply messages below for more information.

Trigger data for the Process

The Trigger will pass the message content serialized as a string to the Process. It can be accessed via the #trigger.data.body reference.

The Trigger will also populate the #trigger.data.properties dictionary with the message properties. Any custom properties will be included in the list by name and value. The built-in message properties are also accessible; they are prefixed with the "BrokerProperties." prefix. The following properties are available:

  • #trigger.data.properties["BrokerProperties.CorrelationId"] - Correlation ID

  • #trigger.data.properties["BrokerProperties.SessionId"] - Session ID

  • #trigger.data.properties["BrokerProperties.DeliveryCount"] - Delivery count, i.e., how many times the message has been received from the queue.

  • #trigger.data.properties["BrokerProperties.LockedUntilUtc"] - Message lock timeout if not consuming the message immediately.

  • #trigger.data.properties["BrokerProperties.LockToken"] - Message lock token if not consuming the message immediately.

  • #trigger.data.properties["BrokerProperties.MessageId"] - Message ID

  • #trigger.data.properties["BrokerProperties.Label"] - Label given to the message.

  • #trigger.data.properties["BrokerProperties.ReplyTo"] - Queue name where to send replies. See Reply messages below for more information.

  • #trigger.data.properties["BrokerProperties.ReplyToSessionId"] - Session ID to set in the reply so the caller can identify it. See Reply messages below for more information.

  • #trigger.data.properties["BrokerProperties.ContentType"] - Body content type.

Reply messages

Sometimes you need to reply back to the sender of a request, for example, when the caller needs to wait for the triggered Process to finish or needs the results. In this case, you can turn on replies on the Service Bus Trigger, which will return the Process result in a message that is put into the given reply queue.

The request-reply process usually goes as follows:

  • The caller decides on a session ID and queue for receiving the reply. They set these as the ReplyToSessionId and ReplyTo properties in the request message and send the message to the queue listened to by the Trigger. The caller then starts listening on the reply queue, accepting only the message session with the given session ID. This ensures that the caller only receives the response meant for them, even from a shared queue.

  • The Trigger receives the request and starts a new Process instance, passing the message body and properties as Trigger properties to the Process.

  • Once the Process has finished, if the 'Reply' option is set, the Trigger creates the response message. The response message has the serialized result in the message body, with the SessionId set to the given ReplyToSessionId value from the request and CorrelationId set to the CorrelationId value from the request. The response is then sent to the queue or topic given in the ReplyTo property, or if the request did not define one, to the default queue for replies, configured in the Trigger.

  • The caller receives the reply message in the session.

If the Process fails and 'Reply Errors' was selected, the exception that caused the failure is written to the reply message. The message also has the SessionId and CorrelationId set if required.

Did this answer your question?