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

MSMQ Connector User Guide

Solution Overview

The Microsoft Message Queuing (MSMQ) connector uses a typical client-server architecture with two tiers, the connector or client running in Mule, and the Anypoint Gateway running on the server side. The latter exposes an HTTP Web API for sending or receiving messages from MSMQ.

The following is a high-level diagram of the solution architecture:

1

The Anypoint Gateway leverages the following technologies/frameworks:

  • ASP.NET Web API exposes an HTTP web API that sends and receives raw messages.

  • OWIN provides the HTTP layer. Open Web Interface for .NET (OWIN) is an open specification for decoupling applications from web server functionality, which provides a layer for making all the HTTP concerns independent of the hosting platform.

  • Katana provides the OWIN Microsoft implementation, which handles self and IIS hosting for OWIN applications.

Primary Use Cases

The MSMQ connector supports two primary use cases:

  • Sends (HTTP POST) a single message MSMQ.

  • Receives (HTTP GET) one or more messages from MSMQ.

HTTP POST Scenario

In the POST scenario, Mule uses the connector to send a raw representation of the Mule Message in the current flow to MSMQ using HTTP to the Anypoint Gateway. The message is sent as an HTTP POST. The payload of the HTTP request is serialized payload of the Mule message (binary or text). The Web API runs on the Anypoint Gateway and forwards the message to a queue using MSMQ.

The following messages show the structure of the HTTP POST request.

Post Request Message


          
       
1
2
3
4
5
POST: https://localhost:9000/msmq
Authorization: mule test-token
Mule-Msmq-Queue-Name: .\private$\qout
Mule-Api-Version: 1
Body: THIS IS A SAMPLE MESSAGE

POST Response Message


          
       
1
Http /1.1 201 Created

HTTP GET Scenario

In the GET scenario, Mule uses the connector to receive one or more messages from MSMQ. This is done as an HTTP GET to the Anypoint Gateway. The Web API runs in the gateway and returns the available messages in a MSMQ queue. The messages are returned in a single HTTP response using a MIME multipart/mixed content type.

The following messages illustrates the structure of the HTTP GET requests.

GET Request Message


          
       
1
2
3
4
GET: https://localhost:9000/msmq?count=50
Authorization: mule test-token
Mule-Msmq-Queue-Name: .\private$\out
Mule-Api-Version: 1

GET Response Message


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
Transfer-Encoding: chunked
Content-Type: multipart/mixed; boundary="47c7462b-f831-48f5-aed2-a561ef31dcc6"
 
 
28
--47c7462b-f831-48f5-aed2-a561ef31dcc6
 
 
218
Content-Type: application/octet-stream
mule-msmq-acknowledgement-type: None
mule-msmq-acknowledgement: None
mule-msmq-attach-sender-id: True
mule-msmq-body-type: 0
mule-msmq-connector-type: 0
mule-msmq-correlation-id: 00000000-0000-0000-0000-000000000000\0
mule-msmq-id: 22af009e-3b1b-4173-ad7f-34b060a158fc\6145
mule-msmq-label:
mule-msmq-lookup-id: 288230376151717889
mule-msmq-message-type: Normal
mule-msmq-priority: Normal
mule-msmq-source-machine: win-dt3v2pm5d7l
mule-msmq-extension:
mule-msmq-app-specific: 0
 
 
11
THIS IS A MESSAGE
2C
 
--47c7462b-f831-48f5-aed2-a561ef31dcc6--
 
0

The HTTP headers used for sending and receiving messages to and from the Gateway services are discussed more in detail later in this document.

Two-Phase Commit

The MSMQ connector uses a two-phase protocol to ensure zero-message-loss communication within the gateway.

In a traditional scenario, after a message is read in the gateway, it is deleted from the queue. If there is a connection failure or another issue in the ESB that prevents the message from being read, that message is lost.

In a scenario with a two-phase commit protocol, the messages read from the main queue are kept in a sub-queue as backup. After the connector receives a copy of the message, it sends an additional request to the gateway to remove the message from the sub-queue. When this commit action is not completed, the message remains in the sub-queue. After a period of time, messages in the sub-queue, considered as orphans, are moved back to their parent queue where they are retired.

Message Timeouts

