IBM MQ Source Connector

Type

source

Class

com.ibm.eventstreams.connect.mqsource.MQSourceConnector

Target System

IBM MQ

Maintainer

IBM

License

Apache License 2.0

Project

github.com/ibm-messaging/kafka-connect-mq-source

Download

GitHub Releases

This page documents version 2.8.0. Newer versions should be compatible unless there are breaking changes, but field names or default values may differ. If you notice discrepancies, please contact Axual Support.

Description

The IBM MQ Source Connector reads messages from an IBM MQ queue and publishes them as records to a Kafka topic.

It is maintained by IBM as part of the open-source github.com/ibm-messaging/kafka-connect-mq-source.

Although IBM MQ implements the JMS API, the dedicated IBM MQ connector is preferred over the generic JMS Source Connector — it supports native CCDT-based connection configuration, TLS client certificate authentication, and a JSON record builder optimised for IBM MQ payloads.

The IBM MQ Sink Connector is a separate connector available at github.com/ibm-messaging/kafka-connect-mq-sink. Contact Axual for support with setting up either direction.

Features

  • Read messages from IBM MQ queues and publish to Kafka topics

  • TLS/SSL connectivity using keystore and truststore

  • JSON record builder support

  • Configurable error tolerance and logging

When to Use

  • You need to bridge IBM MQ messages into Kafka for downstream processing or modernisation.

  • You are migrating from an IBM MQ-based messaging architecture to Kafka.

  • Your existing integration uses IBM MQ queue managers and you want to tap into that data stream without modifying producers.

When NOT to Use

  • You need to write Kafka records into IBM MQ — contact Axual for IBM MQ Sink Connector support.

  • Your broker is not IBM MQ — use the JMS Source Connector instead.

Installation

The connector is available from the github.com/ibm-messaging/kafka-connect-mq-source.

  1. Navigate to the releases page and select the version matching your Kafka Connect installation.

  2. Download the JAR file.

For installation steps, see Installing Connector Plugins.

Configuration

For the complete configuration reference, see the official source connector documentation.

To configure a connector in Axual Self-Service, see Starting Connectors. TIP: For Infrastructure-as-Code deployment, see the Axual Kafka Connect Boilerplates for Terraform and Management API boilerplates.

Getting Started

Prerequisites

IBM MQ instance

  1. Create an MQ instance

    1. Location: Frankfurt (eu-de)

    2. Pricing plan: Lite

    3. Service name: my_axual_mq

    4. Accept the License Agreement and click Create.

  2. Create a queue manager:

    1. Click Create + on the "Queue managers" tab.

    2. Queue manager name: my_axual_queue_manager

    3. Display name: my_axual_queue_manager

    4. Size: Lite

    5. Click Create → Continue.

  3. After the queue manager is created, click it → Connect information → JSON CCDT.
    The CCDT file will be downloaded to your machine. Click Close.

  4. Click the Key store tab → Click the 3 dots on the qmgrcert certificate → Download public certificate.

  5. Create application credentials:

    1. Go to Resources list → Expand "Integration" → Click my_axual_mq.

    2. Click the Application credentials tab → Add +.

    3. Display name: my_mq_connector

    4. Application username: axualconnect

    5. Click Add and generate API key → Download.

The CCDT JSON file, API key, and certificates must be made available on every Connect node by Axual platform operators before you can start the connector.

Axual stream

The stream where the connector will produce events must already exist in Axual Self-Service. See Creating streams if you need to create it.

Steps

Step 1 — Create a connector application

  1. Follow the Creating streams documentation in order to create one stream and deploy it onto an environment.
    The name of the stream will be my_mq_stream.
    The key/value types will be JSON/JSON.

  2. Follow the Configure and install a connector documentation to set up a new Connector-Application.
    Let’s call it my_mq_app.
    The plugin name is com.ibm.eventstreams.connect.mqsource.MQSourceConnector.
    If a plugin isn’t available, ask a platform operator to install plugins.

Step 2 — Configure the connector

  1. Provide the following minimal configuration:

    mq.ccdt.url

    Example value:
    file://etc/ibm_mq_ccdt/my_mq_app/ibm-mq-ccdt.json

    mq.password

    Find this value in the applicationApiKey.json file you downloaded.
    Example value: ABcdefgHIJkLMNOpqRStuvwXYZ1234567890over_flow

    mq.ssl.keystore.location

    Example value:
    /etc/tls/my_mq_app/ibm_mq/keystore.jks

    mq.ssl.keystore.password

    Example value: password

    mq.ssl.truststore.location

    /etc/tls/my_mq_app/ibm_mq/truststore.jks

    mq.ssl.truststore.password

    Example value: password

    mq.queue.manager

    my_axual_queue_manager

    mq.user.name

    axualconnect

    mq.queue

    my_mq_stream

    topic

    my_mq_stream

    mq.record.builder

    com.ibm.eventstreams.connect.mqsource.builders.JsonRecordBuilder

    The following optional configs are also recommended:

    errors.log.enable

    true

    errors.log.include.messages

    true

    errors.tolerance

    all

    For advanced options, see the official source connector documentation.

  2. Authorize the my_mq_app source Connector-Application to produce to the my_mq_stream stream.

Step 3 — Start the connector

Start the connector application from Axual Self-Service.

Step 4 — Verify

In Axual Self-Service, use stream-browse on my_mq_stream to confirm MQ messages are arriving as Kafka records.

Cleanup

When you are done:

  1. Stop the connector application in Axual Self-Service.

  2. Remove stream access for the application if no longer needed.

  3. If deployed via IBM Cloud, delete the queue manager:

    1. Go to Resources list → Expand "Integration" → Click my_axual_mq.

    2. Click the delete button on the right side of the screen and confirm deletion.

Known limitations

  • The CCDT file, TLS keystores, and truststores must be distributed to all Connect nodes by Axual platform operators before the connector can start.

  • Contact Axual for support with the IBM MQ Sink Connector.

Examples

Minimal configuration

{
  "name": "my-ibm-mq-source",
  "config": {
    "connector.class": "com.ibm.eventstreams.connect.mqsource.MQSourceConnector",
    "mq.ccdt.url": "file://etc/ibm_mq_ccdt/my_mq_connector/ibm-mq-ccdt.json",
    "mq.password": "<your-api-key>",
    "mq.ssl.keystore.location": "/etc/tls/my_mq_connector/ibm_mq/keystore.jks",
    "mq.ssl.keystore.password": "<your-keystore-password>",
    "mq.ssl.truststore.location": "/etc/tls/my_mq_connector/ibm_mq/truststore.jks",
    "mq.ssl.truststore.password": "<your-truststore-password>",
    "mq.queue.manager": "my_axual_queue_manager",
    "mq.user.name": "axualconnect",
    "mq.queue": "my_mq_stream",
    "topic": "my_mq_stream",
    "mq.record.builder": "com.ibm.eventstreams.connect.mqsource.builders.JsonRecordBuilder"
  }
}

License

IBM MQ source connector is licensed under the Apache License, Version 2.0.