Skip to content

Commit a443099

Browse files
Joel Hansonvigneshibmpub
authored and
GitHub Enterprise
committed
feat: Update readme with appropriate mqmd info (#37)
* feat: Update readme with appropriate mqmd info Contributes to: event-integration/eventstreams-planning#12434 Signed-off-by: Joel Hanson <joel.hanson2@ibm.com> * Apply suggestions from code review Contributes to: event-integration/eventstreams-planning#12434 Signed-off-by: Joel Hanson <joel.hanson2@ibm.com> Co-authored-by: Vignesh Kumar Elumalai <vigneshkumar.elumalai@ibm.com> * feat: rearrange order of docs in readme Contributes to: event-integration/eventstreams-planning#12434 Signed-off-by: Joel Hanson <joel.hanson2@ibm.com> * feat: copyright year change and readme case fix Contributes to: event-integration/eventstreams-planning#12434 Signed-off-by: Joel Hanson <joel.hanson2@ibm.com> * change to note * remove specifically * Apply suggestions from code review --------- Signed-off-by: Joel Hanson <joel.hanson2@ibm.com> Co-authored-by: Vignesh Kumar Elumalai <vigneshkumar.elumalai@ibm.com>
1 parent b5282cf commit a443099

File tree

3 files changed

+78
-38
lines changed

3 files changed

+78
-38
lines changed

‎README.md

Lines changed: 74 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -307,38 +307,40 @@ For troubleshooting, or to better understand the handshake performed by the IBM
307307

308308
The configuration options for the Kafka Connect sink connector for IBM MQ are as follows:
309309

310-
| Name | Description | Type | Default | Valid values |
311-
| --------------------------------------- | ------------------------------------------------------------------------------------- | ------- | -------------- | --------------------------------- |
312-
| topics or topics.regex | List of Kafka source topics | string | | topic1[,topic2,...] |
313-
| mq.queue.manager | The name of the MQ queue manager | string | | MQ queue manager name |
314-
| mq.connection.mode | The connection mode - bindings or client | string | client | client, bindings |
315-
| mq.connection.name.list | List of connection names for queue manager | string | | host(port)[,host(port),...] |
316-
| mq.channel.name | The name of the server-connection channel | string | | MQ channel name |
317-
| mq.queue | The name of the target MQ queue | string | | MQ queue name |
318-
| mq.exactly.once.state.queue | The name of the MQ queue used to store state when running with exactly-once semantics | string | | MQ state queue name |
319-
| mq.user.name | The user name for authenticating with the queue manager | string | | User name |
320-
| mq.password | The password for authenticating with the queue manager | string | | Password |
321-
| mq.user.authentication.mqcsp | Whether to use MQ connection security parameters (MQCSP) | boolean | true | |
322-
| mq.ccdt.url | The URL for the CCDT file containing MQ connection details | string | | URL for obtaining a CCDT file |
323-
| mq.message.builder | The class used to build the MQ message | string | | Class implementing MessageBuilder |
324-
| mq.message.body.jms | Whether to generate the message body as a JMS message type | boolean | false | |
325-
| mq.time.to.live | Time-to-live in milliseconds for messages sent to MQ | long | 0 (unlimited) | [0,...] |
326-
| mq.persistent | Send persistent or non-persistent messages to MQ | boolean | true | |
327-
| mq.ssl.cipher.suite | The name of the cipher suite for TLS (SSL) connection | string | | Blank or valid cipher suite |
328-
| mq.ssl.peer.name | The distinguished name pattern of the TLS (SSL) peer | string | | Blank or DN pattern |
329-
| mq.ssl.keystore.location | The path to the JKS keystore to use for SSL (TLS) connections | string | JVM keystore | Local path to a JKS file |
330-
| mq.ssl.keystore.password | The password of the JKS keystore to use for SSL (TLS) connections | string | | |
331-
| mq.ssl.truststore.location | The path to the JKS truststore to use for SSL (TLS) connections | string | JVM truststore | Local path to a JKS file |
332-
| mq.ssl.truststore.password | The password of the JKS truststore to use for SSL (TLS) connections | string | | |
333-
| mq.ssl.use.ibm.cipher.mappings | Whether to set system property to control use of IBM cipher mappings | boolean | | |
334-
| mq.message.builder.key.header | The JMS message header to set from the Kafka record key | string | | JMSCorrelationID |
335-
| mq.kafka.headers.copy.to.jms.properties | Whether to copy Kafka headers to JMS message properties | boolean | false | |
336-
| mq.message.builder.value.converter | The class and prefix for message builder's value converter | string | | Class implementing Converter |
337-
| mq.message.builder.topic.property | The JMS message property to set from the Kafka topic | string | | Blank or valid JMS property name |
338-
| mq.message.builder.partition.property | The JMS message property to set from the Kafka partition | string | | Blank or valid JMS property name |
339-
| mq.message.builder.offset.property | The JMS message property to set from the Kafka offset | string | | Blank or valid JMS property name |
340-
| mq.reply.queue | The name of the reply-to queue | string | | MQ queue name or queue URI |
341-
| mq.retry.backoff.ms | Wait time, in milliseconds, before retrying after retriable exceptions | long | 60000 | [0,...] |
310+
| Name | Description | Type | Default | Valid values |
311+
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------- | -------------- | --------------------------------- |
312+
| topics or topics.regex | List of Kafka source topics | string | | topic1[,topic2,...] |
313+
| mq.queue.manager | The name of the MQ queue manager | string | | MQ queue manager name |
314+
| mq.connection.mode | The connection mode - bindings or client | string | client | client, bindings |
315+
| mq.connection.name.list | List of connection names for queue manager | string | | host(port)[,host(port),...] |
316+
| mq.channel.name | The name of the server-connection channel | string | | MQ channel name |
317+
| mq.queue | The name of the target MQ queue | string | | MQ queue name |
318+
| mq.exactly.once.state.queue | The name of the MQ queue used to store state when running with exactly-once semantics | string | | MQ state queue name |
319+
| mq.user.name | The user name for authenticating with the queue manager | string | | User name |
320+
| mq.password | The password for authenticating with the queue manager | string | | Password |
321+
| mq.user.authentication.mqcsp | Whether to use MQ connection security parameters (MQCSP) | boolean | true | |
322+
| mq.ccdt.url | The URL for the CCDT file containing MQ connection details | string | | URL for obtaining a CCDT file |
323+
| mq.message.builder | The class used to build the MQ message | string | | Class implementing MessageBuilder |
324+
| mq.message.body.jms | Whether to generate the message body as a JMS message type | boolean | false | |
325+
| mq.time.to.live | Time-to-live in milliseconds for messages sent to MQ | long | 0 (unlimited) | [0,...] |
326+
| mq.persistent | Send persistent or non-persistent messages to MQ | boolean | true | |
327+
| mq.ssl.cipher.suite | The name of the cipher suite for TLS (SSL) connection | string | | Blank or valid cipher suite |
328+
| mq.ssl.peer.name | The distinguished name pattern of the TLS (SSL) peer | string | | Blank or DN pattern |
329+
| mq.ssl.keystore.location | The path to the JKS keystore to use for SSL (TLS) connections | string | JVM keystore | Local path to a JKS file |
330+
| mq.ssl.keystore.password | The password of the JKS keystore to use for SSL (TLS) connections | string | | |
331+
| mq.ssl.truststore.location | The path to the JKS truststore to use for SSL (TLS) connections | string | JVM truststore | Local path to a JKS file |
332+
| mq.ssl.truststore.password | The password of the JKS truststore to use for SSL (TLS) connections | string | | |
333+
| mq.ssl.use.ibm.cipher.mappings | Whether to set system property to control use of IBM cipher mappings | boolean | | |
334+
| mq.message.builder.key.header | The JMS message header to set from the Kafka record key | string | | JMSCorrelationID |
335+
| mq.kafka.headers.copy.to.jms.properties | Whether to copy Kafka headers to JMS message properties | boolean | false | |
336+
| mq.message.builder.value.converter | The class and prefix for message builder's value converter | string | | Class implementing Converter |
337+
| mq.message.builder.topic.property | The JMS message property to set from the Kafka topic | string | | Blank or valid JMS property name |
338+
| mq.message.builder.partition.property | The JMS message property to set from the Kafka partition | string | | Blank or valid JMS property name |
339+
| mq.message.builder.offset.property | The JMS message property to set from the Kafka offset | string | | Blank or valid JMS property name |
340+
| mq.reply.queue | The name of the reply-to queue | string | | MQ queue name or queue URI |
341+
| mq.retry.backoff.ms | Wait time, in milliseconds, before retrying after retriable exceptions | long | 60000 | [0,...] |
342+
| mq.message.mqmd.write | Whether to enable a custom message builder to write MQ message descriptors | boolean | false | |
343+
| mq.message.mqmd.context | Message context to set on the destination queue. This is required when setting some message descriptors. | string | | `IDENTITY`, `ALL` |
342344

343345
### Using a CCDT file
344346

@@ -427,6 +429,44 @@ You may receive an `org.apache.kafka.common.errors.SslAuthenticationException: S
427429

428430
When configuring TLS connection to MQ, you may find that the queue manager rejects the cipher suite, in spite of the name looking correct. There are two different naming conventions for cipher suites (<https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.1.0/com.ibm.mq.dev.doc/q113220_.htm>). Setting the configuration option `mq.ssl.use.ibm.cipher.mappings=false` often resolves cipher suite problems.
429431

432+
### `MQRC_NOT_AUTHORIZED` exception
433+
434+
When attempting to send a message to an IBM MQ queue, an MQException with code `MQRC_NOT_AUTHORIZED` (reason code `2035`) and completion code 2 is thrown. This indicates insufficient permissions on the queue and the queue manager.
435+
436+
#### Resolving the problem
437+
438+
1. **Review permissions**: Ensure that the user has necessary permissions for accessing the queue and the queue manager.
439+
2. **Grant authority**: If the user does not have the necessary permissions, assign required authorities to the user.
440+
3. **Set Context**: Set `WMQ_MQMD_MESSAGE_CONTEXT` property for required properties.
441+
442+
Configure the `mq.message.mqmd.context` property according to the message context. Options include:
443+
- `ALL`, which corresponds to `WMQ_MDCTX_SET_ALL_CONTEXT`
444+
- `IDENTITY`, mapped to `WMQ_MDCTX_SET_IDENTITY_CONTEXT`
445+
446+
**Important:** If your message contains any of the following properties, you must ensure that `WMQ_MQMD_MESSAGE_CONTEXT` is set to either `WMQ_MDCTX_SET_IDENTITY_CONTEXT` or `WMQ_MDCTX_SET_ALL_CONTEXT`:
447+
- JMS_IBM_MQMD_UserIdentifier
448+
- JMS_IBM_MQMD_AccountingToken
449+
- JMS_IBM_MQMD_ApplIdentityData
450+
451+
Similarly, if your message includes any of the following properties, set the `WMQ_MQMD_MESSAGE_CONTEXT` field to `WMQ_MDCTX_SET_ALL_CONTEXT`:
452+
- JMS_IBM_MQMD_PutApplType
453+
- JMS_IBM_MQMD_PutApplName
454+
- JMS_IBM_MQMD_PutDate
455+
- JMS_IBM_MQMD_PutTime
456+
- JMS_IBM_MQMD_ApplOriginData
457+
458+
Other message properties do not require the `mq.message.mqmd.context` property.
459+
460+
#### Additional tips
461+
462+
- Verify that the length of all properties are correctly set within the allowed limit.
463+
- Do not set the [`JMS_IBM_MQMD_BackoutCount`](https://www.ibm.com/docs/en/ibm-mq/9.3?topic=descriptor-backoutcount-mqlong-mqmd) property.
464+
- Refer to the IBM MQ documentation for detailed configuration guidance:
465+
466+
- [IBM MQ JMS Message Object Properties](https://www.ibm.com/docs/en/ibm-mq/9.3?topic=application-jms-message-object-properties): This documentation provides details about various properties that can be set on IBM MQ JMS message objects, including their names, types, and descriptions.
467+
- [IBM MQ Developer Community](https://community.ibm.com/community/user/integration/home): The developer community for IBM MQ, where you can find forums, articles, and resources related to development and troubleshooting for IBM MQ.
468+
- [IBM MQ troubleshooting guide](https://www.ibm.com/docs/en/ibm-mq/9.3?topic=mq-troubleshooting-support): IBM guide for troubleshooting common issues and errors in IBM MQ.
469+
430470
## Support
431471

432472
A commercially supported version of this connector is available for customers with a support entitlement for [IBM Event Streams](https://www.ibm.com/cloud/event-streams) or [IBM Cloud Pak for Integration](https://www.ibm.com/cloud/cloud-pak-for-integration).
@@ -437,6 +477,6 @@ For issues relating specifically to this connector, please use the [GitHub issue
437477

438478
## License
439479

440-
Copyright 2017, 2020, 2023 IBM Corporation
480+
Copyright 2017, 2020, 2023, 2024 IBM Corporation
441481

442-
The IBM MQ sink connector v2 is available under the IBM Event Automation license and IBM Cloud Pak for Integration license. Please see https://ibm.biz/ea-license for further information.
482+
The IBM MQ sink connector v2 is available under the IBM Event Automation license and IBM Cloud Pak for Integration license. For more information, see the [Event Automation documentation](https://ibm.biz/ea-license).

‎src/main/java/com/ibm/eventstreams/connect/mqsink/JMSWorker.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* Copyright 2017, 2020, 2023 IBM Corporation
2+
* Copyright 2017, 2020, 2023, 2024 IBM Corporation
33
* <p>
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.

‎src/main/java/com/ibm/eventstreams/connect/mqsink/MQSinkConfig.java

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* Copyright 2023 IBM Corporation
2+
* Copyright 2023, 2024 IBM Corporation
33
* <p>
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -159,12 +159,12 @@ public class MQSinkConfig {
159159

160160
// https://www.ibm.com/docs/en/ibm-mq/9.3?topic=amffmcja-reading-writing-message-descriptor-from-mq-classes-jms-application
161161
public static final String CONFIG_NAME_MQ_MQMD_WRITE_ENABLED = "mq.message.mqmd.write";
162-
public static final String CONFIG_DISPLAY_MQ_MQMD_WRITE_ENABLED = "Enable MQMD Message Writing";
162+
public static final String CONFIG_DISPLAY_MQ_MQMD_WRITE_ENABLED = "Enable a custom message builder to write MQ message descriptors";
163163
public static final String CONFIG_DOCUMENTATION_MQ_MQMD_WRITE_ENABLED = "This configuration option determines whether the MQMD structure will be written along with the message data. Enabling this option allows control information to accompany the application data during message transmission between sending and receiving applications. Disabling this option will exclude the MQMD structure from the message payload.";
164164

165165
// https://www.ibm.com/docs/en/ibm-mq/9.3?topic=application-jms-message-object-properties
166166
public static final String CONFIG_NAME_MQ_MQMD_MESSAGE_CONTEXT = "mq.message.mqmd.context";
167-
public static final String CONFIG_DISPLAY_MQ_MQMD_MESSAGE_CONTEXT = "MQMD Message Context";
167+
public static final String CONFIG_DISPLAY_MQ_MQMD_MESSAGE_CONTEXT = "Message context to set on the destination queue. This is required when setting some message descriptors.";
168168
public static final String CONFIG_DOCUMENTATION_MQ_MQMD_MESSAGE_CONTEXT = "This configuration option specifies the context in which MQMD properties are applied. Certain properties require this context to be set appropriately for them to take effect. Valid options for WMQ_MQMD_MESSAGE_CONTEXT are IDENTITY for WMQ_MDCTX_SET_IDENTITY_CONTEXT or ALL for WMQ_MDCTX_SET_ALL_CONTEXT.";
169169

170170
private static final Validator ANY_VALUE_VALID = null;

0 commit comments

Comments
 (0)