Contact Free trial Login

Microsoft Service Bus Connector 2.1 - Mule 4

Support Category: Select

Anypoint Connector for Microsoft Service Bus (Microsoft Service Bus Connector) enables message integration with Windows Service Bus on-premises. The connector supports communication with queues and topics through Advanced Message Queuing Protocol (AMQP) 1.0. In addition, dynamic discovery and provisioning of Service Bus objects is possible using the built-in management API.

This connector supports connecting only to the Microsoft Windows Service Bus on-premises solution. To connect to Microsoft Azure Service Bus, use Anypoint Connector for Azure Service Bus.

Prerequisites

To use this information, you should be familiar with Microsoft Service Bus, Mule runtime engine (Mule), Anypoint Connectors, Anypoint Studio, Mule concepts, elements in a Mule flow, and Global Elements.

You need one of the following credential types to test your connection to your target resource:

  • Windows credentials type

  • SAS (shared access signature) - Deprecated

  • Username and password - Deprecated

For software requirements and compatibility information, see the Connector Release Notes.

To use this connector with Apache Maven, click the Dependency Snippets link in Anypoint Exchange.

The connector supports the Microsoft Windows Service Bus on-premises.

POM File Information

<dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-microsoft-service-bus-connector</artifactId>
  <version>RELEASE</version>
  <classifier>mule-plugin</classifier>
</dependency>

Mule converts RELEASE to the latest version. To specify a version, view Microsoft Service Bus Connector in Anypoint Exchange and click Dependency Snippets.

Connect in Flow Designer

  1. In Flow Designer, click one of the following triggers:

    • Microsoft Windows Service Bus Connector: Listen for changes in a queue, topic, or a custom object.

    • HTTP Listener: Listen for input from a browser, or a command such as curl or Postman.

    • Scheduler: Activate your app at specified time intervals.

      Trigger options
  2. Select the plus sign to add a component.

    add connector
  3. Select the connector as a component.

  4. Configure one of Global elements for the connector:

    • Configuration

      Configuration
      General

      Field

      Description

      Connection Type

      The type of connection:

      • Windows

      • Shared Access Signature (Deprecated)

      • Username and Password (Deprecated)

      Encoding

      The default encoding of the message body to be used if the message doesn’t communicate it.

      Content Type

      The default contentType of the message body to be used if the message doesn’t communicate it.

      Ack Mode

      The Session ACK mode to use when consuming a message.

      Consumer Type

      Used by default when consuming a message that can be overridden at the message source level.

      Persistent Delivery

      If true, the message is sent using the PERSISTENT JMSDeliveryMode.

      Priority

      The default JMSPriority value to be used when sending the message.

      Time To Live

      Defines the default time the message ise in the broker before it expires and is discarded.

      Time To Live Unit

      Time unit to be used in the Time To Live configurations.

      Disable Message Id

      If true, the message is flagged to avoid generating its MessageID.

      Disable Message Timestamp

      If true, the message is flagged to avoid generating its sent Timestamp.

      Delivery Delay

      Sets the delivery delay to be applied to postpone the message delivery.

      Delivery Delay Unit

      Time unit to be used in the Delivery Delay configurations.

      Jms Type

      The message type identifier to be set in the JMS type header when a message is sent.

      Queue Prefetch

      Number of messages that the remote peer can send to the client and hold in a prefetch buffer for each consumer instance.

      • Windows Connection

        General
        Connection
        General

        Field

        Description

        Connection Type

        Windows

        Connection

        Field

        Description

        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.

        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.

        Skip connectivity test

        In case you have limited access to Windows Service Bus resources and you want to skip the connectivity test performed at startup you need to set this setting to true.

Connector-Specific Input Source

Microsoft Service Bus Connector has one connector-specific input source (trigger) named Listener. To configure this input source in Flow Designer:

  1. Click the trigger card for the Listener trigger.

  2. In the Reply To section, enter the destination for the message.

  3. In the Destination information section, select a value for the Destination Type field to indicate whether the trigger listens for new or modified queues, topics, or a custom destination type.

  4. Enter values for these parameters:

    Field Description

    Source Type

    Indicates whether to retrieve messages from a queue or topic

    Destination

    Name of the destination queue, topic, or custom destination type from which messages are retrieved

    Subscription

    Name of the subscription to use when subscribing to topics. If the destination is a queue, select NONE.

  5. Optionally enter values for the other parameters.

Add the Connector to a Studio Project

Anypoint Studio provides two ways to add the connector to your Studio project: from the Exchange button in the Studio taskbar or from the Mule Palette view.

