---
schema_version: "1"
id: 9c47403de4b0adbdbebfd796ea909540486735d9e2bfcdfe4517c577679c32b8
title: Handling Transactions in IBM MQ
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/ibm-mq-connector/latest/ibm-mq-transactions.md
canonical_url: https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-transactions
source_site: docs.mulesoft.com
content_type: documentation
content_hash: f8b811cc5b07bf2d8e81becc4da2a9f5c46f81e5ca8ba2b13fbcee6a013004e5
description: MuleSoft Documentation Site
release: "2.0"
latest: true
---
---
product: IBM MQ Connector
version: 2.0
is-latest-version: true
keywords: jms, ibm mq, mq, xa, connector, transactions, transactional
---

# Handling Transactions in IBM MQ

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

Transactional connections in IBM MQ allow you to execute a series of operations that are actually
performed only when the transaction is committed. This has two main scenarios:

- Publishing a message as part of a transaction: When publishing, a message is sent to the
  destination after the transaction commits. If for some reason the transaction fails and a rollback
  occurs, then the message is not sent.

- Consuming a message as part of a transaction: When consuming a message, either with the listener
  or consume, the message is acknowledged only after the transaction is committed, and instead it’s
  returned to the destination for redelivery if the transaction is rolled-back.

The IBM MQ connector provides support for executing its operations in a transactional way out of the
box using Mule’s transactionalAction configuration.

To execute an operation as part of the transaction, we have the following two options.

## Processing New Messages With Transactional Session

If you want a IBM MQ `On New Message` Listener to use a transactional session when dispatching the
messages, you should set the transactionalAction to ALWAYS\_BEGIN:

```xml
<ibm-mq:listener
     config-ref="IBM_MQ_Config"
     destination="${originQueue}"
     transactionalAction="ALWAYS_BEGIN"/>
```

With this configuration, each new message is processed in a transaction that is propagated to all
the flow’s components and is committed once the flow execution is completed successfully. The
transaction is rolled back if the flow execution completes with an error.

**Note:** By default, other components in the flow do not join the transaction created by the
listener. To execute other operations using the listener’s transaction, you must declare them either
with ALWAYS\_JOIN, or JOIN\_IF\_POSSIBLE.

## Execute Operations As Part Of A Transaction

To execute an operation like publish or consume as part of a transaction, set transactionalAction to
ALWAYS\_JOIN or JOIN\_IF\_POSSIBLE:

This operations can join a transaction initiated by the listener:

```xml
<flow name="joiningToListenerTransaction">
    <ibm-mq:listener config-ref="IBM_MQ_Config"
      destination="${originQueue}"
      transactionalAction="ALWAYS_BEGIN"/>
    <ibm-mq:publish config-ref="IBM_MQ_Config"
      destination="#[attributes.properties.userProperties.redirectDestination]"
      transactionalAction="JOIN_IF_POSSIBLE"/>
    <ibm-mq:consume config-ref="IBM_MQ_Config"
      destination="#[attributes.properties.userProperties.callbackDestination]"
      transactionalAction="JOIN_IF_POSSIBLE"/>
</flow>
```

Or join a scoped transaction:

```xml
<flow name="nonTxPublishMustNotJoinCurrentTx">
    <http:listener config-ref="HTTP_Config" path="/orders"/>
    <try transactionalAction="ALWAYS_BEGIN">
        <ibm-mq:publish config-ref="config"
	destination="${billingService}"
	transactionalAction="ALWAYS_JOIN"/>
        <ibm-mq:publish config-ref="config"
	destination="${shipmentService}"
	transactionalAction="ALWAYS_JOIN"/>
        <ibm-mq:publish-consume config-ref="IBM_MQ_Config"
	destination="${invoicesVerificationService}"/>
        <validation:is-true expression="#[payload]"/>
    </try>
</flow>
```

## XA Transactions

IBM MQ Connector supports a create and join XA transactions feature that enables the connector to
participate in a transaction with multiple resources. This also enables the connector to execute
transactional actions with other connections of IBM MQ or other connectors such as Database
Connector or VM Connector.

> [!NOTE] IBM MQ Connector does not support nested XA transactions because of an IBM MQ driver
> limitation. When you work with nested transactions, outer transactions get suspended and then
> resume after the inner transactions finish. The failure occurs when the outer transactions are
> resumed, due to the driver implementation.

> [!NOTE] In version 2.0, the `enableXa` attribute is removed. Use the
> `<ibm-mq:ibm-mq-xa-connection>` element instead. Applications that still specify `enableXa` fail
> to start with an unknown-attribute error. See
> [Upgrading and Migrating IBM MQ Connector](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-connector-upgrade-migrate).

To enable XA transactions:

1.  Create an XA connection by using the `<ibm-mq:ibm-mq-xa-connection>` element. In Studio, select
    **IBM MQ XA Connection** in the **Connection** field of the global element configuration:

    ```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" queueManager="QM1" />
    			</ibm-mq:connection-mode>
    		</ibm-mq:ibm-mq-xa-connection>
    	</ibm-mq:config>
    ```

    Optionally, configure the XA connection pool by setting the **Min Pool Size** (`minPoolSize`),
    **Max Pool Size** (`maxPoolSize`), and **Max Idle Seconds** (`maxIdleSeconds`) parameters, which
    default to `4`, `32`, and `60`. For details, see
    [IBM MQ XA Connection](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref#config_xa_connection).

2.  Configure to create a XA Transaction: Set transactionType to XA:

    ```xml
    <flow name="joiningToListenerTransaction">
        <ibm-mq:listener config-ref="IBM_MQ_Config"
        destination="${originQueue}"
        transactionalAction="ALWAYS_BEGIN"
        transactionType="XA"/>
        <ibm-mq:publish config-ref="IBM_MQ_Config"
        destination="#[attributes.properties.userProperties.redirectDestination]"
        transactionalAction="JOIN_IF_POSSIBLE"/>
        <ibm-mq:consume config-ref="IBM_MQ_Config"
        destination="#[attributes.properties.userProperties.callbackDestination]"
        transactionalAction="JOIN_IF_POSSIBLE"/>
    </flow>
    ```

    Or join a scoped transaction:

    ```xml
    <flow name="nonTxPublishMustNotJoinCurrentTx">
        <http:listener config-ref="HTTP_Config" path="/orders"/>
        <try transactionalAction="ALWAYS_BEGIN" transactionType="XA">
            <ibm-mq:publish config-ref="config"
    	destination="${billingService}"
    	transactionalAction="ALWAYS_JOIN"/>
            <ibm-mq:publish config-ref="config"
    	destination="${shipmentService}"
    	transactionalAction="ALWAYS_JOIN"/>

            <ibm-mq:publish-consume config-ref="IBM_MQ_Config"
    	destination="${invoicesVerificationService}"/>
            <validation:is-true expression="#[payload]"/>
        </try>
    </flow>
    ```