IBM MQ Publish

The IBM MQ Publish activity publishes a message to a dynamic or predefined topic.

The activity is capable of sending any of the four message types described in the IBM MQ Put activity. The capabilities of the activity are determined by the configuration, with some runtime behaviors controlled by the input schema. The type of the message being sent might determine what fields are applicable for the publish operation, for example, request messages are incompatible with report options. Even though this is a pub/sub type of activity, the report and reply-to queues are real queues, not topics.

In IBM MQ, a topic is defined as a string of characters starting with a forward slash (/) and can contain many topic nodes to the right. IBM MQ supports a mechanism for separating administratively defined topic strings from application-defined ones. This is exposed on the publish activity by the Destination field and the Topic Dynamic field. The intent is that administratively defined portions of the topic string are represented by selecting a permanently defined topic for the first part of the topic string and concatenating the dynamic portion to the right. This way an application can be deployed in several environments without naming conflicts.

There is no difference between the message object published by this activity from the one sent by the Put activity.

General

The General tab of the Publish activity contains the following fields:

Field Module Property? Description
Name N The name to be displayed as the label for the activity in the process.
Connection Y The connection resource which associates this activity with the queue manager that has access to the desired topic.

Click to select a usable connection for the activity.

Destination Y The name of the administratively defined topic to which the message is published. This field is optional if the topic string is to be entirely specified in the Topic Dynamic field or the input schema.
Topic Dynamic Y The contents of this field are concatenated to the topic name referenced by the administratively defined topic. If no administratively defined topic is provided this string forms the entire topic string.
Message Content Type N The following types of message content are supported:
  • Binary: the bytes field in the input schema to map byte array data onto the outgoing message.
  • Text: the text field in the output schema onto which regular string data can be mapped. At run time, this string is converted to bytes using the default Java encoding.
  • Schema: select Schema to write the message body such that it conforms to a schema. The schema to be used is designed as a sharable resource and is provided for mapping on the input schema.
Message Body Fields Y Provide the schema to be used in the Input tab, and at run time to encode the contents of this message.
Message Type N Select the type of the message that is to be sent:
  • Datagram
  • Request
  • Reply
  • Report

If a Request message is selected, the Reply To Destination field is enabled and the report options are disabled. The report options are available when using any other message type.

Reply To Destination Y This Reply To Destination field is enabled only when the Request message type is selected from the Message Type list. This field contains the queue name which is placed into the replyToQueueName field in the Input tab. Click Choose a field value type next to the Reply To Destination field to select the queue.
Retain Message N Select the Retain Message checkbox to indicate that the message is to be retained in the queue manager even if no subscribers exist. The future subscribers can receive the message when they are created. This is useful for conveying application state information.
Fail If Quiescing N Select the Fail If Quiescing checkbox to prevent this activity from holding up a queue manager quiesce operation.
Application Properties N Select a schema that represents the application properties to be placed in this message. To use application properties, create a generic XML schema composed of a node with simple elements inside it and map that schema to this field.
See the IBM MQ documentation for property types supported by the level of client you have installed.
Note: A failure to observe cardinality results in errors processing the input or output schema.
Logger Name Y Enter the name of any pre-configured logger available to the run time. Loggers are configured in an XML document referenced by the Dlogback.configurationFile runtime parameter.

Description

A short description for the Publish activity.

Advanced

The Advanced tab of the Publish activity contains the following fields:

Field Module Property? Description
Message Priority Y Set the priority of the message as it is to be retrieved by the queue manager. The values range from 0 to 9. If not specified, the default is the destination queue's default priority.
Context Support N The input fields of a publish operation fall into categories based on their context. Many fields are always present, but others are only present if the context relevant to that field is chosen. This is because the queue manager must authorize the user to update these fields.
Select one of the following settings:
  • Default: the input schema conforms to the fields accessible to a user with the default authority.
  • Identity: the input schema conforms to the fields accessible to a user with the Set Identity Context authority.
    The new fields are:
    • accountingToken
    • applicationIdData
    • userId
  • All: the input schema conforms to the fields accessible to a user with the Set Identity Context and Set All Context authorities.
    The new fields (also to those provided by Identity) are:
    • applicationOriginData
    • putApplicationType
    • putApplicationName
Confirm On Arrival N Trigger a report message by using the Confirm on Arrival type. The report is not enabled by default.
Report types are:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with the Request type messages. That is, if the message type is Request, a report confirmation is not sent.

Confirm On Delivery N Trigger a report message by using the Confirm on Delivery type. The report is not enabled by default.
Report types are:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with the Request type messages. That is, if the message type is Request, a report confirmation is not sent.