Among different methods, MSMQ messages provide two properties that are useful to grant reliability of information:

  • timeToReachQueue: The maximum number of seconds a message can take to reach the MSMQ server after it’s received in the gateway. The default is not time out (InfiniteTimeout).

  • timeToBeReceived: The number of seconds a message can stay in the queue before it dequeues for a third party application. The default is to not time out (InfiniteTimeout).

    MSMQmessageTimeouts2

Note: If either property times out, the message moves to the dead-letter queue.

Specifying values for the properties:


          
       
1
2
3
4
5
6
<msmq:send
    config-ref="MSMQ"
    messageFormatter="ActiveXMessageFormatter"
    doc:name="MSMQ"
    timeToBeReceived="0"
    timeToReachQueue="0" />

Both properties can be set in the connector configuration and are read by the Anypoint Gateway. If you specify a value of zero (0), the default value is assumed (InfiniteTimeout).

Invalid Message Processing

Unreadable messages are moved to the invalid-queue-name subqueue. You can change this queue’s name using the Anypoint Gateway service configuration file. You can also change the timeout for invalid messages for when a payload of a message is parsed with an incorrect formatter.


          
       
1
2
3
4
5
<!-- The name of the invalid messages sub-queue -->
<add key="invalid-queue-name" value="Invalid"/>
 
<!-- Time in seconds for invalid messages before being sent to dead-letter queue -->
<add key="invalid-message-timeout" value="86400"/>

Enable Exactly-Once and In-Order Support

To enable Exactly-Once and In-Order (EOIO) support, you must select the flow containing MSMQ connector in Anypoint Studio and set the default operation Processing Strategy to synchronous. Otherwise, the connector processes messages as they are received in the ESB and ignores the original order in the queue.

FlowConfiguration

The setting appears in the XML as:


         
      
1
<flow name="myMSMQFlow" doc:name="myMSMQFlow" processingStrategy="synchronous">

Security Consideration

The Anypoint Gateway authenticates the direct caller, which is the connector running in the Mule ESB, and optionally the user on behalf of the connector.

Service Authentication

The authentication of the connector is done through a security token included in the HTTP Authorization header. This token is included on every HTTP request to the Gateway using Mule scheme:


          
       
1
2
3
4
GET: https://localhost:9000/msmq?count=50
Authorization: mule test-token
Mule-Msmq-Queue-Name: .\private$\out
Mule-Api-Version: 1

Configure the token on the connector and also in the Gateway configuration file. The following configuration sections show how the token is configured in both sides.

Connector Configuration


          
       
1
2
3
<msmq:config name="MSMQ" doc:name="MSMQ" accessToken="test-token" rootQueueName=".\private$\qout" serviceAddress="localhost:9000">
  <msmq:connection-pooling-profile initialisationPolicy="INITIALISE_ONE" exhaustedAction="WHEN_EXHAUSTED_GROW"/>
</msmq:config>

Gateway Configuration


          
       
1
2
3
<appSettings>   
    <add key="mule-auth-token" value="test-token"/>
</appSettings>

Note: The installer for the Anypoint Gateway service automatically generates a cryptographically secure token for use by callers upon first install. This token is displayed and placed upon the clipboard during installation for easy copying into a Mule application.

User Authentication

The user executing the call on behalf of the connector is authenticated through two custom HTTP headers, mule-impersonate-username and mule-impersonate-password.

When using user authentication, the queue in MSMQ must also be marked to require authentication. These two headers represent the Windows credentials of an existing user in the Active Directory forest where the Anypoint Gateway service is running, or a local account on the machine hosting the service. When these HTTP headers are included in an HTTP Request, the Anypoint Gateway service authenticates and impersonates this user before queuing/dequeuing a message from MSMQ. This provides the ability to configure the correct access control list permissions on the queue using Windows credentials.

The following HTTP request example illustrates how to pass these two headers from the connector to the Gateway:


         
      
1
2
3
4
5
6
GET: https://localhost:9000/msmq?count=50
Authorization: mule test-token
Mule-Impersonate-Username: domain\myuser
Mule-Impersonate-Password: password
Mule-Msmq-Queue-Name: .\private$\out
Mule-Api-Version: 1

Note: The connector and the gateway use SSL to protect all HTTP communications.

Queue Permissions

To use queue permissions, mark the queue to require authentication. In addition, the connector must send the Mule-Impersonate-Username and Mule-Impersonate-Password headers in the HTTP request message to impersonate the cell; otherwise the account impersonating the host is used (the user impersonating the Windows service or the application pool if the gateway is hosted in IIS).