Add the Connector Using Exchange

  1. In Studio, create a Mule project.

  2. Click the Exchange icon (X) in the upper-left of the Studio task bar.

  3. In Exchange, click Login and supply your Anypoint Platform username and password.

  4. In Exchange, search for "service bus".

  5. Select the connector and click Add to project.

  6. Follow the prompts to install the connector.

Add the Connector in Studio

  1. In Studio, create a Mule project.

  2. In the Mule Palette view, click (X) Search in Exchange.

  3. In Add Modules to Project, type "service bus" in the search field.

  4. Click this connector’s name in Available modules.

  5. Click Add.

  6. Click Finish.

Configure in Studio

  1. Drag a connector’s operation to the Studio Canvas.

  2. Configure the Global element for the connector.

    Configuration values for each Connection type are the same as in the To Connect in Design Center section.

General

Get Queue List Use Case

This use case retrieves a list of existing queues in a specific namespace. It returns the list in JSON format.

General
  1. Create a new Mule application in Studio and select HTTP Listener as a source in the new flow.

  2. Add a new HTTP Listener configuration global element:

  3. Specify the Host and Port parameters with the following values:

    Parameter Value

    Host

    0.0.0.0

    Port

    8081

  4. Click Save.

  5. Assign the new global configuration to HTTP Listener.

  6. Complete the HTTP Listener path with the value /servicebus.

  7. Drag a new Service Bus component operation into the flow.

  8. Configure the Service Bus connector global element with its environment values.

  9. Add a transform message before the connector and add an output like this:

    %dw 2.0
    output application/json
    ---
    payload
  10. Save and run the project as a Mule application.

    To test the app, navigate to http://127.0.0.1:8081/servicebus.

XML flow:

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:servicebus="http://www.mulesoft.org/schema/mule/servicebus"
	xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
	http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/servicebus
http://www.mulesoft.org/schema/mule/servicebus/current/mule-servicebus.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
	<configuration-properties file="mule-app.properties" />
	<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<servicebus:config name="Servicebus_Config" doc:name="Servicebus Config" >
		<servicebus:windows-connection
		namespace="${config.namespace}"
		username="${config.username}"
		password="${config.password}"
		fqdn="${config.fqdn}" />
	</servicebus:config>
	<flow name="servicebusFlow">
		<http:listener doc:name="Listener" config-ref="HTTP_Listener_config"
		path="/servicebus"/>
		<servicebus:queues-list doc:name="Queues list" config-ref="Servicebus_Config"/>
		<ee:transform doc:name="Object to JSON">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
	</flow>
</mule>

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 uses OAuth.

The Windows Service Bus uses a self-signed SSL certificate to secure the communication via AMQP and 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: bin\keytool.exe –importcert –alias AppServerGeneratedSBCA –file %temp%\AutoGeneratedCA.cer –keystore lib\security\cacerts –v

  5. Enter the password when prompted (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).

Using Restricted Access Policies

In cases where you have restrict access to your resources, having a security policy with permissions just at resource level, the connector cannot perform the connectivity test when it is starting up as this targets the root level of your namespace which might be forbidden due to the customized policy applied to the shared access key. For these scenarios, you need to skip the connectivity test with the configuration option available to this purpose, otherwise connetor’s startup fails.

Log Requests and Responses

To log requests and responses when using the connector, configure a logger by adding this line to the Loggers element of the log4j2.xml configuration file for the Mule app:

<AsyncLogger name="org.springframework.web.client"
   level="DEBUG"/>

The following example shows the Loggers element with the AsyncLogger line added:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
	<Appenders>
	    <Console name="Console" target="SYSTEM_OUT">
	    	<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
		</Console>
	</Appenders>
	<Loggers>
		<AsyncLogger name="org.springframework.web.client" level="DEBUG" additivity="false">
			<appender-ref ref="Console" level="debug"/>
		</AsyncLogger>
	</Loggers>
</Configuration>

You can view the app log as follows:

  • If you’re running the app from the Anypoint Platform, the output is visible in the Anypoint Studio console window.

  • If you’re running the app using Mule from the command line, the app log is visible in your OS console.

Unless the log file path was customized in the app’s log file (log4j2.xml), you can also view the app log in this default location:

MULE_HOME/logs/<app-name>.log

For more information about the app log, see Configuring Logging.

Windows Service Bus AMQP Use Case

