Nav

Anypoint MQ Tutorial

This guide helps you send and receive messages using Anypoint MQ using a publish/subscribe queue mechanism. Anypoint MQ provides a user interface built into Anypoint Platform that lets you send messages to a queue or message exchange, and then read the messages from a queue. Anypoint MQ also provides a connector that works with Anypoint Studio. This tutorial explains how to use these features.

This tutorial helps you create a queue and send and receive messages, create a client ID and secret for an application, and use the Anypoint MQ connector in Anypoint Studio to send and receive messages to the application. The advanced section helps you create a message exchange to send a message to multiple queues.

Prerequisites

  1. Read Understanding Anypoint MQ to familiarize yourself with the terminology and concepts of using MQ.

  2. Create an Anypoint Platform account to configure user permissions, register applications in MQ, and to create queues and message exchanges. You can access Anypoint MQ from the main Anypoint Platform screen and the left navigation bar. You can also open or close the left navigation bar by pressing the Escape key on your keyboard, or by clicking the menu icon at the upper left of the screen.

  3. Subscribe to Mule Enterprise - An Enterprise license is required to use the MQ server software.

  4. Install Anypoint Studio.

If you or another person in your organization has not created an environment, user access, and roles for accessing Anypoint MQ, see Anypoint MQ Access Management before starting this tutorial.

Anypoint MQ Queues

A queue provides a temporary area for holding messages. Applications push messages to the queue and other applications consume the messages. In Anypoint MQ, you can read messages, return the messages for later viewing, or delete a message. By default, messages return to the waiting area so other applications can read them. Messages persist until the time to live (TTL) value expires—​by default, a message persists in Anypoint MQ for 7 days.

Queue and message exchange names can contain alphanumeric characters (a-z, A-Z, 0-9), dots (.), and dashes (-). All other characters are not allowed. Queue and message exchange names are limited to 127 characters in length.

Create a Queue

To create a queue:

  1. Log into Anypoint Platform.

  2. Click MQ from the initial Anypoint Platform screen or from the left navigation bar.

    mq-ap-access

  3. Click Destinations:

    mq-destinations-option

  4. Click the blue plus icon mq-blue-plus-icon.

  5. In the drop-down, click Queue:

    mq-create-q-screen-dlq

  6. In the Create Queue screen, specify a name for the queue, and if needed, change the Default TTL (time-to-live) and Default Lock TTL values. A message lock makes a message unavailable to other applications while locked. A locked message does not block other messages to be read.

  7. If you want your queue encrypted, slide the encryption slider to the right.

  8. If your organization previously created a dead letter queue where undeliverable messages go, click Assign a Dead Letter Queue to enable this option. For more information on dead letter queues, see Create a Queue in Queues and message exchanges.

  9. When done, click Save Changes:

    The queue creates and you are returned to the Destinations screen.

    Note: Where you click on a queue entry in the Destinations screen governs what you see next:

    mq-entryui

If you need to delete a queue, see How do I delete a queue? in the Anypoint MQ FAQ.

Send a Message to a Queue

To send a message to a queue:

  1. Log into Anypoint Platform.

  2. In the drop-down left navigation bar, click MQ.

  3. Click Destinations.

  4. Click the MyDemoQueue entry in Destinations to view details about the queue.

  5. Click the left side of the queue entry to open the Messaging feature, or click the right side of the queue entry and click the arrow to the right of the queue name:

    mq-access-messaging2

  6. In the settings page, click Message Sender:

    mq-click-msg-sender2

  7. Type text in the Payload such as Hello Mules (leave the Type field set to Text):

    mq-msg-sender-text-payload2

  8. Click Send.

Verify the Message in a Queue

To verify that the message arrived in the queue:

  1. Click Destinations:

    mq-destinations-option

  2. Click the right side of the queue entry to view details and see the number of messages in the queue:

    mq-num-queued-msgs

Get a Message From a Queue

To get a message from a queue:

  1. Follow the directions in Send a Message to a Queue and advance to Step 6, except click Message Browser:

    mq-click-msg-browser2

  2. Click Get Messages.

    mq-get-messages2

  3. Click the message ID value to view the message.

    mq-click-id2

  4. If you want to return the message to the queue, such as if other applications may also want to read the message, click the Return Messages icon - this is the default condition. If you switch screens back to the Message Sender or to Destinations, messages automatically return to the queue. In Anypoint MQ, returning the messages to the queue is known as nack - the message is not altered. However, the time to live (TTL) value you set when you created your queue determines how long the message is available before Anypoint MQ deletes it.

    mq-click-retmsgs2

    Alternatively, you can delete the message by clicking the trash can icon. Anypoint MQ provides three modes for how messages delete after they are viewed. For more information, see Anypoint MQ Acknowledgement Mode.

    mq-message-delete-trash-can-icon2

Now you are able to send and receive messages in Anypoint MQ. In the next section, you can try alternate ways of formatting messages.

Send a CSV or JSON Message

To send a JSON message:

  1. Click Message Sender.

  2. Set the Type to JSON.

  3. Set the Payload to:

    
                 
              
    1
    2
    3
    4
    5
    
    {
    "animal that walks":"dog",
    "animal that swims":"fish",
    "animal that flies":"parrot"
    }
  4. Click Message Browser and the message ID to view the message:

    mq-json-get-msg2