Confirm On Exception N Trigger a report message by using the Confirm on Exception type. The report is not enabled by default.
Report types are:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with the Request type messages. That is, if the message type is Request, a report confirmation is not sent.

Confirm On Expiry N Trigger a report message by using the Confirm on Expiry type. The report is not enabled by default.
Report types are:
  • NONE: the report is not enabled.
  • NO_DATA: the body of the message does not accompany the report.
  • WITH_DATA: the first 100 bytes of the message body accompanies the report.
  • FULL_DATA: the entire body of the message accompanies the report.

Reports are delivered in the reply to queue specified in the Report Reply Queue field. Because this field maps to the message's replyToQueueName field, reports are mutually exclusive with the Request type messages. That is, if the message type is Request, a report confirmation is not sent.

Report Reply Queue Y Enter the name of the queue where you want to send Report messages. The value entered here maps onto the replyToQueueName field.
Asynchronous Put* N Select the checkbox to achieve a modest improvement in the latency of the Put activity if your application can tolerate the potential for an unreported failure writing to the queue. See the IBM MQ documentation for the put message option MQPMO_ASYNC_RESPONSE for more information regarding the risks of this option.

Input

Activity Pooling

The Activity Pooling tab allows the activity to pool all the MQ resources associated with the publish activity at the process level.

The Activity Pooling tab contains the following fields:

Field Global Variable Description
Pool Activity N Select the Pool Activity checkbox to activate pooling for the client objects used by this activity. Selecting this option causes pooling to be done at a higher level than merely pooling the connection. All destinations used by the activity are kept open and the connection resource specified are not pooled in the usual way even if that resource has pooling enabled. This option is used when the server to which you are connected experiences very high latency such that opening, closing, and pooling of connections cause unacceptable performance degradation.

The primary consideration for choosing pooling parameters is the number of available connections to the queue manager. Choose values that do not create unnecessary resource consumption in the queue manager, and leave available connections for other applications (including other pooled connections and activities, remember that the application might be deployed on multiple engine instances).

Pool Max Y Determines the maximum number of connections in the pool. When this limit is reached, subsequent activities fail with the following message:

"Activity Pool is exhausted: [Timeout waiting for idle object] Either enlarge the pool, allow it to grow, or increase the blocking time."

Pool Max Idle Y Determines the maximum number of idle connections in the pool. When the number of unused connections reaches this number, the idle connections are disconnected and closed, freeing resources on the server. Amounts over the Max Connections values are ignored.
Exhausted Action N Select one of the following options:

● FAIL - The activity fails immediately after the pool is exhausted.

● BLOCK - The activity waits for the "Pool Wait" interval before failing. If an MQ client is available before the timeout, the activity acquires it.

● GROW - The pool grows past its maximum parameters.

Pool Wait Y If exhausted action is set to "BLOCK", the pool waits for the "Pool Wait" interval for an activity to become available before failing.

The following table lists the input items for the Publish activity:

Input Item Module Property? Description
InteractionInput N This input schema field is the root node for all the input provided to the activity.
mqproperties N The node containing all the message header fields (plus the destination override) that are relevant to the input.
  • destination: specify a destination here to override the topic name from the configuration panels.
  • destqmgr: destination queue manager name. The name of the queue manager on which this topic is located.
    Note: A transmission queue and a sender channel must be configured for this queue manager for it to work.
  • topicdynamic: the dynamic portion of the topic string. This can be the entire topic string and override any dynamic topic specified on the configuration panel.
  • correlationId: to provide a correlation identifier for this message by mapping a byte array to this field. The XPath expression tib:string-to-base64 ("correlationid") is sufficient to populate this field. This field is only valid if the topic referenced is an administratively defined unmanaged topic. In all other cases, it is ignored by the queue manager.

    Consult the IBM MQ documentation for descriptions of managed and unmanaged subscriptions.

  • messageId: to provide a message identifier for this message by mapping a byte array to this field. The XPath expression tib:string-to-base64 ("messageId") is sufficient to populate this field. This field is only valid if the topic referenced is an administratively defined unmanaged topic. In all other cases, it is ignored by the queue manager.
  • characterSet: to set the IBM Coded Characterset ID of this message.
    Valid values are:
    • 850: The commonly used ASCII codeset.
    • 819: The ISO standard ASCII codeset.
    • 37: The American EBCDIC codeset.
    • 1200: Unicode.
    • 1208: UTF-8.

    The queue manager might apply this codeset when doing conversions to create report messages.

  • alternateUserId: to document the alternate user ID used in this operation, if any.
  • accountingToken: to provide a binary (base 64 encoded) accounting token to be used on host systems to assist in accounting for resources used by the application.
  • applicationIdData: to provide a string that can be used on all endpoints to identify this application.
  • applicationOriginData: to provide information related to the originating application node for this message.
  • putApplicationType: to provide either one of the IBM documented application type enumerators for this application or one of your choosing.

    See the IBM MQ documentation for the meaning of the documented application types.

    The documented enumerations are: 
    MQAT_AIX          MQC.MQAT_AIX          0x06   