This use case contains the following flows that send and receive messages for topics and queues:

  • load-http-form-flow

    Provides a web form for entering the parameters for messages.

  • topic-endpoint-flow

    Receives messages through the load-http-form-flow, stores each message as the payload, converts each message to a Java object, and sends each message to the destination topic.

  • queue-endpoint-flow

    Receives messages through the load-http-form-flow, stores each message as the payload, converts each message to a Java object, and sends each message to the destination queue.

  • queue-receive-flow

    Listens for, receives, and logs messages from the specified queue.

  • topic-receive-flow

    Listens for, receives, and logs messages from the specified topic.

Studio 7 flows for the Windows Service Bus AMQP demo

XML for this flow:

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:servicebus="http://www.mulesoft.org/schema/mule/servicebus"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/servicebus
http://www.mulesoft.org/schema/mule/servicebus/current/mule-servicebus.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
	<configuration-properties file="mule-app.properties" doc:name="Configuration properties"/>
	<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config">
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<servicebus:config name="Microsoft_Service_Bus_Config" doc:name="Microsoft Service Bus Config">
		<servicebus:windows-connection
			namespace="${windows.namespace}"
			username="${windows.username}"
			password="${windows.password}"
			fqdn="${windows.fqdn}"
			port="${windows.port}"/>
	</servicebus:config>
	<flow name="load-http-form-flow">
		<http:listener doc:name="Root Endpoint" config-ref="HTTP_Listener_config"
			path="/" />
		<parse-template doc:name="Web Form" location="form.html" />
	</flow>
	<flow name="queue-endpoint-flow">
		<http:listener doc:name="Queue Endpoint" config-ref="HTTP_Listener_config"
			path="/pushMessageQueue" />
		<ee:transform doc:name="Convert Payload to Java Object">
			<ee:message>
				<ee:set-payload><![CDATA[%dw 2.0
output application/java
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<servicebus:queue-send doc:name="Queue send" config-ref="Microsoft_Service_Bus_Config"
			destinationQueue="#[payload.queue]">
			<servicebus:message >
				<servicebus:body ><![CDATA[#[payload.message]]]></servicebus:body>
			</servicebus:message>
		</servicebus:queue-send>
	</flow>
	<flow name="topic-endpoint-flow">
		<http:listener doc:name="Topic Endpoint" config-ref="HTTP_Listener_config"
			path="/pushMessageTopic"/>
		<ee:transform doc:name="Convert Payload to Java Object">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<servicebus:topic-send doc:name="Topic send" config-ref="Microsoft_Service_Bus_Config"
			destinationTopic="#[payload.topic]"
			transactionalAction="NOT_SUPPORTED"
			sendCorrelationId="AUTO">
			<servicebus:message >
				<servicebus:body ><![CDATA[#[payload.message]]]></servicebus:body>
			</servicebus:message>
		</servicebus:topic-send>
	</flow>
	<flow name="queue-receive-flow">
		<servicebus:listener
			sourceType="Queue"
			destination="${queue.name}"
			doc:name="Queue receive"
			config-ref="Microsoft_Service_Bus_Config"
			ackMode="AUTO" subscription="NONE"
			numberOfConsumers="1"/>
		<logger level="INFO" doc:name="Log the message" message="#[payload]"/>
	</flow>
	<flow name="topic-receive-flow">
		<servicebus:listener sourceType="Topic" doc:name="Topic receive"
			config-ref="Microsoft_Service_Bus_Config"
			ackMode="AUTO" destination="${topic.name}"
			subscription="${subscription.name}"/>
		<logger level="INFO" doc:name="Log the message" message="#[payload]"/>
	</flow>
</mule>

Windows Service Bus Management Use Case

This use case contains flows that create topics, subscriptions, and rules:

  • service-bus-management-demoFlow

    Creates a topic by following these steps:

    1. Creates the topic description as specified and stores it as the payload.

    2. Creates the topic using the stored configuration from the previous step and the topic namespace, obtained from variable topic.name.

    3. Converts the newly created topic to a JSON object.

    4. Logs the JSON object.

  • service-bus-management-demoFlow1

    Creates a subscription by following these steps:

    1. Creates the subscription description as specified and stores it as the payload.

    2. Creates the subscription using the stored configuration from the previous step, the subscription name from the variable subscription.name, and the topic name from the variable topic.name.

    3. Converts the newly created subscription to a JSON object.

    4. Logs the JSON object.

  • service-bus-management-demoFlow2

    Creates a rule by following these steps:

    1. Creates a rule with the specified configuration and stores it as the payload.

    2. Creates the rule using the stored configuration from the previous step, the rule name from the variable rule.name, the subscription name from the variable subscription.name, and the topic name from the variable topic.name.

    3. Converts the newly created rule to a JSON object.

    4. Logs the JSON object.

Service Bus Management Studio 7 Flow

XML flow:

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:servicebus="http://www.mulesoft.org/schema/mule/servicebus"
	xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
	http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/servicebus
http://www.mulesoft.org/schema/mule/servicebus/current/mule-servicebus.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
	<configuration-properties file="mule-app.properties"
	doc:name="Configuration properties"/>
	<http:listener-config name="HTTP_Listener_config"
	doc:name="HTTP Listener config">
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<servicebus:config name="Microsoft_Service_Bus_Config" doc:name="Microsoft Service Bus Config">
		<servicebus:windows-connection
			namespace="${windows.namespace}"
			username="${windows.username}"
			password="${windows.password}"
			fqdn="${windows.fqdn}"
			port="${windows.port}"/>
	</servicebus:config>
	<flow name="service-bus-management-demoFlow">
		<http:listener doc:name="Topic Create Endpoint"
		config-ref="HTTP_Listener_config"
		path="/topic"/>
		<ee:transform doc:name="Set ServiceBusTopicDescription">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
{
	defaultMessageTimeToLive: "P10675199DT2H48M5.4775807S",
	duplicateDetectionHistoryTimeWindow: "PT10M",
	enableBatchedOperations: false,
	maxSizeInMegabytes: 1024,
	requiresDuplicateDetection: false,
	sizeInBytes: null
} as Object {
	class : "com.mulesoft.connectors.microsoft.servicebus.extension.api.entity.ServiceBusTopicDescription"
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<servicebus:topic-create doc:name="Topic create"
		config-ref="Microsoft_Service_Bus_Config"
		topicPath="${topic.name}">
		</servicebus:topic-create>
		<ee:transform doc:name="Object to Json">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
	author: payload.author,
	id: payload.id,
	title: payload.title
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<logger level="INFO" doc:name="Logger" message="#[payload]"/>
	</flow>
	<flow name="service-bus-management-demoFlow1">
		<http:listener doc:name="Subscription Create Endpoint"
		config-ref="HTTP_Listener_config"
		path="/subscription"/>
		<ee:transform doc:name="Set ServiceBusSubscriptionDescription">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
{
	lockDuration: "PT4M",
	requiresSession: false,
	deadLetteringOnMessageExpiration: false,
	deadLetteringOnFilterEvaluationExceptions: null,
	enableBatchedOperations: false,
	defaultMessageTimeToLive: "P10675199DT2H48M5.4775807S",
	maxDeliveryCount: null
} as Object {
	class : "com.mulesoft.connectors.microsoft.servicebus.extension.api.entity.ServiceBusSubscriptionDescription"
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<servicebus:subscription-create
		topicPath="${topic.name}"
		doc:name="Subscription create"
		config-ref="Microsoft_Service_Bus_Config"
		subscriptionPath="${subscription.name}"/>
		<ee:transform doc:name="Object to Json">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
	linik: payload.link,
	id: payload.id,
	title: payload.title
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<logger level="INFO" doc:name="Logger" message="#[payload]"/>
	</flow>
	<flow name="service-bus-management-demoFlow2">
		<http:listener doc:name="Rule Create Endpoint"
		config-ref="HTTP_Listener_config"
		path="/rule"/>
		<ee:transform doc:name="Set ServiceBusRuleDescription">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
{
	action: {
		sqlExpression: "set MyProperty2 = 'ABC'",
		"type": "SqlRuleAction"
	},
	filter: {
		correlationId: null,
		sqlExpression: "property1 = 'ok'",
		"type": "SqlFilter"
	}
} as Object {
	class : "com.mulesoft.connectors.microsoft.servicebus.extension.api.entity.ServiceBusRuleDescription"
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<servicebus:rule-create topicPath="${topic.name}" doc:name="Rule create"
		config-ref="Microsoft_Service_Bus_Config" rulePath="${rule.name}"
		subscriptionPath="${subscription.name}"/>
		<ee:transform doc:name="Object to Json">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
	link: payload.link,
	id: payload.id,
	title: payload.title
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<logger level="INFO" doc:name="Logger" message="#[payload]"/>
	</flow>
</mule>

Troubleshooting

If the Mule app includes the Listener source, you might receive an error like this:

javax.jms.JMSException: The operation did not complete within the allocated time 00:00:14.9951934 for object connection

If you receive this error when starting the app or calling an operation, check whether the Service Bus server has the Redirect feature enabled. If so, disable this feature by following the steps documented in the Known Issues section on this page: AMQP Java clients (and all non .NET clients) cannot send or receive to/from Service Bus.