To send a CSV message:

  1. Click Message Sender.

  2. Set the Type to CSV.

  3. Set the Payload to:

    "dog",
    "fish",
    "parrot"
  4. Click Message Browser and the message ID to view the message.

Configure Anypoint Studio for MQ

In this section, we use Anypoint Studio to create a simple application that you can use to publish a message to a queue, or to consume the message, and to ack and nack the message.

In the next section, we return to Anypoint Platform and register an application that we can use in Studio.

The Studio screens that follow use the new Anypoint Studio Light Theme appearance option which is the default style for Studio 6 and newer. You can set this theme in older versions of Studio by clicking Anypoint Studio > Preferences > General > Appearance > Theme > Studio Light Theme (Beta).

MQ set the appearance theme

Register a Client Application

The Anypoint MQ feature in Anypoint Platform lets you register a Client Application and get a client ID and a client secret that you plug into an application you create in Anypoint Studio. These credentials enable the MQ server to recognize your Studio application.

To register a client application:

  1. Log into Anypoint Platform.

  2. Click MQ from the initial Anypoint Platform screen or from the left navigation bar.

    mq-ap-access

  3. Click Client Apps:

    mq-click-client-apps

  4. Click the blue plus + button:

    mq-create-client-app-values

  5. Specify an application name such as DemoClientApp and click Save Changes.

    mq-create-client-app-name

Note: Leave the Client Apps window open. We need to copy and paste the Client ID and Client Secret into the configuration for Anypoint Studio in the next step.

When we are ready, you can copy the ID and Secret values by simply clicking each Copy button:

mq-client-id-and-secret-values

Configure Studio for the Anypoint MQ Connector Plugin

To add the Anypoint MQ connector to Studio:

  1. In Studio, click Help > Install New Software:

    mq-tutorial-help-install-new-sw

  2. Click the drop-down menu for Work with and select Anypoint Connectors Update Site:

    mq-connector-install-from-studio

  3. Expand Community and click Anypoint MQ Connector.

  4. Click Next.

  5. Follow the prompts to install the connector and restart Studio when requested.

Use Studio to Create an Application

Note: If you want to create your application using XML or wish to check the XML as you go along, see XML Flow.

To create an application:

  1. Create a new Mule Project. Click File > New > Mule Project. Name the project "mqdemo".

  2. Search for "http" and drag the HTTP Connector to the Studio Canvas. Here’s how the Canvas appears after pulling all the building blocks to the Canvas:

    mq-connector-visual-flow

    1. Search for "set" and drag Set Payload to the Canvas.

    2. Search for "mq" and drag the Anypoint MQ connector icon to the canvas.

    3. Search for "logger" and drag Logger to the Canvas.

  3. Click the HTTP Connector and click the green plus sign to the right of Connector Configuration:

    mq-http-connector

  4. In the HTTP Connector’s Global Element Properties, set the host to 0.0.0.0 and the port to 8081. Click OK.

    mq-http-connector-globals

  5. Set the Path to /mq/{messageId}:

    mq-http-path

  6. Click Set Payload in the Canvas and set the Value to:

    #[message.inboundProperties.'http.uri.params'.messageId]

    mq-set-payload

  7. Click the Anypoint MQ connector, and click the green plus sign to the right of Connector Configuration:

    Connector Configuration access link - green plus sign

  8. In the MQ Connector’s Global Element Properties window, add the information from Anypoint Platform:

    mq-connector-properties

    1. Copy the Anypoint Platform’s Client App > Client App ID value to Studio’s Client ID field.

    2. Copy the Anypoint Platform’s Client App > Client Secret value to Studio’s Client Secret field.

    3. Ensure that Max Redelivery is set to -1 so that Anypoint MQ keeps retrying to deliver a message that is not delivered. The -1 value indicates that there is no limit to retries.

      mq-set-max-redelivery

      For more information on other options and tabs, see Advanced Global Element Properties in Configuring MQ in Anypoint Studio.

    4. Click OK.

  9. Click the Operation field and specify the publish operation.

    mq-operation-publish

  10. Specify the Destination as MyDemoQueue that you set in Anypoint Platform:

    mq-destination-queue2

  11. Click the Logger and set the Message field to:

    MQ Message: #[payload]

    mq-logger-properties

  12. Save your project.

XML Flow

After you configure your application using the MQ Connector, you can check your configuration against this XML:


           
        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:anypoint-mq="http://www.mulesoft.org/schema/mule/anypoint-mq" 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/anypoint-mq http://www.mulesoft.org/schema/mule/anypoint-mq/current/mule-anypoint-mq.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <anypoint-mq:config name="Anypoint_MQ_Configuration" doc:name="Anypoint MQ Configuration">
        <anypoint-mq:provider url="https://mq-us-east-1.anypoint.mulesoft.com/api/v1" clientId="<client_ID_value>" clientSecret="<client_secret-value>"/>
    </anypoint-mq:config>
    <flow name="mqdemoFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/mq/{messageId}" doc:name="HTTP"/>
        <set-payload value="#[message.inboundProperties.'http.uri.params'.messageId]" doc:name="Set Payload"/>
        <anypoint-mq:publish config-ref="Anypoint_MQ_Configuration" doc:name="Anypoint MQ" destination="MyDemoQueue"/>
        <logger message="MQ Message = #[payload]" level="INFO" doc:name="Logger"/>
    </flow>
