---
schema_version: "1"
id: 0269cb09467b8dec1e5f3cdd957b2f858865bdb550cab9864f2611b280ced807
title: Anypoint MQ Connector 3.x Migration Guide
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/anypoint-mq-connector/3.x/anypoint-mq-new-3x-major.md
canonical_url: https://docs.mulesoft.com/anypoint-mq-connector/3.x/anypoint-mq-new-3x-major
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 52852f0fe0ac3482d8f103a95a5651fbd47244bc691a85d86c525d625a07f373
description: MuleSoft Documentation Site
release: 3.x
latest: false
---
---
product: Anypoint MQ Connector
version: 3.x
---

# Anypoint MQ Connector 3.x Migration Guide

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint MQ Connector version 3.0 includes new features, such as simplified configuration,
standardized endpoints, and non-blocking functionality.

## Global Configuration

In version 2.x of this connector, `default-subscriber-config` includes these parameters:

```xml
<anypoint-mq:default-subscriber-config
    name="Anypoint_MQ_Default_subscriber"
    acknowledgementMode="IMMEDIATE"
    acknowledgementTimeout="10000" <!-- (1) -->
    maxRedelivery="2"              <!-- (2) -->
    pollingTime="2000"
    fetchSize="5"                  <!-- (3) -->
    fetchTimeout="5000"            <!-- (3) -->
    frequency="2000">              <!-- (3) -->
  <anypoint-mq:connection          <!-- (4) -->
    clientId="${client.id}"
    clientSecret="${client.secret}"/>
  <anypoint-mq:circuit-breaker     <!-- (5) -->
    circuitName="InvoiceSettings"
    onErrorTypes="JMS:TIMEOUT"
    errorsThreshold="10" tripTimeout="1"
    tripTimeoutUnit="MINUTES" />
</anypoint-mq:default-subscriber-config>
```

In version 3.x of this connector, the `config` element contains only the connection settings:

```xml
<anypoint-mq:config name="Anypoint_MQ_Config">
    <anypoint-mq:connection
        clientId="${client.id}"
        clientSecret="${client.secret}" />
</anypoint-mq:config>
```

This table lists the 2.x `config` elements and their 3.x equivalents.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Version 2.x Behavior</th><th>Version 3.x Equivalent</th></tr></thead><tbody><tr><td><div><div><p><strong>(1)</strong> - Acknowledgment</p></div></div></td><td><div><div><p>Global acknowledgment settings for the Anypoint MQ Subscriber sources.</p></div></div></td><td><div><div><p>Configure for each Subscriber instance.</p></div></div></td></tr><tr><td><div><div><p><strong>(2)</strong> - Max Redelivery</p></div></div></td><td><div><div><p>Redelivery filter for Anypoint MQ messages located in the <code>redeliveryCount</code> header.</p></div></div></td><td><div><div><p>Deprecated and no longer available as a standalone filter. Use <code>"DLQ + Idempotent Filter"</code> pattern instead.</p></div></div></td></tr><tr><td><div><div><p><strong>(3)</strong> - Message Fetch</p></div></div></td><td><div><div><p>All parameters related to how messages are retrieved from the Anypoint MQ service, including <code>prefetch</code> configuration.</p></div></div></td><td><div><div><p>Configure all the fetching strategy parameters on each Subscriber under the <code>Subscriber Type</code> parameter.</p></div></div></td></tr><tr><td><div><div><p><strong>(4)</strong> - Connection</p></div></div></td><td><div><div><p>Connection parameters.</p></div></div></td><td><div><div><p>Idem configuration for all the connection settings.</p></div></div></td></tr><tr><td><div><div><p><strong>(5)</strong> - Circuit Breaker</p></div></div></td><td><div><div><p>Circuit Breaker configuration for the Anypoint MQ Subscriber source.</p></div></div></td><td><div><div><p>Handle each Circuit Breaker instance either as a standalone element referenced by each Anypoint MQ Subscriber or as a private Circuit Breaker for the Subscriber source that declares it.</p></div></div></td></tr></tbody></table>

## Subscriber Listener

In version 3.x of this connector, the `Subscriber` message source configuration for message
listening has changed.