Note: A Windows user must have logged in for at least the first time before using authenticated queues. When a user logs in for the first time, Windows creates a user’s profile, which must exist for the user to use authenticated queues.

The following table shows the permissions required for sending or receiving a message from a queue:

Operation Permissions

Receive

Receive Message, Peek Message

Send

Send Message, Peek Message, Get Properties

In both cases, Peek Message is only used for testing the connection. This permission can be removed if testing the connection is not required.

Note: When MSMQ is installed in a machine not joined to a Windows Domain, it works in Workgroup Mode. In this mode, authenticated queues are not supported and therefore the queue permissions can not be used either.

Message Serialization and Formatting

The Anypoint Gateway service does not use an MSMQ formatter unless it is specified by the connector. Therefore, a message sent in the HTTP request paylaod is stored in raw form in the body of the MSMQ message. However, this behavior can be overridden be setting a Message Formatter in the connector. A single formatter is supported out of the box: ActiveXMessageFormatter.

The following example illustrates how to set the formatter in an MSMQ connector:


         
      
1
<msmq:receive config-ref="MSMQ" doc:name="MSMQ (Streaming)" pollingPeriod="3000" messageFormatter="ActiveXMessageFormatter" />

When a message formatter is set on the connector, an additional HTTP header Mule-Msmq-Formatter is sent to the Anypoint Gateway. The gateway uses the formatter to serialize and deserialize the message when it enqueues or dequeues from MSMQ.

For the ActiveXMessageFormatter, the gateway also uses the Content-Type set by the connector in the HTTP request message:

Content-Type Description

plain/text

The connector sets this when the payload of the current Mule Message string. When set, the gateway sets the body stream of the MSMQ message as a string. Other applications can read this message directly as a string. An MSMQ connector receiving this message sets the payload of the Mule Message to a string so that a converter is not required.

application/octet-stream

Set when the payload is a byte array. The message is stored as a stream of bytes.

Configuration of the msmq:receive Element

The msmq:receive element is used in the primary scenario for receiving one or more messages from the Gateway.

The following table shows the properties in this element:

Property Usage

queueName

Queue name in UNC path or FormatName notation. See the Queue Names section for more information. Overrides the queue name set in the Global element. Optional.

pollingPeriod

Interval in milliseconds used by the connector for polling the configured queue in MSMQ. Optional.

messageCount

Maximum number of messages to retrieve in a single batch. Optional.

userName

The name of the user that is used to impersonate the call when accessing MSMQ from the Gateway. Overrides the user name set in the Global element. Optional.

password

The password of the user that will be used to impersonate the call when accessing the MSMQ from the Gateway. Overrides the password set in the Global element. Optional.

messageFormatter

The message formatter to be used in MSMQ for serializing and deserializing the message. Optional.

Configuration of the msmq:send Element

The msmq:send element is used in the primary scenario for sending one message to the Gateway.

The following table shows the properties in this element:

Property Usage

queueName

Queue name in UNC path or FormatName notation. Overrides the queue name set in the Global element. Optional.

userName

The name of the user that’s used to impersonate the call when accessing MSMQ from the Gateway. Overrides the user name set in the Global element. Optional.

password

The password of the user that’s used to impersonate the call when accessing the MSMQ from the Gateway. Overrides the password set in the Global element. Optional.

messageFormatter

The message formatter to be used in MSMQ for serializing and deserializing the message. Optional.

payload

The message payload to be sent to the Gateway. Optional.

Queue Names (Public, Private, and Clustered)

The MSMQ connector supports private and public queues. Private queues are queues that are not published in Active Directory and are displayed only on the local computer that contains them.

The following schemes are supported:

  • Path name: ComputerName\private$\QueueName

  • Path name on local computer: \private$\QueueName

  • Direct format name: DIRECT=ComputerAddress\PRIVATE$\PrivateQueueName

  • Private format name: PRIVATE=ComputerGUID\QueueNumber

Public queues are queues that are published in Active Directory.

Public format names contain the string PUBLIC= followed by the identifier assigned to the queue when it was created. This identifier is the GUID listed for the queue object in the Active Directory.

The following is the general format used to reference a public queue and its associated queue journal:

  • PUBLIC=QueueGUID

  • PUBLIC=QueueGUID;JOURNAL

The connector also supports private queues hosted in a failover cluster or also known as an MSMQ cluster. The queues are private to the cluster and referenced with the following format:

ClusterName\private$\QueueName

Supported Message Properties

The connector allows passing or receiving properties to and from the MSMQ message. Those properties are set in the current Mule Message and passed to the Anypoint Gateway as custom HTTP headers. The following message illustrates how the connector creates a new MSMQ message with a value "CustomLabel" for the label property:


         
      
1
2
3
4
5
6
POST: https://localhost:9000/msmq
Authorization: mule test-token
Mule-Msmq-Queue-Name: .\private$\qout
Mule-Api-Version: 1
Mule-Msmq-Label: CustomLabel
Body: THIS IS A SAMPLE MESSAGE

The following table summarizes all supported properties on the receive operation, and the mapping of the HTTP headers.

Property HTTP header Usage

msmq.acknowledgement.type

msmq-acknowledgement-type

Sets the type of acknowledgment message to return to the sending application.

msmq.acknowledgement

mule-msmq-acknowledgement

Sets the queue that receives the acknowledgement messages that Message Queuing generates.

msmq.attach.sender.id

mule-msmq-attach-sender-id

Gets a value that indicates whether to attach the sender ID to a message.

msmq.body.type

mule-msmq-body-type

Gets the type of data that the message body contains.

msmq.connector.type

mule-msmq-connector-type

Gets a value that indicates that some message properties typically set by Message Queuing were set by the sending application.

msmq.correlation.id

mule-msmq-correlation-id

The message identifier that references the original message. This ID is used to acknowledge, report, and respond to messages. Supported format: <GUID>\<Number>

For example: 66785f20-a2f3-42a3-bdcd-9ac5a937ac52\1

msmq-id

mule-msmq-id

The message’s unique identifier, which is generated by Message Queuing.

msmq.label

mule-msmq-label

Gets an application-defined unicode string that describes the message.

msmq.lookup.id

mule-msmq-lookup-id

One of the System.Messaging.MessagePriority values, which represent the priority levels of non-transactional messages. The default is Normal.

msmq.message.type

mule-msmq-message-type

Gets the type of the message retrieved from the queue, which can be Normal, Acknowledgement, or Report.

msmq.priority

mule-msmq-priority

Gets or sets the message priority, which indicates where to place a message in the queue.

msmq.extension

mule-msmq-extension

Sets additional, application-defined information associated with a message. Encode this as base64.

msmq.app.specific

mule-msmq-app-specific

Sets additional, application-specific information.

The following table summarizes all supported properties on the send operation, and the mapping with the HTTP headers.

Property HTTP header Usage

msmq.body.type

mule-msmq-body-type

Sets the type of data that the message body contains.

msmq.label

mule-msmq-label

Sets an application-defined unicode string that describes the message.

msmq.acknowledgement.type

msmq-acknowledgement-type

Sets the type of acknowledgment message to be returned to the sending application.

smq.attach.sender.id

mule-msmq-attach-sender-id

Sets a value that indicates whether the sender ID should be attached to the message.

msmq.priority

mule-msmq-priority

Gets or sets the message priority, which determines where in the queue the message is placed.

msmq.connector.type

mule-msmq-connector-type

Sets a value that indicates that some message properties typically set by Message Queuing were set by the sending application.

msmq.correlation.id

mule-msmq-correlation-id

Sets the message identifier that references the original message. Used to acknowledge, report, and respond to messages. Supported format: <GUID>\<Number>

For example: 66785f20-a2f3-42a3-bdcd-9ac5a937ac52\1

msmq.use.tracing

mule-msmq-use-tracing

Sets a value that indicates whether to trace a message as it moves toward its destination queue.

msmq.extension

mule-msmq-extension

Sets additional, application-defined information associated with the message. Encode as base64.

msmq.app.specific

mule-msmq-app-specific

Sets additional, application-specific information.

The following example shows how the "set-payload" component sets the label for an MSMQ message.

<set-property propertyName="msmq-label" value="message_from_mule" doc:name="Label"/>

Anypoint Gateway Service Troubleshooting

The Anypoint Gateway service leverages the built-in .NET tracing system. The basic premise is simple, tracing messages are sent through switches to listeners, which are lied to a specific storage medium. The listeners for the trace source used by the connector are available in the configuration file:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<sharedListeners>
   <add name="console" type="System.Diagnostics.ConsoleTraceListener" />
   <add name="file" type="System.Diagnostics.TextWriterTraceListener" initializeData="Mule.Msmq.log" />
   <add name="etw" type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}" />
