---
schema_version: "1"
id: 1ff563e4807c3c3f2323a138b5e0a5ceba04952e1df9be4bdc8dc05d6ed21160
title: Upgrading and Migrating IBM MQ Connector to Version 2.x
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/ibm-mq-connector/latest/ibm-mq-connector-upgrade-migrate.md
canonical_url: https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-connector-upgrade-migrate
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 7a3dc5a3db75b724864eb855d77784857b2800b75b2846255a18fb68afffd0a5
description: MuleSoft Documentation Site
release: "2.0"
latest: true
---
---
product: IBM MQ Connector
version: 2.0
is-latest-version: true
---

# Upgrading and Migrating IBM MQ Connector to Version 2.x

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

Upgrade Anypoint Connector for IBM MQ (IBM MQ Connector) to version 2.x.

## Supported Upgrade Paths

<table><colgroup><col> <col></colgroup><thead><tr><th>From Version</th><th>To Version</th></tr></thead><tbody><tr><td><div><div><p>1.x</p></div></div></td><td><div><div><p>2.x</p></div></div></td></tr></tbody></table>

## Changes in This Release

IBM MQ Connector 2.x contains the following changes:

- This connector is now compatible with Java 17 only.

- This connector uses the Jakarta Messaging (`jakarta.jms`) namespace, replacing `javax.jms`.

- The recommended IBM MQ client library is now `com.ibm.mq.jakarta.client`, replacing
  `com.ibm.mq.allclient`.

- The `enableXa` attribute is removed from the connection configuration.

- IBM MQ Connector provides separate connection types for XA and non-XA transactions. You can now
  select the new **IBM MQ XA Connection** type in the **IBM MQ Config** window. This new connection
  type replaces the previous `enableXa` attribute on a single connection.

- The existing **IBM MQ Connection** type is now used only for non-XA scenarios.

- The connection element is renamed from `<ibm-mq:connection>` to `<ibm-mq:ibm-mq-connection>`.

- The **XA connection pool** configuration (**Min Pool Size**, **Max Pool Size**, and **Max Idle
  Seconds**) applies only to the **IBM MQ XA Connection** type.

- These libraries are upgraded:

  - The `jakarta.jms-api` library is upgraded to version 3.1.0, replacing `javax.jms-api`.

  - The IBM MQ client library is upgraded to `com.ibm.mq.jakarta.client` version 9.4.5.1.

  - The Spring framework is upgraded to version 6.2.19.

  - The Mule JMS client library is upgraded to version 2.0.1.

In version 1.x, you configured the connection by using the `<ibm-mq:connection>` element, and you
enabled XA transactions by setting the `enableXa` attribute on that same connection:

```xml
<ibm-mq:config name="IBM_MQ_Config">
  <ibm-mq:connection enableXa="true">
    <ibm-mq:connection-mode>
      <ibm-mq:client host="0.0.0.0" port="1414" queueManager="QM1" channel="DEV.ADMIN.SVRCONN"/>
    </ibm-mq:connection-mode>
  </ibm-mq:connection>
</ibm-mq:config>
```

In version 2.x, configure XA transactions using the new **IBM MQ XA Connection** connection type:

```xml
<ibm-mq:config name="IBM_MQ_Config">
  <ibm-mq:ibm-mq-xa-connection>
    <ibm-mq:connection-mode>
      <ibm-mq:client host="0.0.0.0" port="1414" queueManager="QM1" channel="DEV.ADMIN.SVRCONN"/>
    </ibm-mq:connection-mode>
  </ibm-mq:ibm-mq-xa-connection>
</ibm-mq:config>
```

Non-XA connections require the element rename only. Change `<ibm-mq:connection>` to
`<ibm-mq:ibm-mq-connection>`:

```xml
<ibm-mq:config name="IBM_MQ_Config">
  <ibm-mq:ibm-mq-connection>
    <ibm-mq:connection-mode>
      <ibm-mq:client host="0.0.0.0" port="1414" queueManager="QM1" channel="DEV.ADMIN.SVRCONN"/>
    </ibm-mq:connection-mode>
  </ibm-mq:ibm-mq-connection>
</ibm-mq:config>
```

