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

# IBM MQ Sink Connector for Confluent Platform

The Kafka Connect IBM MQ Sink connector is used to move messages from Kafka to
an [IBM MQ](https://www.ibm.com/products/mq) cluster.

#### IMPORTANT
- If you are required to use JNDI to connect to IBM MQ, there is a general
  [JMS Sink connector for Confluent Platform](https://docs.confluent.io/kafka-connect-jms-sink/current/overview.html)
  available that uses a JNDI-based mechanism to connect to the JMS broker.
- With the IBM MQ Sink connector, you can set the following record headers to
  be passed as a JMS message property:
  - `JMSCorrelationId`. The header is ignored if `forward_kafka_key` is
    set as `true`.
  - `JMSReplyTo`. The supported syntax is:
    - Queue: `queue://queueName` or `queue://queueManager/queueName`
    - Topic: `topic://topicName`
  - `JMSType`
- <!-- 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 Sink connector includes the following features:

- [At least once delivery](#ibmmq-sink-at-least-once-delivery)
- [Exactly once semantics](#ibmmq-sink-exactly-once-semantics)
- [Dead Letter Queue](#ibmmq-sink-dead-letter-queue)
- [Multiple tasks](#ibmmq-sink-multiple-tasks)
- [High Availability and Disaster Recovery (HA/DR) Support](#ibmmq-sink-ha-dr-support)
- [Custom Credentials Provider Support](#ibmmq-source-credentials-provider-support)
- [Client-side encryption](#ibmmq-sink-csfle-sm)

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

### At least once delivery

This connector guarantees that records are delivered at least once from the Kafka
topic.

<a id="ibmmq-sink-exactly-once-semantics"></a>

### Exactly once semantics

The connector supports exactly once delivery of messages to IBM MQ by using a dedicated IBM MQ queue to store offsets.
This allows the connector to track progress and resume from the last processed record following a failure or restart.
To enable exactly once semantics, you must manually create a unique queue for each connector to serve as its offset store.
To ensure a single active consumer, the queue must be configured in exclusive mode by setting
the `DEFSOPT` (Default open option) attribute to `EXCLUSIVE`. For more information,
see the [Exactly once connector configuration](connector_config.md#eos-ibmmq-sink-configs).

Consider the following limitations while using exactly once semantics:

- The connector does not auto create the offsets queue. You must create it in IBM MQ before starting the connector.
- Sharing offset queues across multiple connectors is not supported. Each connector requires its own dedicated offsets queue.
- Exactly once semantics is only supported when the connector is configured with a single task.
  It does not support multiple tasks.
- The connector uses the IBM MQ offsets queue as the source of truth and ignores any offsets reset made using the Kafka `reset-offsets` API.

<a id="ibmmq-sink-dead-letter-queue"></a>

### Dead Letter Queue

This connector supports the Dead Letter Queue (DLQ) functionality. For
information about accessing and using the DLQ, see [Confluent Platform
Dead Letter Queue](/platform/current/connect/concepts.html#dead-letter-queue).

<a id="ibmmq-sink-multiple-tasks"></a>

### Multiple tasks

The IBM MQ Sink 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.

<a id="ibmmq-sink-ha-dr-support"></a>

### High Availability and Disaster Recovery (HA/DR) Support

The IBM MQ Sink connector supports High Availability (HA) and Disaster Recovery (DR) configurations through the `mq.connection.list` property. This feature allows you to specify multiple IBM MQ broker endpoints in a comma-separated list format (for example, `host1:port1,host2:port2,host3:port3`). When multiple endpoints are configured, the connector will automatically attempt to connect to each queue manager in sequence until a successful connection is established.

This capability enables:

- **Automatic failover**: If the primary queue manager becomes unavailable, the connector automatically attempts to connect to the next available queue manager in the list.
- **Disaster recovery**: Supports geographically distributed queue managers to ensure business continuity.
- **High availability**: Provides seamless connection to standby queue managers in HA configurations.

To use this feature, configure the `mq.connection.list` property instead of `mq.hostname` and `mq.port`. These configuration options are mutually exclusive—you must use either `mq.connection.list` or the combination of `mq.hostname` and `mq.port`, but not both.

For configuration details, see [Configuration Reference for IBM MQ Sink Connector for Confluent Platform](connector_config.md#ibmmq-sink-connector-config).

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

### Custom Credentials Provider Support

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.jms.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-sink` directory on all Connect workers. This step ensures that the IBM MQ connector can access and use your custom credentials provider.

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

**IbmMqCredentialsProvider Interface**

```java
package io.confluent.connect.jms.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.jms.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-sink-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).

## 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 Platform license](connector_config.md#ibmmq-sink-connector-license-config) for license properties and
[Confluent license properties](https://docs.confluent.io/current/connect/kafka-connect-ibmmq/sink/connector_config.html#confluent-license-properties)
for 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).

## Configuration Properties

For a complete list of configuration properties for this connector, see
[Configuration Reference for IBM MQ Sink Connector for Confluent Platform](connector_config.md#ibmmq-sink-connector-config).

## Install the IBM MQ Sink 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 Kafka Connect IBM MQ Sink
connector:

- Kafka Broker: Confluent Platform 3.3.0 or later, or Kafka 0.11.0 or later
- Kafka Connect: Confluent Platform 4.1.0 or later, or Kafka 1.1.0 or later (requires header support in Connect)
- [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
- Java 1.8
- An installation of the IBM MQ client library JAR files. For help with
  downloading the JAR files, see the [IBM MQ Client Library](#ibmmq-sink-connector-client-libs)
  section.
- You must install the connector on every machine where Connect will run.
- If you want to install the connector using Confluent Hub, 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.

### 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-sink: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-sink:2.2.0
```

### Install the connector manually

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

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

## IBM MQ Client Library

The Kafka Connect IBM MQ connector does not come with the IBM MQ client
library.

If you are running a multi-node Connect cluster, the IBM MQ connector and IBM
MQ client JAR must be installed on **every** Connect worker in the cluster.
See below for details.

### Install IBM MQ Client Library

This connector relies on a provided `com.ibm.mq.allclient` client JAR
distributed by IBM. The connector **will not run** if you have not installed the
JAR on each Connect worker node.

The installation steps are:

1. Follow IBM’s guide on [Obtaining the IBM MQ classes for JMS separately](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.0.0/com.ibm.mq.dev.doc/q128170_.htm)
   to download the IBM MQ client JAR. #. The installation should have created a
   `wmq/JavaSE` directory. From this directory, copy **only** the
   `com.ibm.mq.allclient.jar` file into the
   `share/java/kafka-connect-ibmmq-sink` directory of your Confluent Platform installation **on
   each worker node**.
2. Restart all of the Connect worker nodes.

#### NOTE
The `share/java/kafka-connect-ibmmq-sink` directory mentioned above is for
Confluent Platform. If you are using a different installation, find the location of the
Confluent IBM MQ sink connector JAR files and place the IBM MQ client JAR
file into the same directory.

## JMS Message Formats

The format of outgoing JMS Message values is configured with the
`jms.message.format` property, using one of the following options:

### string (*default*)

When using the `string` Message Format, record values are run through
`Values.convertToString(...)` from the Connect Data package and produced as a
JMS `TextMessage`.

Primitive values are converted to their String equivalent and structured objects
are transformed to a sensible string representation that is similar to the JSON
representation, with the exception of simple string values (not in objects or
arrays) which are unquoted.

### avro

Record values are serialized without the Avro schema information and produced as
a JMS `BytesMessage`. JMS consumers **must have the schema** to deserialize
the data.

#### IMPORTANT
The connector attempts to infer the Avro schema for records that have no
schema. If the connector cannot infer the schema, the task is killed. If you
are processing data without a schema, consider using one of the other
`jms.message.format` configurations.

### json

Record values are converted to a UTF-8 encoded JSON representation and produced
as a JMS `TextMessage`.

### bytes

Record values are passed along in bytes form without any conversion.

#### IMPORTANT
Record values must be converted to bytes form before the connector processes
them. Configure the `value.converter` property to
`org.apache.kafka.connect.converters.ByteArrayConverter` to ensure that
record values arrive in byte format.

## Forwarding Kafka Properties to JMS

The connector can be configured to forward various values from the Kafka record
to the JMS Message.

* Enable `jms.forward.kafka.key` to convert the record’s key to a String and
  forward it as the `JMSCorrelationID`.
* Enable `jms.forward.kafka.metadata` to forward the record’s topic,
  partition, and offset on JMS Message properties.
  * Kafka topic is applied to the message as a String property named `KAFKA_TOPIC`.
  * Partition is applied to the message as an Int property named `KAFKA_PARTITION`.
  * Offset is applied to the message as a Long property named `KAFKA_OFFSET`.
* Enable `jms.forward.kafka.headers` to add each header from the SinkRecord to
  the JMS Message as a String property.

#### NOTE
The connector converts the record key and headers to a sensible string
representation that is similar to the JSON representation, with the
exception of simple string values (not in objects or arrays) which are
unquoted. No other conversion is done to the key and headers before
forwarding them on the JMS Message. If another format is needed,
out-of-the-box or custom [Single Message
Transformation](/platform/current/connect/transforms/index.html) can be used with the connector
to transform the record keys and/or headers to the desired string
representation before the JMS sink connector processes each record.

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).

## Quick Start

This quick start uses the IBM MQ Sink connector to consume records from Kafka and
send them to an IBM MQ broker running in a Docker container.

1. Start the IBM MQ broker.
   ```bash
   docker run -d \
     -p 1414:1414 -p 9443:9443 \
     -e LICENSE=accept \
     ibmcom/mq:9.1.2.0
   ```
2. Install the connector through the [Confluent Hub Client](https://docs.confluent.io/current/connect/managing/confluent-hub/client.html).
   ```bash
   # run from your Confluent Platform installation directory
   confluent connect plugin install confluentinc/kafka-connect-ibmmq-sink:latest
   ```
3. Start Confluent Platform.
   ```bash
   confluent local start
   ```
4. [Produce](https://docs.confluent.io/current/cli/command-reference/confluent-produce.html)
   test data to the `sink-messages` topic in Kafka.
   ```bash
   seq 10 | confluent local produce sink-messages
   ```
5. Create a `ibmmq-sink.json` file with the following contents:
   ```json
   {
     "name": "IbmMqSinkConnector",
     "config": {
       "connector.class": "io.confluent.connect.jms.IbmMqSinkConnector",
       "tasks.max": "1",
       "topics": "sink-messages",
       "mq.username": "app",
       "mq.channel": "DEV.APP.SVRCONN",
       "mq.hostname": "localhost",
       "mq.port": "1414",
       "mq.password": "",
       "mq.queue.manager": "mq",
       "mq.transport.type": "client",
       "jms.destination.type": "queue",
       "jms.destination.name": "DEV.QUEUE.1",
       "value.converter": "org.apache.kafka.connect.storage.StringConverter",
       "key.converter": "org.apache.kafka.connect.storage.StringConverter",
       "confluent.topic.replication.factor": "1",
       "confluent.topic.bootstrap.servers": "localhost:9091"
     }
   }
   ```
6. Load the IBM MQ Sink connector.
   ```bash
   confluent local load mq --config ibmmq-sink.json
   ```

   #### IMPORTANT
   Don’t use the [Confluent CLI](https://docs.confluent.io/confluent-cli/current/index.html) in production
   environments.
7. Confirm that the connector is in a `RUNNING` state.
   ```bash
   confluent local status mq
   ```
8. Navigate to the [IBM MQ Console](https://localhost:9443/ibmmq/console) to
   confirm the messages were delivered to the `DEV.QUEUE.1` queue.