</sharedListeners>
 
<sources>
    <source name="Mule.Msmq">
        <listeners>
            <clear />
            <add name="console" />
            <add name="etw"/>
        </listeners>
    </source>
</sources> 

The previous example configures three listeners for the output console, for files, and for Event Tracing for Window (ETW). The trace source for the connector Mule.Msmq is configured to output the traces to the console and ETW only.

Changing the Tracing Level

The Anypoint Gateway is configured by default to log everything, which is the Verbose level. Other possible levels are:

  • Error: Output error handling messages

  • Warning: Output warnings and error handling messages

  • Info: Output informational messages, warnings, and error handling messages

  • Off: Disable tracing

You can configure the levels at switch level in the configuration file:


         
      
1
2
3
<switches>
    <add name="Mule.Msmq" value="Verbose" />
</switches>

Event Tracing for Windows (ETW)

ETW is a very efficient built-in publish and subscribe mechanism for doing event tracing at the kernel level. There is little overhead in using this feature compared to other traditional tracing solutions that rely on I/O for storing the traces in persistence storage such as files or databases. As a built-in mechanism in Windows, many of the operating systems services and components use this feature as well. For that reason, not only can you troubleshoot the application but also many of the OS components involved in the same execution.

In ETW, there are applications publishing events in queues (or providers) and other applications consuming events from those queues in real-time through ETW sessions. When an event is published in a provider, it goes nowhere unless there is a session collecting events on that queue. (The events are not persisted).

The tracing system in .NET includes a trace listener for ETW, EventProviderTraceListener, which you can configure with a session identifier, which ETW uses to collect traces:


         
      
1
2
3
<sharedListeners>
   <add name="etw"type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}"/>
</sharedListeners>

In the example, the session is associated with this identifier: {47EA5BF3-802B-4351-9EED-7A96485323AC}

Collect Session Traces

To collect sesison traces:

  1. Open a Windows console and run this command to start a new session:

    logman start mysession -p {47EA5BF3-802B-4351-9EED-7A96485323AC} -o etwtrace.etl -ets
  2. Run this command to stop the session:

    logman stop mysession -ets

    This generates the etwtrace.etl file with the tracing session data.

  3. Run this command to generate a human readable file:

    tracerpt etwtrace.etl

    This command transfers useful information in the dumpfile.xml text file. For more information, see Tracerpt

MSMQ Connector Troubleshooting

The MSMQ connector is integrated with the Mule ESB logging infrastructure for logging errors and relevant information for the user.

The following table lists common errors that can occur while using the MSMQ connector:

Error Cause

Unauthorized. "Authentication with the proxy failed".

The security token configured on the connector and the one on the gateway do not match. Verify the token configured on the MSMQ connector within Mule and in the Anypoint Gateway service configuration file.

Forbidden. "Access Forbidden to write in queue [Queue Name]"

The user with the credentials specified in username and password does not have permissions for writing to or reading the queue. Verify the queue access permissions.

Not acceptable. "The connector and proxy version do not match"

This is unlikely to happen. The version of the connector running in the ESB is not compatible with the version of the Anypoint Gateway. Make sure to update the connector or gateway to use the same version.

Not Found. Queue Not Found [Queue Name]

The queue configured in the connector could not be found.

Not Found.

The Gateway address and port configured in the connector are incorrect. Verify the Gateway configuration to determine the right server name and port.

Internal Server Error

An unexpected error occurred in the Gateway. Check the Gateway traces to determine the cause of the issue.

Message Acknowledgement Samples

Requirements:

  • Windows PowerShell 3.0 under the Windows Management Framework 3.0

  • Anypoint Studio with MSMQ connector installed as described in this guide

  • MessageAcknowledgeSample.zip samples zip file. Contains PowerShell scripts (.ps1 file type) and the msmq-demo-ack.zip file. The executables are signed with MuleSoft’s certificate.

Step 1: Open the msmq-demo-ack Project

  1. Launch Anypoint Studio and open an existing Mule project.

  2. Click File >Import > Anypoint Studio generated Deployable Archive (.zip).

  3. In the zip file, navigate the file system, and click the msmq-demo-ack.zip file.

  4. Click Finish.

