Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Microsoft Service Bus Connector

The ServiceBus connector enables message integration with Windows Service Bus on premises and Azure Service Bus on the cloud. The connector supports communication with queues, topics and event hubs through AMQP 1.0. In addition, dynamic discovery and provisioning of Service Bus objects is possible using the built-in management API.

The connector currently supports the following operations:

  • Send to Queues, Topics and Event Hubs with support of AMQP message properties and header, including custom properties.

  • Receive from Queues and Topics asynchronously

  • Rest Management API

  • CRUD for Queues

  • CRUD for Topics

  • CRUD for Subscriptions

  • CRUD for Rules   

The connector supports the following Service Bus versions:

  • Microsoft Azure Service Bus (Cloud)

  • Microsoft Windows Service Bus (on-premises)

Prerequisites

This document assumes that you are familiar with Mule, Anypoint Connectors, and the Anypoint Studio Essentials. To increase your familiarity with Studio, consider completing one or more Anypoint Studio Tutorials. Further, this page assumes that you have a basic understanding of Mule flows and Mule Global Elements.

Installing the Service Bus Connector

To install a connector, see To Install a Connector from Anypoint Exchange. == Using the Connector in Mule Flows

To use a Service Bus connector in a Mule application, follow the steps below.

Create a New Mule Project

To begin building this application, start Anypoint Studio and create a new project.

  1. Select File > New > Mule Project.

  2. In the New Mule Project configuration menu, provide a name for this project: service_bus_demo.

  3. Click Finish.

A new project opens with a blank canvas for building the flow, and the palette with Message Processors to the right.

Create a Mule Flow 

The following section is described using a demo Mule flow that is built to list all the existing queues in a service bus.

demo+flow

  1. Drag an HTTP connector into the canvas, and click to open the properties editor console.

  2. Click the green plus symbol:

    image:DotNetHTTP0.png[DotNetHTTP0]
  3. Configure the HTTP connector as follows:

  4. Hostlocalhost

  5. Port8081

  6. Path: servicebus

    DotNetHTTP1

  7. Search for a drag the Microsoft Service Bus connector into the canvas, and click to open the properties editor console.

  8. Click the Connection Configuration green arrow:

    ServiceBusGeneral

  9. Click the Service Bus type:

    ServiceBusGlobalType

  10. Azure Service Bus:

    ServiceBusAzure

    Field Description

    Name

    Enter a name for the global element.

    Service Namespace

    Enter the name of the service namespace to address Service Bus resources within your application.

    Shared Access Key Name

    Enter the name of access key configured on the namespace.

    Shared Access Key

    Enter the 256-bit primary key.

    Enable DataSense

    If you intend to employ the Microsoft Service Bus connector in conjunction with a DataMapper transformer to map and transform data, you can make use of Anypoint Studio’s DataSense functionality. You can enable DataSense as part of configuring the global element.

  11. Windows Service bus:

    ServiceBusWindowsGen

    Field Description

    Name

    Enter a name for the global element.

    Service Namespace

    Enter the name of the service namespace to address Service Bus resources within your application.

    Username

    Enter the user to use for authentication.

    Password

    Enter the password of the user.

    Shared Access Key Name

    Enter the name of access key configured on the namespace.

    Fully Qualified Domain Name

    Enter the fully qualified domain name of your Windows Service Bus server

    Port

    Enter the server port number.

    Disable SSL Certificate Validation

    If you are using a self-signed SSL certificate, select this check box.

    Enable DataSense

    If you intend to employ the Microsoft Service Bus connector in conjunction with a DataMapper transformer to map and transform data, you can make use of Anypoint Studio’s DataSense functionality. You can enable DataSense as part of configuring the global element.

  12. Configure the required parameters as shown below:

    Service+Bus+Config

    Parameter Value

    Display Name

    Microsoft Service Bus

    Connector Configuration

    Microsoft_Service_Bus_Azure_Service_Bus (Refer to Step 2 to learn how to create a global element)

    Operation

    Queues List

  13. Drag an Object to JSON transformer next to the Microsoft Service Bus connector.

For code samples that illustrate more advanced scenarios, refer to service-bus-connector-samples.zip

Running the Application

