<a id="ibmmq-source-connector"></a>

# IBM MQ Source Connector for Confluent Platform

The Kafka Connect IBM MQ Source connector reads messages from an
[IBM MQ](https://www-03.ibm.com/software/products/en/ibm-mq) cluster using
JMS (Java Message Service) and writes them to a Apache Kafka® topic.

Before using this connector, consider the following:

- Confluent Platform also includes a general [JMS Source connector](https://docs.confluent.io/kafka-connectors/jms-source/current/overview.html)
  that uses a JNDI (Java Naming and Directory Interface)-based mechanism to
  connect to the JMS broker. If you have to use JNDI to connect to your JMS
  broker, consider using the JMS Source connector instead.
- The 11.x version of this is connector does not support at-least-once semantics
  and is no longer supported. To upgrade to a 12.x version, see
  [Migrate from 11.x to 12.x](#ibmmq-source-migration).
- You must [download the IBM MQ client library JAR](#ibmmq-source-connector-client-libs) files to use this connector.
- <!-- WARNING: THIS IS A SHARED FILE AND THE SOURCE IS LOCATED IN DOCS-COMMON. DO NOT ADD TO ANY OTHER REPO. -->

  Effective July 6, 2025, only self-managed connector versions that meet or exceed the minimum version listed on the
  [Supported Connector Versions](https://docs.confluent.io/platform/7.8/connect/supported-connector-version.html#supported-connector-versions-till-cp-7-8)
  page receive support from Confluent. Older, unsupported connector versions have been removed from Confluent Marketplace and
  are no longer available for download.

## Features

The IBM MQ Source connector includes the following features:

- [At least once delivery](#ibmmq-source-connector-at-least-once-delivery)—delivers each message
  at least once by default.
- [Exactly once delivery](#ibmmq-source-connector-exactly-once-delivery)—delivers each message
  exactly once when configured with a state topic.
- [Run multiple connector tasks](#ibmmq-source-connector-multiple-tasks)—runs one or more tasks to
  increase throughput.
- [JMS message types](#ibmmq-source-connector-jms-message-types)—supports `TextMessage`
  and `BytesMessage` JMS message types.
- [Retries and reconnection](#ibmmq-source-connector-retries-and-reconnection)—retries with
  exponential back-off after connection errors.
- [Message acknowledgement](#ibmmq-source-connector-message-acknowledgement)—acknowledges
  messages in IBM MQ after they’re delivered to Kafka or the pending-message
  limit is reached.
- [Configure a custom credentials provider](#ibmmq-source-credentials-provider-support)—supports a custom
  credentials provider for authentication.
- [Client-side encryption](#ibmmq-source-csfle-sm)—supports client-side field level encryption
  (CSFLE) for sensitive data.

### Delivery guarantee

The connector can run in either of the following depending on the connector and worker configuration:

- [At least once delivery](#ibmmq-source-connector-at-least-once-delivery)
- [Exactly once delivery](#ibmmq-source-connector-exactly-once-delivery)

<a id="ibmmq-source-connector-at-least-once-delivery"></a>

#### At least once delivery

This connector guarantees that records are delivered at least once to the Kafka
topic. If the connector restarts, there may be some duplicate
records in the Kafka topic.

The IBM MQ Source connector supports two JMS destination types: `queue` and
`topic`. The following table describes when to use each type and how each
affects message durability.

| Destination type   | When to use                                                                                                                                                      | Durability behavior                                                                                                             |
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `queue`            | A single consumer reads from the destination. This is the<br/>recommended type when the connector is the only consumer of the<br/>source destination.            | Messages are persisted in the queue and delivered at least once.                                                                |
| `topic`            | Multiple consumers read from the same destination. This is the<br/>recommended type so the connector and other consumers all receive<br/>the broadcast messages. | You must set `jms.subscription.durable` to `true`. JMS topics<br/>don’t persist messages unless you use a durable subscription. |

#### NOTE
Enabling exactly once settings shifts the connector from at least once delivery to [Exactly once delivery](#ibmmq-source-connector-exactly-once-delivery).

<a id="ibmmq-source-connector-exactly-once-delivery"></a>

#### Exactly once delivery

The connector supports exactly once semantics when the following conditions are met:

- All the connect workers in the cluster have the [exactly.once.source.support](https://docs.confluent.io/platform/current/installation/configuration/connect/index.html#exactly-once-source-support) property set to `enabled`. For more information, see [exactly once source worker](https://kafka.apache.org/documentation.html#connect_exactlyoncesource) .
- The connect worker is running in a distributed mode. Exactly once delivery cannot be supported in standalone mode.
- The connect worker principal should have the required ACLs. For more information on the required ACLs, see [ACLs for exactly once source](https://kafka.apache.org/documentation.html#connect_exactlyonce) .
- The connector is configured with the `state.topic.name` property.

#### NOTE
When configuring `state.topic.name`, use the MQ topic string value (for example, `/kafkaConnect/stateTopics/connector_name`).
If you use the MQ topic name (administrative name), the connection fails.

When these conditions are met, the connector processes each record exactly once, even through failures or restarts.
It uses the state topic to track progress of the records it has processed, allowing it to resume from the last
processed record in case of a failure. You must set the state topic only when you first create the connector.
Changing the topic name after the connector creation can result in duplicates.

For exactly once semantics, the connector requires only one consumer of the MQ destination. Hence, it doesn’t support more than one task or receiver thread.

The connector uses a transactional producer for writing records to the Kafka topic, guaranteeing exactly once delivery.
Any Kafka consumer reading from the topic must also set [isolation.level](https://docs.confluent.io/platform/current/installation/configuration/consumer-configs.html#isolation-level) property to `read_committed`.

#### NOTE
If the Connect cluster doesn’t meet these requirements, the connector
guarantees that records are delivered at least once to the Kafka topic. If the
connector restarts, it can deliver duplicate records to the Kafka topic.

When you configure the connector to consume from a priority queue in MQ, the MQ may deliver messages out of order. Under this condition, the connector cannot guarantee exactly once semantics and may fail.

<a id="ibmmq-source-connector-multiple-tasks"></a>

### Run multiple connector tasks

The IBM MQ Source connector supports running one or more tasks. You can specify
the number of tasks in the `tasks.max` configuration parameter. This can lead
to performance gains when multiple files need to be parsed.

#### NOTE
The connector does not support running multiple tasks when the exactly once settings are enabled for the connector.

<a id="ibmmq-source-connector-jms-message-types"></a>

### JMS message types

The connector currently supports [TextMessage](https://docs.oracle.com/javaee/6/api/javax/jms/TextMessage.html) and
[BytesMessage](https://docs.oracle.com/javaee/6/api/javax/jms/BytesMessage.html). The
connector does not currently support [ObjectMessage](https://docs.oracle.com/javaee/6/api/javax/jms/ObjectMessage.html) or
[StreamMessage](https://docs.oracle.com/javaee/6/api/javax/jms/StreamMessage.html).

<a id="ibmmq-source-connector-retries-and-reconnection"></a>

### Retries and reconnection

The IBM MQ Source connector uses the general retry policy implemented for most
Confluent connectors; however, the IBM MQ Source connector uses exponential
backoff after each retry attempt. The backoff time is the time between retries
and is a random value between zero and the exponentially increasing bound:

```text
initialbackoffTime * 2 ^ (retry-1)
```

The exponential bound is capped at one minute, and the initial backoff time is
100 milliseconds (ms). The [max.retry.time configuration property](source_connector_config.md#ibmmq-source-connector-config) controls the maximum total time the connector
spends retrying before failure—the default value is 3600000 ms (one hour). The
total number of retry attempts isn’t configurable.

The following errors will trigger a retry:

* `MQRC_GET_INHIBITED`
* `MQRC_BACKED_OUT`
* `MQRC_CHANNEL_NOT_AVAILABLE`
* `MQRC_CONNECTION_BROKEN`
* `MQRC_HOST_NOT_AVAILABLE`
* `MQRC_NOT_AUTHORIZED`
* `MQRC_Q_MGR_NOT_AVAILABLE`
* `MQRC_Q_MGR_QUIESCING`
* `MQRC_Q_MGR_STOPPING`
* `MQRC_UNEXPECTED_ERROR`

Except for `MQRC_GET_INHIBITED`, all other errors in this list first shut
down the connection and then reconnect before retrying.

<a id="ibmmq-source-connector-message-acknowledgement"></a>

### Message acknowledgement

The IBM MQ Source connector sends an acknowledgement message when one of the
following occurs:

- IBM MQ no longer has any more records to deliver.
- The `max.pending.messages` configuration limit has been breached.

To ensure each batch sends an acknowledgement, you must set `batch.size` and
`max.pending.messages` to an equal value.

<a id="ibmmq-source-csfle-sm"></a>

### Client-side encryption

This connector supports Client-Side Field Level Encryption (CSFLE) and Client-Side Payload Encryption (CSPE). For more information, see [Manage Client-Side Encryption](https://docs.confluent.io/platform/current/connect/manage-csfle.html).

<a id="ibmmq-source-credentials-provider-support"></a>

### Configure a custom credentials provider

You can configure the IBM MQ connector to use a custom credentials provider.
To do this, you implement a custom credentials provider, build it
as a JAR file, and deploy the JAR file to use the custom provider.

Complete the following steps to use a custom credentials provider:

1. **Set a custom credentials provider class**: Set the `credentials.provider.classpath` property to a class that implements the `io.confluent.connect.ibm.mq.creds.IbmMqCredentialsProvider`. Configure the class to the fully qualified name of your custom credentials provider class.
2. **Configure additional settings (Optional)**: For additional configuration, prefix the configuration keys with `credentials.provider.` . If your custom credentials provider needs to accept additional configuration, implement the `org.apache.kafka.common.Configurable` interface that lets the connector receive configurations that are prefixed with `credentials.provider.`.
3. **Package your provider**: Once your custom credentials provider class is implemented, package it into a JAR file.
4. **Copy the JAR file to Connect Worker**: Copy the built JAR file to the `share/java/kafka-connect-ibmmq-source` directory on all Connect workers. This step ensures that the IBM MQ connector can access and use your custom credentials provider.

To implement the custom credentials provider, you need to implement the following interface:

**IbmMqCredentialsProvider Interface**

```java
package io.confluent.connect.ibm.mq.creds;

public interface IbmMqCredentialsProvider {
    /**
      * Interface for providing dynamic credentials to IBM MQ connections.
      * Can be used with any other authentication mode (like OAuth2) combined
      * with security exits for authentication flow.
      */
    void setCredentials();

    /**
      * Gets the username/password required for IBM MQ authentication.
      */
    IbmMqCredentials getCredentials();
}
```

**IbmMqCredentials Class**

```java
package io.confluent.connect.ibm.mq.creds;

public class IbmMqCredentials {
    private final String username;
    private final String password;

    public IbmMqCredentials(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public String username() {
        return username;
    }

    public String password() {
        return password;
    }
}
```

<a id="ibmmq-source-connector-license-key"></a>

## License

You can use this connector for a 30-day trial period without a license key.

After 30 days, you must purchase a connector subscription which includes [Confluent enterprise license](/platform/current/installation/license.html#enterprise-subscription-license) keys to subscribers, along with [enterprise-level support](https://www.confluent.io/subscription/) for Confluent Platform and your connectors. If you are a subscriber, you can contact [Confluent Support](https://support.confluent.io/) for more information.

See [Confluent license properties](source_connector_config.md#ibmmq-source-connector-license-config)
for license properties and information about the license topic.

## Linux on IBM Z (s390x) support

Starting with Confluent Platform 8.2, this connector supports Linux on IBM Z (s390x).
The connector supports the same capability available on x86_64 unless
otherwise noted. For more information, see [Linux on IBM Z (s390x) support](https://docs.confluent.io/platform/current/installation/versions-interoperability.html#linux-on-ibm-z-s390x-support).

## IBM MQ Source connector configuration properties

For a complete list of configuration properties for this connector, see
[Configuration Reference for IBM MQ Source Connector for Confluent Platform](source_connector_config.md#ibmmq-source-connector-config). To understand how the connector internally
configures the acknowledgement mode, see the following section.

For an example of how to get Kafka Connect connected to [Confluent Cloud](/cloud/current/index.html), see
[Connect Self-Managed Kafka Connect to Confluent Cloud](/cloud/current/cp-component/connect-cloud-config.html#distributed-cluster).

<a id="ibmmq-source-ack-mode"></a>

### Acknowledgement mode

The connector internally uses `CLIENT_ACKNOWLEDGE` mode to receive and
acknowledge messages from the JMS broker. In this mode, acknowledging any
message will acknowledge every message received (see section 6.2.10 in the [JMS
2.0 Specification](https://download.oracle.com/otndocs/jcp/jms-2_0-fr-eval-spec/)). To prevent
messages from being prematurely acknowledged, the connector processes only one
message at time. In other words, the connector will not try to receive new
messages until the last message is committed to a Kafka topic. This might
compromise the throughput of the connector, but messages will be transferred to
Kafka successfully.

<a id="ibmmq-source-migration"></a>

## Migrate from 11.x to 12.x

Users who have previously deployed an 11.x version can leverage at-least-once
semantics by migrating to a 12.x version using the following steps:

### Step 1: Stop Connect

Stop Connect using the [Shutting Down Kafka Connect](https://docs.confluent.io/kafka-connectors/self-managed/userguide.html#shutting-down-kconnect-long)
instructions. Connect performs classloading only during worker startup. To
identify any later plugins, you must restart the entire worker.

### Step 2: Install a later version of IBM MQ Source connector

- To install a later version of IBM MQ Source connector using the
  Confluent CLI, run a command similar to the following:
  ```bash
  confluent connect plugin install confluentinc/kafka-connect-ibmmq:12.x
  ```

  This will install the 12.x version of IBM MQ Source connector. While running
  the previous command, ensure you choose the option to replace the existing
  connector.
- To install an later version of IBM MQ Source connector manually, follow the
  instructions in [Installing plugins](https://docs.confluent.io/kafka-connectors/self-managed/userguide.html#installing-plugins).

### Step 3: Start Kafka Connect

- For standalone mode, follow the steps in [Standalone Mode](https://docs.confluent.io/kafka-connectors/self-managed/userguide.html#standalone-mode).
- For distributed mode, follow the steps in [Distributed Mode](https://docs.confluent.io/kafka-connectors/self-managed/userguide.html#distributed-mode).
- For running Kafka in production, see [Running Kafka in Production](https://docs.confluent.io/platform/current/kafka/deployment.html).

## Install the IBM MQ Source Connector

You can install this connector by using the [Confluent Hub Client installation
instructions](https://docs.confluent.io/home/connect/confluent-hub/client.html), or by
manually downloading the ZIP file.

### Prerequisites

The following are required to install and run the Connect IBM MQ Source connector:

- [IBM MQ 8.0.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_8.0.0/com.ibm.mq.pro.doc/q001010_.htm)
  or later, or [IBM MQ on Cloud](https://www.ibm.com/cloud/mq) service.
- You must install the connector on every machine where Connect will run.
- If you want to install the connector using Confluent Marketplace, you must install
  the [Confluent Hub Client](https://docs.confluent.io/home/connect/confluent-hub/client.html). This
  is installed by default with Confluent Enterprise.
- An installation of the IBM MQ client library JAR files. For help with
  downloading the JAR files, see the [Download the IBM MQ client library JAR files](#ibmmq-source-connector-client-libs)
  section.

### Install the connector using the Confluent CLI

To install the `latest` connector version using [Confluent Hub Client](https://www.confluent.io/hub/), navigate to your Confluent Platform installation directory
and run the following command:

```bash
confluent connect plugin install confluentinc/kafka-connect-ibmmq:latest
```

You can install a specific version by replacing `latest` with a version number
as shown in the following example:

```bash
confluent connect plugin install confluentinc/kafka-connect-ibmmq:13.1.0
```

### Install the connector manually

[Download and extract the ZIP file](https://www.confluent.io/hub/confluentinc/kafka-connect-ibmmq) for your
connector and then follow the manual connector installation [instructions](https://docs.confluent.io/home/connect/install.html).

<a id="ibmmq-source-connector-client-libs"></a>

## Download the IBM MQ client library JAR files

To use the Kafka Connect IBM MQ connector, you must download the IBM MQ client
library JAR files. To download the required JAR files, complete the following
steps:

1. Follow IBM’s [Getting the IBM MQ classes for Java and JMS](https://www-01.ibm.com/support/docview.wss?uid=swg21683398) instructions
   to download the IBM MQ client JAR.
2. Copy only the `com.ibm.mq.allclient.jar` file into the
   `share/confluent-hub-components/confluentinc-kafka-connect-ibmmq/lib`
   directory of your Confluent Platform installation on each Connect worker node.
3. Restart all of the Connect worker nodes.

<a id="ibmmq-source-connection"></a>

## Connect to IBM MQ

This connector connects directly to IBM MQ using configuration properties
that match your environment. Before you begin, install the IBM MQ client JARs
into this connector’s installation directory—see
[Download the IBM MQ client library JAR files](#ibmmq-source-connector-client-libs).

The following example shows a typical configuration of the connector for use
with [distributed mode](/platform/current/connect/concepts.html#distributed-workers):

```bash
{
  "name": "connector1",
  "config": {
    "connector.class": "io.confluent.connect.ibm.mq.IbmMQSourceConnector",
    "kafka.topic":"MyKafkaTopicName",
    "mq.hostname":"localhost",
    "mq.port":"61616",
    "mq.transport.type":"client",
    "mq.queue.manager":"QMA",
    "mq.channel":"SYSTEM.DEF.SVRCONN",
    "jms.destination.name":"testing",
    "jms.destination.type":"queue",
    "confluent.license":"",
    "confluent.topic.bootstrap.servers":"localhost:9092"
  }
}
```

The connector also supports other [configuration options](source_connector_config.md#ibmmq-source-connector-config) beyond those shown in this JSON
configuration.

<a id="ibmmq-source-connector-topics"></a>

## How the connector writes to Kafka topics

This connector consumes messages from IBM MQ using the configured [message
selectors](source_connector_config.md#ibmmq-source-connector-config) and writes them to a single Kafka
topic. If you want to write messages to multiple topics, use a simple message
transform that routes the messages based upon your criteria.

<a id="ibmmq-source-connector-schemas"></a>

## Schemas

The IBM MQ connector produces messages with keys and values that adhere to the
schemas described in the following sections.

<a id="ibmmq-source-connector-schema-key"></a>

### io.confluent.connect.jms.Key

This schema is used to store the incoming MessageID on the message interface.
This will ensure that when that if the same message id arrives it will end up in
the same partition. In practice this should never occur. The schema defines the
following fields:

| Name      | Schema   | Required   | Default Value   | Documentation                                                                                                                                  |
|-----------|----------|------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| messageID | STRING   | yes        |                 | This field stores the value of<br/>[Message.getJMSMessageID()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSMessageID()). |

<a id="ibmmq-source-connector-schema-value"></a>

### io.confluent.connect.jms.Value

This schema is used to store the value of the JMS message. The schema defines
the following fields:

| Name          | Schema                                                                       | Required   | Default Value   | Documentation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|---------------|------------------------------------------------------------------------------|------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| messageID     | STRING                                                                       | yes        |                 | This field stores the value of<br/>[Message.getJMSMessageID()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSMessageID()).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| messageType   | STRING                                                                       | yes        |                 | This field stores the type of message that was received. This corresponds<br/>to the sub-interfaces of [Message](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html).<br/>[BytesMessage](https://docs.oracle.com/javaee/6/api/javax/jms/BytesMessage.html) =<br/>`bytes`, [MapMessage](https://docs.oracle.com/javaee/6/api/javax/jms/MapMessage.html) = `map`,<br/>[ObjectMessage](https://docs.oracle.com/javaee/6/api/javax/jms/ObjectMessage.html) =<br/>`object`, [StreamMessage](https://docs.oracle.com/javaee/6/api/javax/jms/StreamMessage.html) =<br/>`stream` and [TextMessage](https://docs.oracle.com/javaee/6/api/javax/jms/TextMessage.html) =<br/>`text`. The corresponding field will be populated with the values from the<br/>respective message sub-interface. |
| timestamp     | INT64                                                                        | yes        |                 | Data from the [getJMSTimestamp()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSTimestamp())<br/>method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| deliveryMode  | INT32                                                                        | yes        |                 | This field stores the value of [Message.getJMSDeliveryMode()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSDeliveryMode()).<br/>method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| correlationID | STRING                                                                       | no         |                 | This field stores the value of [Message.getJMSCorrelationID()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSCorrelationID()).<br/>method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| replyTo       | [Destination](#ibmmq-source-connector-schema-destination)                    | no         |                 | This schema is used to represent a JMS Destination, and is either [queue](https://docs.oracle.com/javaee/6/api/javax/jms/Queue.html) or [topic](https://docs.oracle.com/javaee/6/api/javax/jms/Topic.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| destination   | [Destination](#ibmmq-source-connector-schema-destination)                    | no         |                 | This schema is used to represent a JMS Destination, and is either [queue](https://docs.oracle.com/javaee/6/api/javax/jms/Queue.html) or [topic](https://docs.oracle.com/javaee/6/api/javax/jms/Topic.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| redelivered   | BOOLEAN                                                                      | yes        |                 | This field stores the value of [Message.getJMSRedelivered()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSRedelivered()).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| type          | STRING                                                                       | no         |                 | This field stores the value of [Message.getJMSType()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSType()).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| expiration    | INT64                                                                        | no         |                 | This field stores the value of [Message.getJMSExpiration()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSExpiration()).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| priority      | INT32                                                                        | no         |                 | This field stores the value of [Message.getJMSPriority()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSPriority()).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| properties    | Map of STRING, [PropertyValue](#ibmmq-source-connector-schema-propertyvalue) | yes        |                 | This field stores the data from all of the properties for the Message indexed by their propertyName.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| bytes         | BYTES                                                                        | no         |                 | This field stores the value from<br/>[BytesMessage.html.readBytes(byte[])](https://docs.oracle.com/javaee/6/api/javax/jms/BytesMessage.html#readBytes(byte[])).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| map           | Map of STRING, [PropertyValue](#ibmmq-source-connector-schema-propertyvalue) | no         |                 | This field stores the data from all of the map entries returned from<br/>[MapMessage.getMapNames()](https://docs.oracle.com/javaee/6/api/javax/jms/MapMessage.html#getMapNames())<br/>for the Message indexed by their key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| text          | STRING                                                                       | no         |                 | This field stores the value from [TextMessage.html.getText()](https://docs.oracle.com/javaee/6/api/javax/jms/TextMessage.html#getText()).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

<a id="ibmmq-source-connector-schema-destination"></a>

### io.confluent.connect.jms.Destination

This schema is used to represent a JMS Destination, and is either [queue](https://docs.oracle.com/javaee/6/api/javax/jms/Queue.html) or [topic](https://docs.oracle.com/javaee/6/api/javax/jms/Topic.html). The schema
defines the following fields:

| Name            | Schema   | Required   | Default Value   | Documentation                                                                                                                                                                                                                                                        |
|-----------------|----------|------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| destinationType | STRING   | yes        |                 | The type of JMS Destination, and either `queue` or `topic`.                                                                                                                                                                                                          |
| name            | STRING   | yes        |                 | The name of the destination. This will be the value of<br/>[Queue.getQueueName()](https://docs.oracle.com/javaee/6/api/javax/jms/Queue.html#getQueueName())<br/>or [Topic.getTopicName()](https://docs.oracle.com/javaee/6/api/javax/jms/Topic.html#getTopicName()). |

<a id="ibmmq-source-connector-schema-propertyvalue"></a>

### io.confluent.connect.jms.PropertyValue

This schema is used to store the data that is found in the properties of the
message. To ensure that the proper type mappings are preserved field
`propertyType` stores the value type for the field. The corresponding field in
the schema will contain the data for the property. This ensures that the data is
retrievable as the type returned by [Message.getObjectProperty()](https://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getObjectProperty(java.lang.String)).
The schema defines the following fields:

| Name         | Schema   | Required   | Default Value   | Documentation                                                                                                                           |
|--------------|----------|------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| propertyType | STRING   | yes        |                 | The Java type of the property on the Message. One of `boolean`, `byte`,<br/>`short`, `integer`, `long`, `float`, `double`, or `string`. |
| boolean      | BOOLEAN  | no         |                 | The value stored as a boolean. Null unless `propertyType` is set to `boolean`.                                                          |
| byte         | INT8     | no         |                 | The value stored as a byte. Null unless `propertyType` is set to `byte`.                                                                |
| short        | INT16    | no         |                 | The value stored as a short. Null unless `propertyType` is set to `short`.                                                              |
| integer      | INT32    | no         |                 | The value stored as a integer. Null unless `propertyType` is set to `integer`.                                                          |
| long         | INT64    | no         |                 | The value stored as a long. Null unless `propertyType` is set to `long`.                                                                |
| float        | FLOAT32  | no         |                 | The value stored as a float. Null unless `propertyType` is set to `float`.                                                              |
| double       | FLOAT64  | no         |                 | The value stored as a double. Null unless `propertyType` is set to `double`.                                                            |
| string       | STRING   | no         |                 | The value stored as a string. Null unless `propertyType` is set to `string`.                                                            |

<a id="ibmmq-source-troubleshooting"></a>

## Troubleshooting

<a id="ibmmq-source-troubleshooting-backed-out"></a>

### `MQRC_BACKED_OUT` (2003) Errors

**Symptom**
: The connector logs show frequent `MQRC_BACKED_OUT` errors (IBM MQ reason code 2003).

**Explanation**
: This error indicates that a transaction to commit records on the IBM MQ
  side has been rolled back. This typically occurs when the acknowledgment
  call to IBM MQ times out. The connector receives messages from IBM MQ and
  buffers them based on the `max.pending.messages` configuration (default:
  2000). If the time to acknowledge these messages exceeds IBM MQ’s
  transaction timeout, IBM MQ will roll back the transaction, resulting in
  `MQRC_BACKED_OUT` errors and message redelivery.

**Resolution**

1. **Reduce max.pending.messages**: Lower the `max.pending.messages` configuration value to reduce the number of messages buffered before acknowledgment. This decreases the time between message retrieval and acknowledgment.

   Example: Reduce from the default 2000 to 500:
   ```json
   {
     "max.pending.messages": "500"
   }
   ```

   To update the configuration in Confluent Platform:
   - Navigate to your connector in the Confluent Control Center
   - Click **Settings**
   - Locate the **Max pending messages** field
   - Update the value to 500 (or another appropriate value)
   - Click **Next** and then **Launch** to apply the changes
2. **Monitor performance**: After reducing `max.pending.messages`, monitor the connector’s throughput and if performance is impacted, gradually increase the value while watching for `MQRC_BACKED_OUT` errors in the connector logs.
3. **Check IBM MQ transaction logs**: Consult your IBM MQ administrator to review queue manager transaction logs and verify if there are transaction timeout settings that may need adjustment.

For more information, see [IBM MQ Reason Code 2003 Documentation](https://www.ibm.com/docs/en/ibm-mq/9.4.x?topic=codes-2003-07d3-rc2003-mqrc-backed-out)