MQAT_CICS         MQC.MQAT_CICS         0x01
MQAT_DOS          MQC.MQAT_DOS          0X05      
MQAT_IMS          MQC.MQAT_IMS          0X03
MQAT_MVS          MQC.MQAT_MVS          0X02
MQAT_OS2          MQC.MQAT_OS2          0X04
MQAT_OS400        MQC.MQAT_OS400        0X08   
MQAT_QMGR         MQC.MQAT_QMGR         0X07   
MQAT_UNIX         MQC.MQAT_UNIX         0X06
MQAT_WINDOWS      MQC.MQAT_WINDOWS      0X09   
MQAT_JAVA         MQC.MQAT_JAVA         0X1C  
MQAT_UNKNOWN      MQC.MQAT_UNKNOWN   -1 or 0XFFFFFFFF   
MQAT_NO_CONTEXT   MQC.MQAT_NO_CONTEXT   0X00   
MQAT_CICS_VSE     MQC.MQAT_CICS_VSE     0X0A
MQAT_VMS          MQC.MQAT_VMSQ         0X0C   
MQAT_GUARDIAN     MQC.MQAT_GUARDIAN     0X0D   
MQAT_VOS          MQC.MQAT_VOS          0X0E  
MQAT_DEFAULT      MQC.MQAT_DEFAULT      0X1C   
MQAT_NSK          MQC.MQAT_NSK          0X0D   
MQAT_CICS_BRIDGE  MQC.MQAT_CICS_BRIDGE  0X15   
MQAT_NOTES_AGENT  MQC.MQAT_NOTES_AGENT  0X16   
MQAT_WINDOWS_NT   MQC.MQAT_WINDOWS_NT   0X0B   
MQAT_IMS_BRIDGE   MQC.MQAT_IMS_BRIDGE   0X13   
MQAT_XCF          MQC.MQAT_XCF          0X14
  • putApplicationName: the name of the application that puts the message. Provide information about the originating application in this field.
  • userId: to provide the user ID to be used when authorizing this message as it traverses the messaging system. For operations with report options, this field is mandatory. If a value is not provided here, it is taken from the connection resource if one is available there, and from the environment, if it is not.
  • replyToQueueName: to specify the name of an existing queue that the target application can use as a destination for its response. This enables the common "request response" pattern.
  • replyToQmgrName: destination queue manager name. The name of the queue manager on which this queue is located.
    Note: A transmission queue and a sender channel must be configured for this to work.
  • format: to describe the nature of the data in the message. It defaults to a space character or MQFMT_NONE. A user-defined format can be used to assist the receiving application in decoding the message, for example, in the selection of a Data Conversion parse activity for this message type.
  • expiry: to indicate the length of time (in tenths of a second) that the message is kept in the queue before being deleted. Defaults to -1, which means there is no expiration. This field overrides the configuration value for expiry if it is mapped.

    Permissible values are positive integers or -1.

  • priority: the priority (from 1 to 9) of the message. This field overrides a configuration value for priority if it is mapped.
  • reportOptionPan: this is the Positive Acknowledgment report field and is provided by the sending application. This report field is not acted upon by the queue manager.
  • reportOptionNan: this is the Negative Acknowledgment report field and is provided by the sending application. This report field is not acted upon by the queue manager.
  • report: this is the report options field for the message. If nothing is entered, then the report options as configured in the Advanced tab are used to populate it at run time. However, if a number is mapped here, it is logically OR'ed with the results of processing the report options. It is provided to enable the use of report options not configurable in the Advanced tab.
  • encoding: this is the encoding field for the message and it specifies the representation used for numeric values in the application message data. This applies to binary, packed decimal, and floating-point data. This encoding is used when the processing of fields is mapped by a message body schema.

    For specific values, see the MQMessage encoding field in the IBM MQ documentation.