You are now ready to run the project! First, you can test run the application from Studio:

  1. Right-click your application in the Package Explorer pane.

  2. Select Run As > Mule Application:

  3. Start a browser and go to http://localhost:8081/servicebus.

  4. The list of existing queues should be returned in JSON format (results vary according to your Service Bus instance).

Service Bus Authentication

For sending and receiving messages through the Service Bus connector, the authentication is performed through AMQP.

For the REST Management API, the authentication scheme differs based on the Microsoft Service Bus version. The Windows Service Bus running on premises uses OAuth and the Azure Service Bus running on the cloud uses a Shared Access Key token.

The Windows Service Bus uses a self-signed SSL certificate to secure the communication via AMQP/HTTPS. The connector won’t run if this certificate is not locally imported in the box running Mule, unless the Ignore SSL warning check is enabled.

To enable the SSL checks, the certificate must be imported following these steps:

  1. Use the powershell cmdlet Get-SBAutoGeneratedCA to download the certificate locally in the box running the Windows Service Bus. For the purposes of this tutorial,  assume the certificate file is exported to %temp%\AutoGeneratedCA.cer.

  2. Go to %programfiles%\Java\jre7. Verify that the bin\keytool.exe tool exists, and that lib\security\cacerts exists. Note that you must be running as Administrator in order to perform a certificate import with Keytool.exe. Otherwise, an Access Denied error is generated.

  3. Enter the following command:*  bin\keytool.exe –list –keystore lib\security\cacerts.*

  4. Import the autogenerated Service Bus certificate by running the following command:

    
                
             
    1
    2
    
    bin\keytool.exe –importcert –alias AppServerGeneratedSBCA –file
    %temp%\AutoGeneratedCA.cer –keystore lib\security\cacerts –v
  5. You are prompted for the password (the default is “changeit”).  If you do not know the password, you cannot perform the import.  When the tool asks you whether to trust the certificate, enter Y (Yes).

AMQP Operations - Send to Queue Topic Event Hub

Property Usage

Destination Queue/Topic/Event Hub

The name of the destination of the message

Body

The content of the message

Header

The supported Header fields defined in the AMQP 1.0 standard

Properties

The supported Amqp Properties defined in the AMQP 1.0 Standard

The following message content types are supported by these operations : String, Stream, Map, Byte Array or any object that implements the serializable interface. An Exception is raised otherwise.

The Amqp Header fields defined in the AMQP 1.0 standard that can be specified in the processor are:

  • Durable: specify durability requirements

  • Priority: relative message priority

  • Ttl: time to live in ms

  • deliveryCount: the number of prior unsuccessful delivery attempts

The following Amqp Properties in the standard are supported and can be specified:

  • messageId: application message identifier

  • contentType: MIME content type

  • correlationId: application correlation identifier

  • to: the address of the node the message is destined for

  • replyTo: the node to send replies to

  • userId: creating user id 

  • subject: the subject of the message

Custom Properties:

Additional custom properties can be passed through the Mule Message properties to the processor. To do this, the property name of the Mule Message has to start with the “amqp.” prefix.

AMQP Operations - Receive from Queue/Topic

Property Usage

Source Topic/Queue

The name of the source from where the messages is retrieved

Subscription

In case of receiving messages from a topic, the name of the subscription from where the messages is retrieved has to be specified

To use these operations, the connector has to be an inbound endpoint. The Receive operations use asynchronous listeners to receive the messages. Once the message is received, the custom properties of the AMQP Message is transformed into Mule Message properties with the “amqp.” prefix, and the content of the message is passed as the payload.

Management API

Queues

ServiceBusQueue Object

The queue is represented by an object containing the following fields:

  • Id (String)

  • Title (String)

  • Published (Date)

  • Updated (Date)

  • Author (String)

  • Link (String)

  • Queue Description (ServiceBusQueueDescription)