</mule>

Run the Studio Application

In Anypoint Studio, click the project name in Package Explorer, and click Run > Run As > Mule Application.

The output should end with these statements:


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Started app 'mqdemo'                                     +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
INFO  <date_and_time> [main] org.mule.module.launcher.DeploymentDirectoryWatcher:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Mule is up and kicking (every 5000ms)                    +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
INFO  <date_and_time> [main] org.mule.module.launcher.StartupSummaryDeploymentListener:
**********************************************************************
*              - - + DOMAIN + - -               * - - + STATUS + - - *
**********************************************************************
* default                                       * DEPLOYED           *
**********************************************************************

*******************************************************************************************
*      - - + APPLICATION + - -      *       - - + DOMAIN + - -       * - - + STATUS + - - *
*******************************************************************************************
* mqdemo                            * default                        * DEPLOYED           *
*******************************************************************************************

Test Your Application

Get a REST plugin for your browser so that you can send POST requests. Typical software:

The following is an example setup using Postman:

mq-post

To set up Postman for a REST POST:

  1. Specify the URL to send the message as 0.0.0.0:8081/mq/Hello. You can also specify messages with spaces such as, 0.0.0.0:8081/mq/My What A Great Message.

  2. Click POST in the drop-down options menu.

  3. Click Send to post the message. You can send more than one message if you prefer.

  4. View the resulting reply from the Anypoint Studio web server.

Viewing Your Message in Anypoint MQ

To view your message:

  1. Switch back to Anypoint Platform, and if needed, log in, and click MQ in the left navigation bar.

  2. Click Destinations.

  3. Click MyDemoQueue at the right side to view the number of messages in the queue:

    mq-messages-in-queue2

    You can see the number of messages in the queue. Having verified that you have messages, we can now view them.

  4. Click MyDemoQueue at the start of the entry to view the Queue Settings, Message Sender, and Message Browser.

    mq-view-mydemoq-settings2

  5. Click Message Browser and click Get Messages:

    mq-get-messages2

  6. Click a message ID and view the message to the right.

    mq-click-id-to-see-msg2

You can repeat this process by returning to your REST POST application and sending and viewing more messages. In the next section, we build on your knowledge, first with an administrative task of creating user roles and then creating and testing message exchanges, which let you send one message to multiple queues.

Message Exchanges

The sections that follow help you work with message exchanges. A message exchange consists of a collection of one or more queues. Message exchanges help you organize queues and send one message to all its bound queues. You can still send and receive messages from a bound queue, but the message exchange ensures all queues get the same message.

Message exchange and queue names can contain alphanumeric characters (a-z, A-Z, 0-9), dots (.), and dashes (-). All other characters are not allowed. Message exchange and queue names are limited to 127 characters in length.

Create a Message Exchange

To create a message exchange:

  1. Log into Anypoint Platform.

  2. Click the menu icon at the top left of the screen and click MQ from the left navigation bar, or click MQ from the Anypoint Platform screen.

  3. Click Destinations.

  4. Click the blue plus circle.

  5. Click Exchange.

    mq-create-demo-exchange

  6. Specify the name MyDemoExchange.

  7. Click the checkbox to bind MyDemoQueue to this message exchange.

  8. Click Save Changes.

  9. In the Destinations screen. click the message exchange Type to list its details.

If you need to delete a message exchange, see How do I delete a Message Exchange? in the Anypoint MQ FAQ.

Bind a Queue to a Message Exchange

To bind a queue to a message exchange:

  1. Log into Anypoint Platform.

  2. In the top task bar, click MQ.

  3. Click Destinations.

  4. Click the left side of the message exchange entry in Destinations.

    Note: Where you click on a message exchange entry in the Destinations table governs what you see next:

    mq-where-to-click-x2

  5. In the Exchange menu, click Bind for each queue you want to bind to the message exchange:

    mq-bind-queue-to-exchange2

Send a Message to a Message Exchange

Sending a message to a message exchange is very similar to sending a message to a queue. The only difference is that you can get the message from any queue bound to a message exchange.

To send a message to a message exchange:

  1. Log into Anypoint Platform.

  2. In the top task bar, click MQ.

  3. Click Destinations.

  4. Click the MessageExchange entry in Destinations to view details about the message exchange.

  5. Click the MessageExchange link in the details screen to access the Message Sender:

    mq-exchange-msg-access2

  6. Click Message Sender:

    mq-exchange-msg-sender2

  7. Type the contents of the Payload and click Send:

    mq-exchange-payload2

You can now use the Message Browser to get the message from the MyDemoQueue as described in Get a Message From a Queue.

You can also send comma-separated value (CSV) or JSON content in the payload by changing the message Type value. For more information, see Send a CSV or JSON Message.