Both connection types accept the same connection parameters. The **IBM MQ XA Connection** type adds
the **Min Pool Size** (`minPoolSize`), **Max Pool Size** (`maxPoolSize`), and **Max Idle Seconds**
(`maxIdleSeconds`) XA connection pool parameters, which default to `4`, `32`, and `60`. For more
information, see [IBM MQ XA Connection](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref#config_xa_connection).

## Requirements

Ensure your system meets the following compatibility requirements before you perform the upgrade:

<table><colgroup><col> <col></colgroup><thead><tr><th>Application/Service</th><th>Version</th></tr></thead><tbody><tr><td><p>Mule runtime</p></td><td><p>4.10 and later</p></td></tr><tr><td><p>Java</p></td><td><p>17</p></td></tr><tr><td><p>Anypoint Studio</p></td><td><p>7.21 and later</p></td></tr></tbody></table>

Mule versions 4.4, 4.6, and 4.9 are not supported. Applications on these versions must remain on IBM
MQ Connector 1.x. Upgrade the Mule runtime and JDK in all environments before you upgrade the
connector, because the connector doesn’t load on earlier runtimes.

## Upgrade Prerequisites

Before you perform the upgrade, create a backup of your files, data, and configuration in case you
need to restore to the previous version.

## Upgrade Steps

Follow these steps to perform the upgrade to version 2.x:

1.  In Anypoint Studio, create a Mule project.

2.  In the **Mule Palette** view, click **Search in Exchange**.

3.  In **Add Dependencies to Project**, enter `ibm mq` in the search field.

4.  In **Available modules**, select **IBM MQ Connector** and click **Add**.

5.  Click **Finish**.

6.  Verify that the IBM MQ Connector dependency version is `2.x` in the project’s `pom.xml` file:

    ```xml
    <dependency>
      <groupId>com.mulesoft.connectors</groupId>
      <artifactId>mule-ibm-mq-connector</artifactId>
      <version>2.0.0</version>
      <classifier>mule-plugin</classifier>
    </dependency>
    ```

Studio upgrades the connector automatically, but configuration changes are required.

## Post-Upgrade Steps

After you install the latest version of the connector, complete the following steps:

1.  Replace the `com.ibm.mq.allclient` library with the Jakarta Messaging client library in the
    project’s `pom.xml` file:

    ```xml
    <dependency>
        <groupId>com.ibm.mq</groupId>
        <artifactId>com.ibm.mq.jakarta.client</artifactId>
        <version>9.4.5.1</version>
    </dependency>
    ```

    If you keep the `com.ibm.mq.allclient` library, the connector wraps it to expose a `jakarta.jms`
    connection factory. This backward compatibility support is best-effort only. For details and
    limitations, see [Support for the Legacy javax.jms Client Library](https://docs.mulesoft.com/ibm-mq-connector/latest/#javax-client-library).

2.  Rename each `<ibm-mq:connection>` element to `<ibm-mq:ibm-mq-connection>`.

3.  In each **IBM MQ Config** global element that uses XA transactions, change the **Connection**
    field to **IBM MQ XA Connection**.

4.  Remove any reference to the `enableXa` attribute, if present, because it no longer exists on the
    connection configuration.

5.  Move any **XA connection pool** configuration (**Min Pool Size**, **Max Pool Size**, and **Max
    Idle Seconds**) to the new XA connection element.

6.  Make sure all environments run on Mule 4.10 or later and use JDK 17, and update the Maven build
    configuration to use a JDK 17 toolchain.

For more information, see [Handling Transactions in IBM MQ](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-transactions).

## Verify the Upgrade

After you install the latest version of the connector, follow these steps to verify the upgrade:

1.  In Studio, verify that there are no errors in the **Problems** or **Console** views.

2.  Verify that there are no problems in the project `pom.xml` file.

3.  Verify that no `enableXa` attributes and no `<ibm-mq:connection>` elements remain in your
    configurations.

4.  Test the connection to verify that the operations work.

5.  Verify that the application log doesn’t contain a warning about the legacy `javax.jms` client
    library.

6.  If your app uses XA transactions, verify that the corresponding XA connection type is configured
    and that transactions still commit and roll back as expected.

## Revert the Upgrade

If it is necessary to revert to the previous version of IBM MQ Connector, change the
`mule-ibm-mq-connector` dependency version in the project’s `pom.xml` file to the previous version,
and revert any XA connection elements back to the `<ibm-mq:connection>` element with the `enableXa`
attribute set. Restore the `com.ibm.mq.allclient` IBM MQ client library.

You must update the project’s `pom.xml` file in Anypoint Studio.

Reverting requires an environment that is compatible with version 1.x requirements.

## Troubleshooting

If you encounter issues, perform these troubleshooting steps.

### Troubleshoot Startup Parse Failures

If the application fails to start with an unknown-attribute or unknown-element error, follow these
steps:

1.  Replace the `enableXa="true"` attribute with the `<ibm-mq:ibm-mq-xa-connection>` element.

2.  Rename `<ibm-mq:connection>` elements to `<ibm-mq:ibm-mq-connection>`.

### Troubleshoot Runtime Compatibility Issues

If the application fails to deploy with a JDK or Mule runtime error, follow these steps:

1.  Upgrade to Mule 4.10 or later. Earlier versions can’t load this connector version.

2.  Upgrade to JDK 17.

### Troubleshoot Connection Failures That Report shim:javax-fallback

If connection failure messages end with `[shim:javax-fallback]`, the connector is using the legacy
`com.ibm.mq.allclient` library through the backward compatibility wrapper. Replace that library with
`com.ibm.mq.jakarta.client` 9.4.5.1.

## See Also

- [IBM MQ Connector Overview](https://docs.mulesoft.com/ibm-mq-connector/latest/)

- [Handling Transactions in IBM MQ](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-transactions)

- [IBM MQ Connector Reference](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref)

- [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors)

- [Salesforce Help](https://help.salesforce.com)