ServiceBusQueueDescription Object

  • Lock Duration (String): Determines the amount of time in seconds in which a message should be locked for processing by a receiver. After this period, the message is unlocked and available for consumption by the next receiver. Settable only at queue creation time. 
    Valid values: Range: 0 – 5 minutes. 0 means that the message is not locked. 
    Format: PTx3Mx4S , where x1 is number of days, x2 is number of hours, x3 is number of minutes, x4 is number of seconds (Examples: PT5M (5 minutes) , PT1M30S (1 minute, 30 seconds)).

  • Max Size In Megabytes (Long): Specifies the maximum queue size in megabytes. Any attempt to enqueue a message that causes the queue to exceed this value will fail. Valid values are: 1024, 2048, 3072, 4096, 5120.

  • Size In Bytes (Long): Reflects the actual number of bytes that messages in the queue currently occupy toward the queue’s quota.

  • Message Count (Long): Displays the number of messages currently in the queue.

  • *Requires Duplicate Detectio*n (Boolean): Settable only at queue creation time.

  • Requires Session (Boolean): Settable only at queue creation time. If set this to true, the queue will be session-aware and only SessionReceiver is supported. Session-aware queues are not supported through REST.

  • Dead Lettering On Message Expiration (Boolean): This field controls how the Service Bus handles a message with an expired TTL. If it is enabled and a message expires, Service Bus moves the message from the queue into the queue’s dead-letter sub-queue. If disabled, message is permanently deleted from the queue. Settable only at queue creation time.

  • Enable Batched Operations (Boolean): Enables or disables service-side batching behavior when performing operations for the specific queue. When enabled, Service Bus collects/batches multiple operations to the back end, to be more efficient with the connection. If you want lower operation latency, you can disable this feature.

  • Default Message Time To Live (String): Depending on whether DeadLettering is enabled, a message is automatically moved to the DeadLetterQueue or deleted if it has been stored in the queue for longer than the specified time. This value is overwritten by a TTL specified on the message if and only if the message TTL is smaller than the TTL set on the queue. This value is immutable after the queue has been created.

  • Format: Px1DTx2Hx3Mx4S , where x1 number of days, x2 number of hours, x3 number of minutes, x4 number of seconds (Examples: PT10M (10 minutes), P1DT2H (1 day, 2 hours)

  • Duplicate Detection History Time Window (String): Specifies the time span during which Service Bus detects message duplication
    Valid values: Range: 1 second – 7 days.
    Format: Px1DTx2Hx3Mx4S , where x1 number of days, x2 number of hours, x3 number of minutes, x4 number of seconds (Examples: PT10M (10 minutes), P1DT2H (1 day, 2 hours)).

  • Max Delivery Count (Integer): The maximum number of times Service Bus tries to deliver a message before being it is discarded.

Create Queue

Property Usage

Queue Path

The name of the queue that is created

Queue Description

A ServiceBusQueueDescription object containing the desired values of the queue’s properties that is  created

Output: A ServiceBusQueue object containing the representation of the queue created

Get Queue

Property Usage

Queue Path

The name of the queue that is retrieved; DataSense is enabled on this field

Output: A ServiceBusQueue object containing the representation of the queue retrieved

List Queues:

Output:  A List of ServiceBusQueue object containing every existing queue

Update Queue:

Property Usage

Queue Path

The name of the queue that is updated; DataSense is enabled on this field

Queue Description

A ServiceBusQueueDescription object containing the desired values of the queue’s properties that is updated

Output: A ServiceBusQueue object containing the representation of the queue updated

Delete Queue

Property Usage

Queue Path

The name of the queue that is delete; DataSense is enabled on this field

ServiceBusTopic Object

The topic is represented by an object containing the following fields:

  • Id (String)

  • Title (String)

  • Published (Date)

  • Updated (Date)

  • Author (String)

  • Link (String)

  • Topic Description (ServiceBusTopicDescription)

ServiceBusTopicDescription Object

  • Max Size In Megabytes (Long): Specifies the maximum queue size in megabytes. Any attempt to enqueue a message that will cause the queue to exceed this value will fail. Valid values are: 1024, 2048, 3072, 4096, 5120

  • Size In Bytes (Long): Reflects the actual number of bytes that messages in the queue currently occupy toward the queue’s quota.

  • Requires Duplicate Detection (Boolean): If enabled, the topic detects duplicate messages within the time span specified by the DuplicateDetectionHistoryTimeWindow property. Settable only at topic creation time.

  • Enable Batched Operations (Boolean): Enables or disables service side batching behavior when performing operations for the specific queue. When enabled, Service Bus collects/batches multiple operations to the back end in order to be more connection efficient. If you want lower operation latency, you can disable this feature.

  • Default Message Time To Live (String):Determines how long a message lives in the associated subscriptions. Subscriptions inherit the TTL from the topic unless they are created explicitly with a smaller TTL. Based on whether dead-lettering is enabled, a message whose TTL has expired will either be moved to the subscription’s associated DeadLtterQueue or will be permanently deleted.

  • Format: Px1DTx2Hx3Mx4S , where x1 is number of days, x2 is number of hours, x3 is number of minutes, x4 is number of seconds (Examples: PT10M (10 minutes), P1DT2H (1 day, 2 hours)).

  • Duplicate Detection History Time Window (String): Specifies the time span during which Service Bus detects message duplication
    Valid values: Range: 1 second – 7 days.
    Format: Px1DTx2Hx3Mx4S , where x1 is number of days, x2 is number of hours, x3 is number of minutes, x4 is number of seconds (Examples: PT10M (10 minutes), P1DT2H (1 day, 2 hours)).

    === Create Topic

Property Usage

Topic Path

The name of the topic that is retrieved

Topic Description

A ServiceBusTopicDescription object containing the desired values of the properties of the topic that is created

Output: A ServiceBusTopic object containing the representation of the created topic

Get Topic

Parameter Usage

Topic Path

The name of the topic that is retrieved; DataSense is enabled on this field

Output :  A ServiceBusTopic object containing the representation of the retrieved topic

List Topics

Output: A List of ServiceBusTopic object containing every existing topic

Update Topic

Property Usage

Topic Path

The name of the topic that is updated; DataSense is enabled on this field

Topic Description

A ServiceBusTopicDescription object containing the desired values of properties of the topic that is updated

Output: A ServiceBusTopic Object containing the representation of the updated topic

Delete Topic

Property Usage

Topic Path

The name of the topic that is be deleted; DataSense is enabled on this field

Subscriptions

ServiceBusSubscription Object

The subscription is represented by an object containing the following fields:

  • Id (String)

  • Title (String)

  • Published (Date)

  • Updated (Date)

  • Link (String)

  • Subscription Description (ServiceBusSubscriptionDescription)

ServiceBusSubscriptionDescription Object

  • Lock Duration (String): The default lock duration is applied to subscriptions that do not define a lock duration. You can only set this property at subscription creation time.
    Valid values: Range: 0 – 5 minutes. 0 means that the message is not locked.
    Format: PTx3Mx4S , where x1 number of days, x2 number of hours, x3 number of minutes, x4 number of seconds (Examples: PT5M (5 minutes) , PT1M30S (1 minute, 30 seconds)).

  • Message Count (Long): Reports the number of messages in the queue as reported by the monitoring system.

  • Requires Session (Boolean): You can only set this property at subscription creation time. If set to true, the subscription will be session-aware and only SessionReceiver will be supported. Session-aware subscriptions are not supported through REST.

  • Dead Lettering On Message Expiration (Boolean): This field controls how Service Bus handles a message with an expired TTL. If it is enabled and a message expires, Service Bus moves the message from the queue into the subscription’s dead-letter sub-queue. If disabled, message is permanently deleted from the subscription’s main queue. Settable only at subscription creation time.

  • Dead Lettering On Filter Evaluation Exceptions (Boolean): Determines how Service Bus handles a message that causes an exception during a subscription’s filter evaluation. If the value is set to true, the message that caused the exception is moved to the subscription’s dead-letter queue. Otherwise, it is discarded. By default, this parameter is set to true, enabling you to investigate the cause of the exception. It can occur from a malformed message or some incorrect assumptions being made in the filter about the form of the message. Settable only at subscription creation time.

  • Enable Batched Operations (Boolean): Enables or disables service-side batching behavior when performing operations for the specific queue. When enabled, Service Bus will collect/batch multiple operations to the backend to be more connection efficient. If you want lower operation latency, then you can disable this feature.

  • Default Message Time To Live (String): Determines how long a message lives in the subscription. Based on whether dead-lettering is enabled, a message whose Time To Live (TTL) has expired is either moved to the subscription’s associated DeadLetterQueue, or permanently deleted. If the topic specifies a smaller TTL than the subscription, the topic TTL is applied.
    Format: Px1DTx2Hx3Mx4S , where x1 number of days, x2 number of hours, x3 number of minutes, x4 number of seconds (Examples: PT10M (10 minutes), P1DT2H (1 day, 2 hours)

  • Max Delivery Count (Integer): The maximum number of times Service Bus tries to deliver a message before that message is dead lettered or discarded.

Create Subscription

Property Usage

Topic Path

The name of the topic where the subscription is created

Subscription Path

The name of the subscription that is created

Subscription Description

A ServiceBusSubscriptionDescription object containing the desired values of the properties of the subscription that is created

Output: A ServiceBusSubscription object containing the representation of the created subscription

Get  Subscription

Property Usage

Topic Path

The name of the topic from where the subscription that is retrieved; DataSense is enabled on this field

Subscription Path

The name of the subscription that is retrieved

Output:  A ServiceBusSubscription Object containing the representation of the retrieved subscription

List Subscriptions

Property Usage

Topic Path

The name of the topic from where the subscriptions are retrieved; DataSense is enabled on this field

Output :   A List of ServiceBusSubscription Object containing every existing subscription in the topic

Update Subscription

Property Usage

Topic Path

The name of the topic where the subscription is updated; DataSense is enabled on this field

Subscription Path

The name of the subscription that is updated

Subscription Description

A ServiceBusSubscriptionDescription object containing the desired values of the subscription’s properties that will be updated

Output:  A ServiceBusSubscription Object containing the representation of the updated subscription

Rules

ServiceBusRule Object

It represents a rule for processing messages. Service Bus matches messages with the filter represented by its Filter property and performs action represented by its Action property, against the messages that matched the filter.

  • Id (String)

  • Title (String)

  • Published (Date)

  • Updated (Date)

  • Link (String)

  • Rule Description (ServiceBusRuleDescription)

ServiceBusRuleDescription Object

  • Filter (ServiceBusRuleFilter): If left empty, no filter is applied

  • Action (ServiceBusRuleAction): If left empty, no action is  performed

ServiceBusRuleFilter Object

Sql Expression (String): The sql expression for filtering messages. You must select SqlFilter in the filter type for it to be applied. Example: MyProperty = 'value'.

Correlation Id (String): The id to match in case the filter is a CorrelationFilter

Type (ServiceBusRuleFilterType): Valid values are:

  • SqlFilter: A type of Filter that is represented by SQL expression

  • TrueFilter/FalseFiilter: A handy shortcut for returning true or false; they are a type of SqlFilter

  • CorrelationFilter: A type of Filter that matches CorrelationId property of BrokeredMessage

ServiceBusRuleAction Object

  • Sql Expression (String): The sql expression of the action to be performed. Example: SET MyProperty = 'ABC'

  • Type(ServiceBusRuleActionType): Valid values are:

    • SqlFilterAction: A type of FilterAction that is represented by SQL expression

    • EmptyRuleAction: A type of FilterAction that represents an empty action

Create Rule

Property Usage

Topic Path

The name of the topic which has the subscription for the rule that is created

Subscription Path

The name of the subscription where the rule is created

Rule Path

The name of the rule that is created

Rule Description

A ServiceBusRuleDescription object containing the desired values of the  properties of the rule that is created

Output: A ServiceBusRule Object containing the representation of the created rule.

Get Rule

Property Usage

Topic Path

The name of the topic which has the subscription from where the rule is retrieved

Subscription Path

The name of the subscription from where the rule is retrieved

Rule Path

The name of the rule that is retrieved

Output: A ServiceBusRule Object containing the representation of the retrieved rule

List Rules

Property Usage

Topic Path

The name of the topic which has the subscription from where the rule is retrieved

Subscription Path

The name of the subscription from where the rules need to be retrieved

  *Output*: A List of ServiceBusRule Object containing every existing rule in the specified subscription and topic

Update Rule

Property Usage

Topic Path

The name of the topic which has the subscription where the rule is updated

Subscription Path

The name of the subscription where the rule is updated

Rule Path

The name of the rule that is updated

Rule Description

A ServiceBusRuleDescription object containing the desired values of the  properties of the rule that is updated

Output: A ServiceBusRule Object containing the representation of the created rule

Delete Rule

Property Usage

Topic Path

The name of the topic which has the subscription where the rule is deleted

Subscription Path

The name of the subscription where the rule is deleted

Rule Path

The name of the rule that is deleted

See Also