WebSphere MQ Suite Open Session Service
The WebSphere MQ Suite Open Session service is used in conjunction with the other WebSphere MQ Suite services to send and receive messages from a WebSphere MQ server.
The following table provides an overview of the WebSphere MQ Suite Open Session service:
Category | Description |
---|---|
System Name | WSMQOpenSession |
Graphical Process Modeler (GPM) categories) | All Services, Messaging |
Description | Used as part of the WebSphere MQ Suite of services to open a session, which establishes a connection to a WebSphere MQ Queue Manager. |
Business usage | Used in conjunction with the other WebSphere MQ Suite services to send and/or receive messages from a WebSphere MQ server. |
Usage example | Must be called first before any other WebSphere MQ Suite services. |
Preconfigured? | Yes – a default instance is created during install, which can be used by all business processes. Default instance name is WSMQ_OpenSession. |
Requires third party files? | com.ibm.mq.jar version 5.2.0 or higher and associated message catalog property files (i.e. mqji_en_US.property). These files need to be installed using install3rdParty. |
Platform availability | All supported Sterling B2B Integrator platforms |
Related services | Related services:
|
Application requirements | You must have a WebSphere MQ server. |
Initiates business processes? | No. This service does not invoke business processes or process any business process documents. |
Invocation | Invoke the default instance in a business process and specify the appropriate parameters. |
Business process context considerations | If multiple connections (sessions) to different queue managers is required within the same business process, it is the responsibility of the business process writer to save off the wsmq_sessionid values returned from this service and pass them into the appropriate services where needed. |
Returned status values | Returned status values:
|
Restrictions | None |
Persistence level | Default |
Testing considerations | Debug messages can be turned on as part of the business process without having to turn on full system debugging. All logging for this suite of services goes to a separate log file called WebSphere MQSuite. MQ tracing can also be activated as part of the service configuration. |
Implementing the WebSphere MQ Suite Open Session Service
There are no steps required for implementing this service. The default configuration, WSMQ_OpenSession, is ready for use as soon as Sterling B2B Integrator is installed. However, you can edit the service's parameter settings for specific business processes in the GPM.
Setting Up the Service in the GPM
Use the field definitions in the following table to set up the service configuration in the GPM:
Field | Description |
---|---|
Config | Select the name of the service configuration from the list. |
Channe l(wsmq_channel) | The channel to use. Valid value is alphanumeric. No default. Required. |
Turn on debug messages? (wsmq_debug) | Used to turn on debugging messages for this session. Valid values are Yes and No. Default is No. Optional. |
Error Status For MQException (wsmq_errorOnMQException) | Normally when an MQException occurs, the workflow status is set to error but this allows it to be set to success so that the workflow can perform its own error process or retry logic. Valid values are Yes and No. Default is Yes. Optional. |
Host Name (wsmq_hostname) | The host name or IP address of the WebSphere MQ server. Valid value is
alphanumeric. Optional; if not specified, bindings mode is used. 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. |
Password (wsmq_password) | A user password if required to access the WebSphere MQ server. Valid value is alphanumeric. No default. Optional. |
CCSID (mq_ccsid) | If needed, enter the Coded Character Set Identifier (CCSID) that represents the
codeset name you wish to use. Optional.
Note: CCSID is not used when connecting directly using “binding mode.”
Note: CCSID is not used when connecting directly using “binding moce.”
|
Listening Port (wsmq_port) | The listening port of the WebSphere MQ server. Valid value is valid port. Default is 1414. Optional. |
poolName | The name of the connection pool associated with a session. Valid value is alphanumeric. Optional. |
poolLimit | The maximum number of connections on a queue WebSphere MQ Suite Open Session
service can open when connecting to the WebSphere MQ server. After the number of connections reaches
the maximum limit specified, the sessions wait until a connection is released. Valid value is any
number. Optional. Note: If you specify a value for poolName and do not specify a value for
poolLimit, the value of poolLimit will be set to 0.
|
Queue Manager (wsmq_qmanager) | The Queue Manager name to use. Valid value is alphanumeric. Optional; if not specified, uses the default queue manager. |
Session Timeout Minutes (wsmq_sessiontimeout) | Overrides the default session timeout. Valid value is numeric, specified in minutes. Default is 3 (minutes). Optional. |
Turn on MQ tracing? (wsmq_trace) | Used to turn on MQ level 5 tracing. Instance must be cycled (disable/enabled) to
take effect. Valid values are Yes and No. Default is No. Optional. Important: You must also configure Java diagnostic configuration details for this
feature to work properly. See the Java diagnostics topic in the WebSphere MQ Knowledge Center for
more information:
http://ibm.com/support/knowledgecenter/SSFKSJ_7.0.1/com.ibm.mq.amqzag.doc/fa15460_.htm
Configure
the JAVA diagnostic configuration details:
|
3. Perform the operation. By default, the trace logs are collected in
Otherwise, the trace logs will be
available in the location specified in Diagnostics.Java.Trace.Destination.Pathname
in step 2.
|
|
Trace output filename (wsmq_traceFile) | User specified fully qualified path and filename to use for trace output. Any value is valid. No default. Required if using Turn on MQ tracing? (wsmq_trace) |
Trace Level (1-5) (wsmq_traceLevel) | User specified fully qualified path and filename to use for trace output. Any value is valid. No default. Required if using Turn on MQ tracing? (wsmq_trace). |
User Identifier (wsmq_userid) | A user identifier if required to access the WebSphere MQ server. Valid value is alphanumeric. No default. Optional. |
SSL parameters | You can enable the SSL option with sslProtocol set to TLS1.2 and
is configured in the WebSphere MQ property file. You can configure the following SSL parameters:
|
Parameters Passed From Business Process to Service
The parameters passed from the business process to the WebSphere MQ Suite Open Session service are the same as those configurable in the GPM, listed in Setting Up the Service in the GPM.
Parameters Passed From Service to Business Process
The following table contains the parameters passed from the WebSphere MQ Suite Open Session service to the business process:
Parameter | Description |
---|---|
wsmq_sessionid | The session identifier is a Global Unique Identifier (GUID) that is then used by all other WebSphere MQ Suite services as it maintains the connection to a queue manager for subsequent operations. |
WSMQ/CompletionCode | Only set if an MQException occurs and indicates the completion code. |
WSMQ/ReasonCode | Only set if an MQException occurs and indicates the reason code. |
Business Process Example
The following example illustrates how the WebSphere MQ Suite Open Session service can be used in a business process:
<process name = "PUTexample">
<sequence name="OpenSession">
<operation name="Open Session">
<participant name="WSMQ_OpenSession"/>
<output message="toService">
<assign to="." from="*"/>
<assign to="wsmq_hostname">some_host_name</assign>
<assign to="wsmq_channel">some_channel_name</assign>
<!-- <assign to="wsmq_debug">Yes</assign> -->
</output>
<input message="fromService">
<assign to="." from="*"/>
</input>
</operation>
<sequence name="SessionOpened">
<operation name="Open Queue">
<participant name="WSMQ_OpenQueue"/>
<output message="toService">
<assign to="wsmq_sessionid" from="string(wsmq_sessionid)"/>
<assign to="wsmq_qname">some_queue_name</assign>
<assign to="wsmq_MQOO_type">PUT</assign>
<assign to="wsmq_MQOO_failifquiescing">Yes</assign>
</output>
<input message="fromService"/>
</operation>
<operation name="PUT message(s)">
<participant name="WSMQ_PutMessage"/>
<output message="toService">
<assign to="." from="*"/>
<assign to="wsmq_qname">some_queue_name</assign>
<!-- If neither two following assign's are specified,
the PrimaryDocument will be sent
OR to perform batch sending, use the following assign:
<assign to="wsmq_batchFilter">*</assign>
OR to send some other single document, use the following assign:
<assign to="wsmq_document" from="SomeDocumentName/@*"/>
-->
</output>
<input message="fromService">
<assign to="." from="*"/>
</input>
</operation>
<operation name="Commit the PUT">
<participant name="WSMQ_Commit"/>
<output message="toService">
<assign to="wsmq_sessionid" from="string(wsmq_sessionid)"/>
</output>
<input message="fromService"/>
</operation>
<operation name="Close Queue">
<participant name="WSMQ_CloseQueue"/>
<output message="toService">
<assign to="wsmq_sessionid" from="string(wsmq_sessionid)"/>
<assign to="wsmq_qname">some_queue_name</assign>
</output>
<input message="fromService"/>
</operation>
<sequence name="CloseSession">
<operation name="Close Session">
<participant name="WSMQ_CloseSession"/>
<output message="toService">
<assign to="wsmq_sessionid" from="string(wsmq_sessionid)"/>
</output>
<input message="fromService"/>
</operation>
</sequence>
<onFault>
<operation name="Make sure session is closed">
<participant name="WSMQ_CloseSession"/>
<output message="toService">
<assign to="wsmq_sessionid" from="string(wsmq_sessionid)"/>
</output>
<input message="fromService"/>
</operation>
</onFault>
</sequence> <!-- end of SessionOpened sequence -->
</sequence> <!-- end of OpenSession sequence -->
</process>
Business Process Example - poolName and poolLimit
The following example illustrates how the poolName and poolLimit parameters in the WebSphere MQ Suite Open Session service can be used in a business process:
<operation name="WebSphere MQ Suite Open Session">
<participant name="WSMQ_OpenSession"/>
<output message="WSMQOpenSessionInputMessage">
<assign to="wsmq_channel">channel</assign>
<assign to="wsmq_hostname">xx.xx.xx.xxx</assign>
<assign to="wsmq_port">1419</assign>
<assign to="wsmq_qmanager">NewQManager</assign>
<assign to="poolName">BPool</assign>
<assign to="poolLimit">3</assign>
<assign to="." from="*"/></assign>
</output>
<input message="inmsg"/>
<assign to="." from="*"/></assign>
</input>
</operation>