dynamicProperties N
  • dynamic property: these properties are the same as those mapped through the appProperties node with the exception that no special schema is required to map them. A dynamicProperties node is created for each property in the message which was not mapped by the appProperties schema mechanism. If no appProperties schema is in place, all properties are dynamic. Note that the publish and subscribe mechanisms in IBM MQ use message properties in the implementation, you can see the property mqps.Top and possibly others on all publications.
  • name: the name of the property.
  • value: the string type value of the property.
  • type: the type for the property. The valid types are "string", "boolean", "short", "integer", "long", "float", "double", and "byte".
bytes N Map the main content of the message body here. In general, this is the output of a Plug-in for Data Conversion render activity, but can be an array of bytes. If string data is to be mapped to this field, use the XPath function tib:string-to-base64 to convert it to bytes.

This field is only displayed when Binary is selected in the Message Content Type area.

text N This field contains a text representation of the bytes in the message body as converted using the default Java encoding.

This field is only displayed when Text is selected in the Message Content Type area.

appProperties N Contains fields that correspond to the schema as it is defined in the application properties resource that is mapped to this activity.
Note: The appProperties node is only present if a WMQ Properties Resource has been configured for the activity.
messageFields N This element is present when Schema is selected from the Message Content Type list of the General tab. The contents of the mapped schema are present in this node for mapping purposes.

Output

The following table lists the output items for the Publish activity:

Output Item Module Property? Description
InteractionOutput N The root node for all the output provided by the activity.
mqproperties N The node containing all the message header fields (plus the destination override) as they are mapped from the message after it is sent.
  • destination: to document the destination for this message. If the topic is a dynamic topic, the generated name is reported here.
  • destqmgr: to document the remote queue manager specified in the input schema.
  • topicdynamic: to document the effective topic string for this publication. This includes the root portion from any administratively defined topic provided, as well as any dynamic portion.
  • correlationId: to document the message correlation ID, if any.
  • messageId: to document the message ID.
  • characterSet: to document the character set the queue manager uses to process this message.
  • alternateUserId: to document the alternate user ID used in this operation, if any.
  • accountingToken: as provided in the input schema.
  • applicationIdData: as provided in the input schema.
  • applicationOriginData: as provided in the input schema.
  • putApplicationType: as provided in the input schema.
  • putApplicationName: as provided in the input schema.
  • userId: the effective user ID used to connect to the queue manager.
  • replyToQueueName: same as input.
  • replyToQmgrName: same as input.
  • format: the character string placed into the format field by the sending application.
  • expiry: to indicate the number in tenths of a second that the message is to be kept in the queue before being deleted. Defaults to -1, which means there is no expiration.
  • priority: the priority (from 1 to 9) with which the message is sent.
  • reportOptionPan: reflects the value of the Positive Acknowledgment bit of the report field. This field is an application-only field and is not acted upon by the queue manager.
  • reportOptionNan: reflects the value of the Negative Acknowledgment bit of the report field. This field is an application-only field and is not acted upon by the queue manager.
  • report: this is the report options field for the message. If nothing is entered, then the report options as configured in the Advanced tab are used to populate it at run time. However, if a number is mapped here, it is logically OR'ed with the results of processing the report options. It is provided to enable the use of report options not configurable in the Advanced tab.
  • encoding: this is the encoding field for the message and it specifies the representation used for numeric values in the application message data. This applies to binary, packed decimal, and floating-point data. This encoding element is used when the processing of fields mapped by a message body schema. For specific values, see the MQMessage encoding field in the IBM MQ documentation.
  • messageType: an enumerated value indicating the message type.
    Where:
    • 8 is Datagram.
    • 2 is Reply.
    • 4 is Report.
    • 1 is Request.
  • backoutCount: the number of times this message is backed out before being committed.
  • feedback: if the message is a Report message, this field defines the nature of the report. Defaults to 0 for non-report messages.
  • version: to document the version of the message. This plug-in supports type 2 messages only.
  • putDateTime: the time that the message is placed into the queue.
  • groupStatus: to indicate the logical message status of a message. Pub/Sub does not support logical messages so this field is empty.
responsetimemillisec N To indicate, in milliseconds, how long it takes to publish the message.

Fault

The Fault tab lists exceptions that occur in the Publish activity:

Error Schema Element Data type Description
msg String The ActiveMatrix BusinessWorks Plug-in for IBM MQ error message.
msgCode String The ActiveMatrix BusinessWorks Plug-in for IBM MQ error code.
mqCompCode String If the message originates as an IBM MQ API exception, then that exception's completion code is here.
mqReasonCode String If the message originates as an IBM MQ API exception, then that exception's reason code is here.
mqErrorCode String If the message originates as an IBM MQ API exception, then that exception's error code is here.