For information about the new subscriber, see [Anypoint MQ Subscriber Source](https://docs.mulesoft.com/anypoint-mq-connector/3.x/anypoint-mq-listener).

### Message Acknowledgment

In version 2.x of this connector, the acknowledgement mode of the Subscriber source is defined at
the configuration level:

```xml
<anypoint-mq:default-subscriber-config name="Anypoint_MQ_Default_subscriber"
       acknowledgementMode="MANUAL" acknowledgementTimeout="120000">
    <anypoint-mq:connection clientId="${client.id}" clientSecret="${client.secret}"/>
</anypoint-mq:default-subscriber-config>
```

In version 3.x, these parameters are part of the Subscriber source itself and affect only that
single Subscriber instance. The semantics of the acknowledgment parameters has not changed. Here’s
the equivalent configuration of the Subscriber source:

```xml
<anypoint-mq:subscriber config-ref="Anypoint_MQ_Config"
    destination="queue"
    acknowledgementMode="MANUAL"
    acknowledgementTimeout="2"
    acknowledgementTimeoutUnit="MINUTES"/>
```

### Prefetch Mode

In version 2.x of this connector, `prefetch` mode is enabled by default and you specified all
related parameters at the configuration level:

```xml
<anypoint-mq:default-subscriber-config
      name="Anypoint_MQ_Default_subscriber"
      pollingTime="2000" fetchSize="5"
      fetchTimeout="5000" frequency="2000">
    <anypoint-mq:connection clientId="${client.id}"
      clientSecret="${client.secret}"/>
</anypoint-mq:default-subscriber-config>
```

Version 3.x includes a new concept called `Subscriber Type`, in which you control the `prefetch`
configuration.

```xml
<anypoint-mq:subscriber config-ref="Anypoint_MQ_Config"
    destination="queue">
   <anypoint-mq:subscriber-type>
     <anypoint-mq:prefetch maxLocalMessages="20"/>
   </anypoint-mq:subscriber-type>
</anypoint-mq:subscriber>
```

This table lists the 2.x `prefetch` parameters and their 3.x equivalents.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Version 2.x Parameter</th><th>Description</th><th>Version 3.x Equivalent</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>fetchSize</code></p></div></div></td><td><div><div><p>Declared at the <code>config</code> level, controls the size of the local message buffer, which is calculated as three times the <code>fetchSize</code> value.</p></div></div></td><td><div><div><p><code>maxLocalMessages</code></p></div></div></td><td><div><div><p>Declared at the <code>Subscriber</code> level, explicitly controls the maximum size that the local message buffer can have. This parameter serves as a target number, attempting to fetch as many messages as needed to fill the buffer completely.</p></div><div><p>When using <code>prefetch</code> mode, set <code>maxLocalMessages</code> to a value greater than <code>1</code> to avoid message-processing latency issues. When <code>maxLocalMessages</code> is set to <code>1</code>, latency can occur when the connector prefetches the message but the app doesn’t consume it, and the message returns to the queue for reprocessing.</p></div></div></td></tr><tr><td><div><div><p><code>fetchTimeout</code></p></div></div></td><td><div><div><p>Controls the time waiting for a response from the service.</p></div></div></td><td><div><div><p>Deprecated</p></div></div></td><td><div><div><p>This parameter is no longer available. The connector always uses the maximum long-polling value.</p></div></div></td></tr><tr><td><div><div><p><code>frequency</code></p></div></div></td><td><div><div><p>Controls when to recheck for messages after the queue is empty.</p></div></div></td><td><div><div><p>Deprecated</p></div></div></td><td><div><div><p>This parameter is no longer available. The connector handles the frequency internally, fixed at 1 second.</p></div></div></td></tr><tr><td><div><div><p><code>pollingTime</code></p></div></div></td><td><div><div><p>Used only when <code>fetchSize</code> is <code>0</code>, effectively disabling the <code>prefetch</code> mode and enabling <code>polling</code> mode.</p></div></div></td><td><div><div><p>Deprecated</p></div></div></td><td><div><div><p>This parameter is replaced by the more powerful <code>polling</code> subscriber type.</p></div></div></td></tr></tbody></table>

### Polling Mode

Version 2.x of the Anypoint MQ Connector allowed you to disable the `prefetch` mode by setting the
`fetchSize` parameter to `0` and then using `pollingTime` as a fixed-frequency polling scheduler.

In version 3.x of this connector, the polling mode of the Subscriber source is simplified and
normalized. You can use the schedulers provided by Mule runtime engine out of the box, either as
`fixed-frequency` or `cron`:

- `fixed-frequency`

  ```xml
  <anypoint-mq:subscriber config-ref="Anypoint_MQ_Config"
    destination="queue">
     <anypoint-mq:subscriber-type >
        <anypoint-mq:polling fetchSize="9">
           <scheduling-strategy >
              <fixed-frequency frequency="1" timeUnit="SECONDS" />
           </scheduling-strategy>
        </anypoint-mq:polling>
     </anypoint-mq:subscriber-type>
  </anypoint-mq:subscriber>
  ```

- `cron`

  ```xml
  <anypoint-mq:subscriber destination="queue"
      config-ref="Anypoint_MQ_Config">
      <anypoint-mq:subscriber-type>
          <anypoint-mq:polling fetchSize="9">
              <scheduling-strategy>
                  <cron expression="0 * 14 * * ?"
                  timeZone="America/Los_Angeles"/>
              </scheduling-strategy>
          </anypoint-mq:polling>
      </anypoint-mq:subscriber-type>
  </anypoint-mq:subscriber>
  ```

This table lists the 2.x `polling` parameters and their 3.x equivalents.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Version 2.x Parameter</th><th>Description</th><th>Version 3.x Equivalent</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>fetchSize</code></p></div></div></td><td><div><div><p>Declared at the <code>config</code> level, controls the size of the local message buffer, which is calculated as three times the <code>fetchSize</code> value.</p></div></div></td><td><div><div><p><code>fetchSize</code></p></div></div></td><td><div><div><p>Declared at the <code>Subscriber</code> level, sets the maximum number (1-10) of messages to fetch on each polling execution. The default is 10.</p></div></div></td></tr><tr><td><div><div><p><code>fetchTimeout</code></p></div></div></td><td><div><div><p>Limits the wait time for a response from the service.</p></div></div></td><td><div><div><p>Deprecated</p></div></div></td><td><div><div><p>This parameter is no longer available. The connector always uses the maximum long-polling value.</p></div></div></td></tr><tr><td><div><div><p><code>frequency</code></p></div></div></td><td><div><div><p>Controls when to recheck for messages after the queue is empty.</p></div></div></td><td><div><div><p>Deprecated</p></div></div></td><td><div><div><p>This parameter is no longer available. The connector uses a fixed frequency of 1 second.</p></div></div></td></tr><tr><td><div><div><p><code>pollingTime</code></p></div></div></td><td><div><div><p>Used only when <code>fetchSize</code> is <code>0</code>, effectively disabling the <code>prefetch</code> mode and enabling <code>polling</code> mode.</p></div></div></td><td><div><div><p>Deprecated</p></div></div></td><td><div><div><p>This parameter is replaced by the more powerful <code>polling</code> subscriber type.</p></div></div></td></tr></tbody></table>

### Circuit Breaker

The circuit breaker declaration is no longer in `default-subscriber-config` and is either a global
element or an inline declaration.

In version 2.x of this connector, you declared the circuit breaker as part of the Subscriber
configuration and then referenced it across multiple Subscriber sources.

```xml
<anypoint-mq:default-subscriber-config name="ConfigWithCircuit" >
     <anypoint-mq:connection url="${providerUrl}"
       clientId="${clientId}"
      clientSecret="${clientSecret}"/>
   <anypoint-mq:circuit-breaker
       circuitName="InvoiceProcess"
       onErrorTypes="FTP:RETRY_EXHAUSTED, HTTP:SERVICE_UNAVAILABLE"
       errorsThreshold="10"
       tripTimeout="5"
       tripTimeoutUnit="MINUTES"/>
</anypoint-mq:default-subscriber-config>

<flow name="subscribe">
    <anypoint-mq:subscriber
        config-ref="ConfigWithCircuit"
        destination="${reservationsQueue}"/>
    <flow-ref name="invoiceProcess">
</flow>

<flow name="otherSubscribe">
    <anypoint-mq:subscriber
        config-ref="ConfigWithCircuit"
        destination="${paymentsQueue}"/>
    <flow-ref name="invoiceProcess">
</flow>

<sub-flow name="invoiceProcess">
  <ftp:write path="${auditFolder}" config-ref="ftp-config"/>
  <http:request config-ref="requestConfig" path="/external"/>
</sub-flow>
```

In version 3.x of this connector, you declare one standalone global element, and reference that
global element from each subscriber, no longer binding a connection to the app logic circuit:

```xml
<anypoint-mq:config name="Anypoint_MQ_Config">
    <anypoint-mq:connection url="${providerUrl}"
       clientId="${clientId}"
       clientSecret="${clientSecret}"/>
</anypoint-mq:config>

<anypoint-mq:circuit-breaker
    name="InvoiceProcess"
    onErrorTypes="FTP:RETRY_EXHAUSTED, HTTP:SERVICE_UNAVAILABLE"
    errorsThreshold="10"
    tripTimeout="5"
    tripTimeoutUnit="MINUTES"/>

<flow name="subscribe">
    <anypoint-mq:subscriber
        destination="${reservationsQueue}"
        config-ref="Anypoint_MQ_Config"
        circuitBreaker="GlobalCircuit"/>
    <flow-ref name="invoiceProcess">
</flow>

<flow name="otherSubscribe">
    <anypoint-mq:subscriber
        destination="${paymentsQueue}"
        config-ref="Anypoint_MQ_Config"
        circuitBreaker="GlobalCircuit"/>
    <flow-ref name="invoiceProcess">
</flow>

<sub-flow name="invoiceProcess">
  <ftp:write path="${auditFolder}" config-ref="ftp-config"/>
  <http:request config-ref="requestConfig" path="/external"/>
</sub-flow>
```

## Publish Operation

In version 2.x of this connector, Publish operation properties are declared like this:

```xml
<anypoint-mq:publish config-ref="Anypoint_MQ_Default_subscriber"
       destination="queue"
       messageId="#[vars.messageId]" sendContentType="false">
   <anypoint-mq:body >#[vars.messageBody]</anypoint-mq:body>
   <anypoint-mq:properties >
      <anypoint-mq:property key="MSG_TYPE" value="My Value"/>
   </anypoint-mq:properties>
</anypoint-mq:publish>
```

In version 3.x, you declare the same properties as a dynamic map, subject to transformations and a
dynamic number of keys, instead of having fixed keys for each message:

```xml
<anypoint-mq:publish config-ref="Anypoint_MQ_Config"
     destination="queue"
     messageId="#[vars.currentId]" sendContentType="false">
   <anypoint-mq:body >#[vars.messageBody]</anypoint-mq:body>
   <anypoint-mq:properties ><![CDATA[#[output application/java -----
{
   "MSG_TYPE" : vars.msgType
}]]]></anypoint-mq:properties>
</anypoint-mq:publish>
```

This table lists the 2.x Publish operation and its 3.x equivalents.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Changes</th><th>Version 2.x</th><th>Version 3.x</th></tr></thead><tbody><tr><td><p>Execution Type</p></td><td><p>Blocking</p></td><td><p>Non-Blocking</p></td></tr><tr><td><p>Properties Parameter</p></td><td><p>Fixed key-value map</p></td><td><p>Dynamic "content" parameter map</p></td></tr></tbody></table>

For more information, see [Anypoint MQ Publish Operation](https://docs.mulesoft.com/anypoint-mq-connector/3.x/anypoint-mq-publish)

## Consume Operation

This table lists the 2.x Consume operation and its 3.x equivalents.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Changes</th><th>Version 2.x</th><th>Version 3.x</th></tr></thead><tbody><tr><td><p>Execution Type</p></td><td><p>Blocking</p></td><td><p>Non-Blocking</p></td></tr><tr><td><p>Default Acknowledgment Mode</p></td><td><p>MANUAL</p></td><td><p>IMMEDIATE</p></td></tr></tbody></table>

For more information, see [Anypoint MQ Consume Operation](https://docs.mulesoft.com/anypoint-mq-connector/3.x/anypoint-mq-consume).

## ACK and NACK Operations

The ACK and NACK operations use the `ackToken` string.

You can obtain `ackToken` from the `attributes` element. The `ackToken` value is available only for
messages that have a `MANUAL` acknowledgment mode.

This table lists the 2.x ACK and NACK operations and their 3.x equivalents.

<table><colgroup><col> <col></colgroup><thead><tr><th>Version 2.x</th><th>Version 3.x</th></tr></thead><tbody><tr><td><p>Operations received a <code>messageContext</code> parameter, whose value had to be the <code>attributes</code> element from a given message.</p></td><td><p>The <code>ackToken</code> string of the message for performing ACK or NACK of a message.</p></td></tr></tbody></table>

For more information, see [Anypoint MQ ACK and NACK Operations](https://docs.mulesoft.com/anypoint-mq-connector/3.x/anypoint-mq-ack).

## Platform Compatibility

<table><colgroup><col> <col></colgroup><thead><tr><th>Software</th><th>Version</th></tr></thead><tbody><tr><td><p>Mule Runtime Engine</p></td><td><p>4.1.1 and later</p></td></tr><tr><td><p>Anypoint Studio</p></td><td><p>v7 and later</p></td></tr></tbody></table>