WebSphere MQ Suite Async Receive Adapter
The WebSphere MQ Suite Async Receive receives messages as soon as they are available on the queue instead of waiting for a scheduled job to poll the queue.
For this adapter to work correctly, before you configure the adapter, you must download the J2EE(TM) Connector Architecture Specification Interface Classes connector.jar file and install it with install3rdParty.
The following table provides an overview of the WebSphere MQ Suite Async Receive:
Category | Description |
---|---|
System Name | WSMQAsyncRcv |
Graphical Process Modeler (GPM) categories) | None – cannot be used as part of a business process. |
Description | Used to receive messages asynchronously and
invoke business processes. Note: You need to configure this
adapter if you are receiving CHIPS messages using the MQ
transport mode in the CHIPS adapter.
|
Business usage | To receive messages as soon as they are available on the queue instead of waiting for a scheduled job to poll the queue. |
Usage example | Once an instance of this adapter is configured, it immediately and continuously performs “gets” on the queue to receive messages and then starts the specified business process. |
Preconfigured? | No. |
Requires third-party files? | com.ibm.mq.jar version 5.2.0 or later and associated message catalog property files (i.e. mqji_en_US.property). These files need to be installed using install3rdParty. |
Platform availability | All supported application platforms. |
Related services |
Related services:
|
Application requirements | You must have a WebSphere MQ server. |
Initiates business processes? | Yes. Always invokes a business process when data is received. |
Invocation | Cannot be invoked by a business process; runs as soon as it is configured. |
Business process context considerations | This adapter can either automatically commit
the messages received or it can pass the session identifier on
to the invoked business process where further processing
(puts, gets, etc) can occur. If “Get Type” is
configured as “Get One”, the invoked business
process will only contain the primary document. If “Get
Type” is configured as “Get All”, the
invoked business process will contain one or more documents
based on the other message handling parameters. Note: The WSMQ
Suite Commit service, which is the “other end”
of this service, is ignored if it exists within a
distributed transaction.
|
Returned status values | No status values returned since it cannot be used in a business process. |
Restrictions | None. |
Persistence level | Default. |
Testing considerations | While testing this service, it is recommended that you turn on debugging (wsmq_debug=Yes), which provides useful information if problems occur. |
Implementing the WebSphere MQ Suite Async Receive
- Create a configuration of the WebSphere MQ Suite Async Receive.
- Specify field settings for the adapter configuration in the application Admin Console as necessary.
Configuring the WebSphere MQ Suite Async Receive
You must specify field settings in the application, using the Admin Console.
Creating or Setting Up a Service Configuration in the Admin Console
Use the field definitions in the following table to create a new configuration of the WebSphere MQ Suite Async Receive, or to set up the configuration provided with the application:
Field | Description |
---|---|
Name | Unique and meaningful name for the adapter configuration. Required. |
Description | Meaningful description for the adapter configuration, for reference purposes. Required. |
Select a Group | Select one of the options:
Note: See Managing Services and
Adapters.
|
Host Name (wsmq_hostname) | The host name or IP address of the WebSphere
MQ server. Valid value is alphanumeric. If not specified,
bindings mode is used. Optional. To configure Sterling B2B Integrator as a high availability multi-instance of WebSphere MQ queue manager, configure the Host Name as the following: host1(port),host2 where host1 is the host name or IP address of the active QMGR and host2 is the host name or IP address of the passive QMGR host. Note: This parameter is required when configuring the
adapter for use with CHIPS. This Host Name must be the
same as the Websphere MQ Server Name that you configured
in the CHIPS adapter.
|
Port Number (wsmq_port) | The listening port of the WebSphere MQ
server. Valid value is a valid numeric port. Default is 1414.
Optional. Note: This parameter is required when configuring
this adapter for use with CHIPS. This Listening Port must be
the same as the WebSphere MQ Server Port No. that you
configured in the CHIPS adapter.
|
Queue Manager (wsmq_qmanager) | The Queue Manager name to use. Valid value is
alphanumeric. If not specified, uses the default queue
manager. Optional. Note: This parameter is required when
configuring this adapter for use with CHIPS. This Queue
Manager name must be the same as the Reply-To Queue Manager
name that you configured in the CHIPS
adapter.
|
Channel (wsmq_channel) | The channel to use. Valid value is
alphanumeric. Required. Note: This parameter is required when
configuring the adapter for use with CHIPS. This Channel
name must be the same as the Channel name you configured in
the CHIPS Adapter.
|
User Identifier (wsmq_userid) | A user identifier if required to access the
WebSphere MQ server. Valid value is alphanumeric. Default is
blank when not provided. Optional. Note: This parameter is
optional when configuring this adapter for use with CHIPS.
This User Identifier must be the same as the Websphere MQ
Server User ID that you configured in the CHIPS adapter, if
present.
|
Password (wsmq_password) | A user password if required to access the
WebSphere MQ server. Valid value is alphanumeric. Default is
blank when not provided. Optional. Note: This parameter is
optional when configuring for use with CHIPS. This Password
must be the same as the WebSphere MQ Server Password that
you configured in the CHIPS adapter, if present.
|
CCSID (mq_ccsid) | If needed, enter the Coded Character Set
Identifier (CCSID) that represents the codeset name you wish
to use. There is no default for this field. Optional.
Note: CCSID is not used when connecting directly using
“binding mode.”
|
Queue Name (wmq_qname) | The name of a previously opened queue used to
PUT messages. Any value is valid. Required. Note: This
parameter is required when configuring for use with CHIPS.
This Queue Name must be the same as the Reply-To Queue name
that you configured in the CHIPS adapter.
|
Remote Queue Manager | The name of the remote queue manager, which is any queue manager other than the local queue manager. A remote queue manager exists on a remote machine across the network, or on the same machine as the local queue manager. Optional. |
Dynamic Queue Name | The name of the Dynamic Queue. Dynamic queues
are created by the queue manager when an application issues an
MQOPEN request specifying a queue name that is the name of a
model queue. The dynamic queue that is created in this way is
a local queue whose attributes are taken from the model queue
definition. Optional. Note: The Dynamic Queue Name can be
specified by the application or the queue manager can
generate the name and return it to the application. Dynamic
queues defined in this way are either temporary queues,
which do not survive product restarts, or permanent queues
that do survive.
|
Alternate User Identifier | The identifier for the alternate user.
Alternate-user authority controls whether one user profile can
use the authority of another user profile when accessing a
WebSphere MQ object. Optional. Note: This authority is
essential when a server receives requests from a program and
the server wants to ensure that the program has the required
authority for the request. The server might have the
required authority, but it needs to know whether the program
has the authority for the actions it has
requested.
|
Binding Options (wsmq_MQOO_binding) | These options apply when the queue being
opened is a cluster queue. Optional. Valid values are:
|
Context Options (wsmq_MQOO_context) | These options control the processing of
message context. Optional. Valid values are:
|
MQOO_FAIL_IF_QUIESCING? (wsmq_MQOO_failifquiescing) | Indicates whether or not to include the MQOO_FAIL_IF_QUIESCING Open Option. Valid values are Yes and No. Default is Yes. Optional. |
Automatically Commit? (wsmq_autocommit) | Determines if the adapter should automatically commit messages received or pass on the session identifier to the invoked business process for additional processing. Valid values are Yes and No. Default is Yes. Optional. |
Enable debug messages? (wsmq_debug) | Used to turn on debugging messages for this adapter instance. Valid values are Yes and No. Default is No. Optional. |
SSL (SSL_SETTING_ssl_option) | Whether SSL is active. Valid values:
|
Cipher Suite (SSL_SETTING_cipherSuite) | Specifies a valid SSL Version 2 or Version 3 cipher. For example, SSL_RSA_WITH_3DES_EDE_CBC_SHA. |
Key Certificate (System Store)(SSL_SETTING_keyCertID) | Specifies a valid key certificate for client
authentication. For example:
frcppe03z3:1df073d:1153772f2cb:- 66demg2sdsb:1a679b7:116218d328a:-5e84 |
CA Certificate (SSL_SETTING_ca_cert_ids) | Specifies a CA certificate for server
authentication. For MQ, only one certificate may be selected.
For example: Measle1:1decdec:11159ba495b:-583c, frcppe03z3:1037c71:11584abf184:-7c4d, Measle1:1decdec:11159ba495b:- 5837Measle1:1decdec:11159ba495b:-5837 |
Get Type (wsmq_type) | Specifies the type of Get to perform.
Optional. Valid values are:
Note: This parameter is required when
configuring this adapter for use with CHIPS, and the
required Get Type is GETONE.
|
Receive Message Limit (wsmq_rcvMsgLimit) | Used with GETALL or BROWSEALL to limit the number of messages received. Valid values are 0 (unlimited) to 999999999. Default is 0 (unlimited). Optional. |
MQGMO_ALL_MSGS_AVAILABLE (wsmq_MQGMO_allmsgavail) | Valid values are Yes and No. Select Yes (default) to include this Get Message Option. Optional. |
MQGMO_ALL_SEGMENTS_AVAILABLE (wsmq_MQGMO_allsegavail) | Valid values are Yes and No. Select Yes (default) to include this Get Message Option. Optional. |
MQGMO_COMPLETE_MSG (wsmq_MQGMO_completemsg) | Valid values are Yes and No. Select Yes (default) to include this Get Message Option. Optional. |
MQGMO_CONVERT (wsmq_MQGMO_convert) | Valid values are Yes (true) and No (false). Default is No. Select Yes to include this Get Message Option. A value of Yes (true) converts an ASCII message to EBCDIC or an EBCDIC message to ASCII. Optional. |
MQGMO_FAIL_IF_QUIESCING (wsmq_MQGMO_failifquiescing) | Valid values are Yes and No. Select Yes (default) to include this Get Message Option. Optional. |
MQGMO_LOGICAL_ORDER (wsmq_MQGMO_logicalorder) | Select Yes (default) to include this Get Message Option. Optional. |
MQGMO_SYNCPOINT (wsmq_MQGMO_syncpoint) | Select Yes (default) to include this Get Message Option. Optional. |
Wait Interval (milliseconds) (wsmq_MQGMO_waitInterval_async) | Specifies the polling interval. Should be less than 15 minutes, that is, session timeout. Valid value is any valid long integer value less than session timeout of 15 minutes (900000 milliseconds). Default is 10 sec. Optional. |
Message Handling (wsmq_msgHandling) | Select the type of message handling to be
used. Optional. Valid values are:
|
Total Business Process Queue Depth Threshold (V5.2.6.1 or later) | Maximum number of queued business processes
allowed for this adapter. If this value is not defined, or the value is 0, the adapter processes the message from WSMQ if there is a message. If the total business process
queue depth in Sterling B2B Integrator is:
|
Group messages (wsmq_groupBy) | Selects which identifier to use when grouping
messages. Optional. Valid values are:
Note: Only displayed if the wsmq_msgHandling parm is set
to GROUP.
|
Use the group status flag to determine end-of-group? (wsmq_useGroupStatus) | Specifies whether to use the group status to
determine end of a group or to receive until no more messages
are available. Valid values are Yes and No. Default is No.
Optional. Note: Only displayed if the wsmq_msgHandling parm is
set to GROUP.
|
Group messages even when the identifier is MQ*_NONE? (wsmq_groupMsgWhenIdNone) | Determines if messages will be grouped even
if the identifier equals MQ*_NONE. Valid values are Yes and No
Default is Yes. Optional. Note: Only displayed if the
wsmq_msgHandling parm is set to GROUP.
|
Document Storage Type (docStorageType) | Determines the media used for temporary
storage of data while processing. Optional. Valid values are:
|
Document tracking (wsmq_docTracking) | Specifies whether to perform document tracking. Valid values are Yes and No. Default is No. Optional. |
Document Name (wsmq_docName) | The document name to associate with the data received. Any value is valid. Default is %^.dat. Optional. |
Buffersize override (wsmq_buffersize) | If specified, overrides the default buffersize used when streaming data. Valid values are 0-999999999. Optional. |
Metadata1 To Include (wmq_metadata1) | Specifies which metadata fields (added
together if multiple) from the message to include with the
Document created in ProcessData. Optional. Valid values are:
|
Metadata2 To Include (wmq_metadata2) | Specifies which metadata fields (added
together if multiple) from the message to include with the
Document created in ProcessData. Optional. Valid values are:
|
Maximum Bootstrap Threads (wmq_maxThreads) | The maximum number of threads to use when invoking business processes. Valid values are 0 (unlimited) - 99999. Default is 10. Optional. |
Bootstrap Workflow (wsmq_bootFlow) | The name of the business process to invoke
once messages are received. Valid value is an existing
business process. Required. Note: This parameter is required
when configuring the adapter for use with CHIPS. If you are
using MQ as a transport method for CHIPS, you must select
the CHIPSUtility_ReceiveHandler.bpml
business process. This preloaded system business process
checks the Queue Manager Name, Queue name and Channel Name
and uses the correct CHIPS Adapter to send back the required
acknowledgement. The Queue Manager name, Queue Name, and
Channel Name are taken from the Process Data when this
business process is invoked. Based on the values from the
Process Data, it will check the values in the CHIPS adapter
Reply-To Queue Manager, Reply-To Queue, and Channel Name to
pick up the correct CHIPS adapter instance.
|
Failure Workflow (wsmq_failFlow) | Specifies the business process to start if all failure retries have been exhausted. Valid value is a valid and existing business process. Optional. |
Failure retry attemptswsmq_retryCount() | The number of retry attempts when exceptions occur. Valid value is any valid integer. Using the value “–1” specifies infinite retry attempts. 0 specifies no retry attempts. Optional. |
Delay between retries (wsmq_retrySleep) | The number of milliseconds to wait before retrying. Valid value is any valid long integer. Default is 300000 (5 minutes). Optional. |
User (wsmq_userID) | This user identifier is used as part of the
security context for the invoked business process. Optional.
Note: This parameter is optional when configuring for CHIPS.
This User Identifier must be the same as the Websphere MQ
Server User ID configured in the CHIPS adapter, if
present.
|
Parameters Passed From Adapter to Invoked Business Process
The following table contains the parameters passed from the WebSphere MQ Suite Async Receive to the business process it invokes:
Parameter | Description |
---|---|
wsmq_sessionid | This value is only passed to the invoked business process if wsmq_autocommit=No. The invoked business process is then responsible for making sure that the data is committed or backed out as necessary and that the session is properly closed. Optional. See the example that follows this table. |
accountingToken | The accounting token of this message. Because this value could contain embedded nulls, it is a hex representation of the string so that no characters are lost. |
applicationIdData | The application identifier data of this message. |
applicationOriginData | The application origin data of this message. |
characterSet | The character set of this message |
correlationId | The correlation identifier of this message. Because this value could contain embedded nulls, it is a hex representation of the string so that no characters are lost. |
DocumentX | If wsmq_type=GETONE, then PrimaryDocument is created. If wsmq_type=GETALL, one or more documents are created in sequential order starting with 1 (for example, Document1, Document2, Document3...). |
DocumentCount | The number of documents created in ProcessData. |
encoding | The message encoding. |
expiry | The message expiry of this message. |
feedback | The message feedback of this message. |
format | The format of this message. |
groupId | The group identifier of this message. Because this value could contain embedded nulls, it is a hex representation of the string so that no characters are lost. |
groupStatus | The message group status of this message. |
messageFlags | The message flags of this message. |
messageId | The message identifier of this message. Because this value could contain embedded nulls, it is a hex representation of the string so that no characters are lost. |
messageSequenceNumber | The message sequence number of this message. |
messageType | The type of message received. |
offset | The current message offset. |
persistence | The persistence setting for this message. |
priority | The priority setting for this message. |
putApplicationName | The put application name of this message. |
putApplicationType | The put application type of this message. |
putDateTime | The put date and time of this message in the format “MM-dd-yyyy HH:mm:ss”. |
replyToQueueManagerName | The reply to queue manager of this message. |
replyToQueueName | The reply to queue of this message. |
report | The contents of the report field of this message. |
Examples
Example 1 – Process Data
The values specified for wsmq_metadata1 and wsmq_metadata2 determine which metadata fields are included with each document. The following example is what process data would look like as a result of specifying 4095 for both wsmq_metadata1 and wsmq_metadata2:
<ProcessData>
<WSMQ>
<DocumentCount>1</documentCount>
<Document1 SCIObjectID="df8f5e:102fa5a6c8f:-7414">
<messageId>414D5120514D5F6761727931303030205D624C4220000502</messageId>
<correlationId>000000000000000000000000000000000000000000000000
</correlationId>
<groupId>000000000000000000000000000000000000000000000000</groupId>
<accountingToken>16010515000000B5E512BBA14EC030000000000000000B
</accountingToken>
<replyToQueueManagerName>QM_gary1000</replyToQueueManagerName>
<replyToQueueName/>
<applicationIdData/>
<applicationOriginData/>
<messageType verbose="Datagram">8</messageType>
<format>MQSTR </format>
<report>0</report>
<feedback>0</feedback>
<groupStatus/>
<encoding>273</encoding>
<characterSet>819</characterSet>
<expiry>-1</expiry>
<putDateTime>03-31-2005 15:58:18</putDateTime>
<putApplicationName>MQSeries Client for Java </putApplicationName>
<putApplicationType>28</putApplicationType>
<messageFlags>0</messageFlags>
<messageSequenceNumber>1</messageSequenceNumber>
<offset>0</offset>
<persistence>0</persistence>
<priority>0</priority>
</Document1>
</WSMQ>
</ProcessData>
Example 2 – Processing Batch Documents Using GETALL
The following is an example of how to process batch documents received from a WebSphere MQ server. The following example could be used as the bootstrap workflow defined in the WebSphere MQ Suite Async Receive. This example iterates through all batch documents received and extracts each of them using the File System adapter:
<process name="(MyBusinessProcess)">
<rule name="has more docs">
<condition>number(/ProcessData/index/text()) < number(
/ProcessData/WSMQ/DocumentCount/text())</condition>
</rule>
<sequence>
<assign to="index">0</assign>
<choice name="for each doc">
<select>
<case ref="has more docs" activity="process doc"/>
</select>
<sequence name="process doc">
<assign to="index" from="number(number(index) + 1)"></assign>
<operation name="File System Adapter">
<participant name=" (My_File_System_Adapter)"/>
<output message="FileSystemInputMessage">
<assign to="." from="*"></assign>
<assign to="Action">FS_EXTRACT</assign>
<assign to="PrimaryDocument" from="/ProcessData/WSMQ/*[number(
/ProcessData/index/text())]/@SCIObjectID"></assign>
</output>
<input message="inmsg">
<assign to="." from="*"></assign>
</input>
</operation>
<repeat name="next doc" ref="for each doc"/>
</sequence>
</choice>
</sequence>
</process>
Example 3 – Sending Messages Using the Adapter
To send messages using the WebSphere MQ Suite adapter, set the parameters in a business process, as follows:
<PARM>
<name>SSL_SETTING_ca_cert_ids</name>
<value>Measle1:1decdec:11159ba495b:-583c,frcppe03z3:1037c71:11584abf184:-7c4d,
MBradley1:1decdec:11159ba495b:-5837</value>
</PARM>
<PARM>
<name>SSL_SETTING_cipherSuite</name>
<value>SSL_RSA_WITH_3DES_EDE_CBC_SHA</value>
</PARM>
<PARM>
<name>SSL_SETTING_keyCertID</name>
<value>frcppe03z3:1df073d:1153772f2cb:-66de</value>
</PARM>
<PARM>
<name>SSL_SETTING_ssl_option</name>
<value>SSL_MUST</value>
</PARM>