Step 2: Run Setup Script

  1. This script creates messages queues and send messages for the samples.

  2. Open a command window: Windows key + R, type PowerShell, right-click the program, and click on Run As Administrator.

  3. Navigate to the sample directory, and type Set-ExecutionPolicy Unrestricted and press Enter. By default the Execution Policy value is restricted, which does not allow you to run this sample.

  4. Type .\1-setup.ps1 and press Enter.

  5. The Console displays:

    
                 
              
    1
    2
    3
    4
    5
    6
    7
    
    Creating .\private$\sampleq
    Queue Creating .\private$\secondq
    Queue Creating .\private$\adminq
    Queue Sending Message 1 to .\private$\sampleq
    Sending Message 2 to .\private$\secondq
    Sending Message 3 to .\private$\sampleq
    Sending Message 4 to .\private$\sampleq
  6. Do not close this console.

Step 3: Running the Demo

  1. Right-click msmq-demo.xml and select Run As Mule Application.

  2. Check the console to see when the application starts:

    
                 
              
    1
    2
    
    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    + Started app 'msmq-demo-ack' + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  3. Check for these lines, which indicate that MSMQ connector is listening to both queues and received 1 message in sampleq queue and 6 messages in adminq queue.

    
                 
              
    1
    2
    3
    4
    
    INFO  XXXX-XX-XX XX:XX:XX,XXX [Receiving Thread] org.mule.modules.msmq.MsmqConnector: Connecting to https://localhost:9000/msmq
    INFO  XXXX-XX-XX XX:XX:XX,XXX [Receiving Thread] org.mule.modules.msmq.MsmqConnector: Connecting to https://localhost:9000/msmq
    INFO  XXXX-XX-XX XX:XX:XX,XXX [Receiving Thread] org.mule.modules.msmq.MsmqConnector: Receiving 1 from .\private$\sampleq
    INFO  XXXX-XX-XX XX:XX:XX,XXX [Receiving Thread] org.mule.modules.msmq.MsmqConnector: Receiving 6 from .\private$\adminq
  4. The following lines appear (order may change), which indicate that one message was read, Message 1 . The message’s body and label are shown along with several incorrect versions of ACK (logged as INFOs') or NACK (logged as WARNs) depending on the context and the message. For more information, see Acknowledgement Enumeration.

    
                 
              
    1
    2
    3
    4
    5
    6
    7
    8
    
    INFO  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-choice-flow.stage1.03] org.mule.api.processor.LoggerMessageProcessor: ACK Cause: ReachQueue | Correlation Id: xxxx  | Label: Message 2
    INFO  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-choice-flow.stage1.07] org.mule.api.processor.LoggerMessageProcessor: ACK Cause: Receive | Correlation Id: xxxx  | Label: Message 1
    INFO  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-normalFlow.stage1.02] org.mule.api.processor.LoggerMessageProcessor: Label: Message 1 | Body: <?xml version="1.0"?>
    <string>First Message</string>
    INFO  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-choice-flow.stage1.04] org.mule.api.processor.LoggerMessageProcessor: ACK Cause: ReachQueue | Correlation Id: xxxx  | Label: Message 4
    INFO  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-choice-flow.stage1.02] org.mule.api.processor.LoggerMessageProcessor: ACK Cause: ReachQueue | Correlation Id: xxxx  | Label: Message 1
    WARN  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-ReceiveTimeout.stage1.02] org.mule.api.processor.LoggerMessageProcessor: 'ReceiveTimeout NACK' Received | Correlation Id: xxxx | Label: Message 4
    WARN  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-NotTransactionalQueue.stage1.02] org.mule.api.processor.LoggerMessageProcessor: 'NotTransactionalQueue NACK' Received | Correlation Id: xxxx | Label: Message 3
  5. Double-click Choice flow control under the msmq-choice-flow flow to view its properties:

    MSMQAdmin

    The Choice flow control evaluates the msmq.acknowledgement property of each message received. This routes messages to a SubFlow (using Flow Reference control). Messages received in adminq are just for acknowledgement purposes. Even when those six messages have an msmq.id property, it is not important, but what is relevant is the msmq.correlation.id, which points to the msmq.id of the message originating the acknowledgement message in the administrative queue. In the sample, Message 4 has been set with a millisecond in the property timeToBeReceived, which produces a ReceiveTimout NACK. Also, Message 6 is sent in a transactional way using a non-transactional queue, which brings a NotTransactionalQueue NACK.

Deleting a Message

  1. Open the Message Queuing Administrative Console.

  2. Press the Windows Key + E.

  3. Right-click Computer and clcik Manage.

    MSMQManage

  4. In the Computer Management Console tree on the left, open Services and Applications > Message Queueing > Private Queues

  5. A remaining message dispalys in secondq, as MSMQ connector in not configured to listen this queue.

  6. Delete the message: In the left tree, open Private Queues > secondq > Queue messages and right-click Queue messages > All Tasks > Purge:

    MSMQpurge

  7. Select Yes in the popup.

  8. Return to Anypoint Studio and notice these additional lines in the Console, which indicate an additional kind of NACK, and that the orginating message has not been read and has not been purged:

    
                 
              
    1
    2
    
    INFO  XXXX-XX-XX XX:XX:XX,XXX [Receiving Thread] org.mule.modules.msmq.MsmqConnector: Receiving 1 from .\private$\adminq
    WARN  XXXX-XX-XX XX:XX:XX,XXX [[msmq-demo-ack].msmq-QueuePurged.stage1.02] org.mule.api.processor.LoggerMessageProcessor: 'QueuePurged NACK' Received | Correlation Id: xxxx | Label: Message 2

Step 4: Cleaning the Environment

  • Go back to the console and type .2\clean-ps1 and this message appears:


          
       
1
2
3
Deleting .\private$\sampleq Queue
Deleting .\private$\secondq Queue
Deleting .\private$\adminq Queue

CloudHub Integration Sample

This sample receives incoming requests via HTTP connector, and sends the request via MSMQ connector (Send operation) to the remote MSMQ queue. It then receives a MSMQ message from your server (Streaming Receive operation) and logs the result.

  1. Create new Mule project from File > New > Mule Project. You can set name to cloudhub-test. Click Finish.

  2. Go to Configuration XML tab and replace existing code with the following:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    <mule xmlns:msmq="http://www.mulesoft.org/schema/mule/msmq" 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:spring="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
    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/msmq http://www.mulesoft.org/schema/mule/msmq/current/mule-msmq.xsd">
        <msmq:config name="MSMQ" serviceAddress="X.X.X.X:9000" accessToken="you_key" rootQueueName=".\private$\test-cloudhub" ignoreSSLWarnings="true" doc:name="MSMQ"/>
        <flow name="msmq-cloudhub-test2Flow1" doc:name="msmq-cloudhub-test2Flow1">
            <http:inbound-endpoint exchange-pattern="one-way" host="localhost" port="80" doc:name="HTTP"/>
            <expression-filter expression="#[payload != '/favicon.ico']" doc:name="Expression"/>
            <set-payload value="#['Hello, ' + payload + '. Today is ' + server.dateTime.format('dd/MM/yy') + '.' ]" doc:name="Set Payload"/>
            <msmq:send config-ref="MSMQ" messageFormatter="ActiveXMessageFormatter" doc:name="MSMQ"/>
        </flow>
        <flow name="msmq-cloudhub-test2Flow2" doc:name="msmq-cloudhub-test2Flow2">
            <msmq:receive config-ref="MSMQ" messageFormatter="ActiveXMessageFormatter" doc:name="MSMQ (Streaming)"/>
            <byte-array-to-string-transformer doc:name="Byte Array to String"/>
            <logger message="#[payload]" level="INFO" doc:name="Logger"/>
        </flow>
    </mule>

    In the MSMQ configuration node:

    • serviceAddress is the IP and port of your VPN appliance. Double check that port 9000 (or the one set during Anypoint Gateway setup) is open in the firewall settings and the appliance server.

    • accessToken is the token configured during Gateway setup.

    • rootQueueName is the existing queue name with writing rights to user Everyone according normal installation of Mule samples. You can verify that connectivity to MSMQ is OK by using the Test Connection button:

      MSMQGlobalElProps

  3. Right-click the cloudhub-test Mule project, select*Deploy to Anypoint Platform* → Cloud.

  4. Fill in the fields with the provided account settings that you used when you created your account in the Anypoint Platform

  5. Select the Environment, choose an available domain and click Finish. You are prompted with a confirmation window. Click *OK. Then you are able to use the intergation project.

    MSMQCHsuccess

  6. Point your browser to this address (note that the browser remains blank):

    http://your_subdomain.cloudhub.io/this_is_a_test
  7. Log into the Anypoint Platform to enter your application, and select Logs from the dashboard.

  8. The resulting messages are logged:

    MSMQinfo