The MSMQ adapter sends messages to and reads messages from a remote Microsoft® Message Queue.
The following table provides an overview of the MSMQ adapter:
|Graphical Process Modeler (GPM) categories||All Services, Custom, Sync Mode, Transactional Mode
Note: This adapter will not display in the GPM stencils until you create a configuration of the adapter in the Sterling B2B Integrator Admin UI.
|Description||Sends messages to and reads messages from a remote Microsoft® Message Queue. You
can configure the MSMQ adapter to send and retrieve messages:
|Business Usage||Processing messages from an MSMQ server as part of a business process.|
|Requires third party files?||No|
|Platform availability||All supported Sterling B2B Integrator platforms|
|Application Requirements||The MSMQ adapter supports MSMQ version 1.1 and later. The MSMQ adapter supports 40-bit encryption for versions 1.1 and later and 128-bit encryption in versions 2.0 and later.|
|Initiates business processes?||Yes, when using the RETRIEVE action (reading a message from the queue).|
|Invocation||Runs as a service within a business process.|
|Returned status values||
Returned status values:
|Persistence Level||Full (default).
Note: When running in transactional mode, this setting is overridden at the business process level and set to Zero persistence.
- The connection from Sterling B2B Integrator to the system where the MSMQ server resides.
- The port number of the system where the MSMQ server resides. This port number is used by the MSMQ adapter.
- The queue must be preconfigured in the MSMQ server. This queue name is used by the MSMQ adapter. The queue can be transactional or non-transactional, depending on how you need to use the MSMQ adapter.
How the MSMQ Adapter Works
- The MSMQ adapter extracts the message body from the incoming business process context and sends it to a remote system Microsoft Message Queue.
- The MSMQ adapter creates a correlation ID and returns it in the process data elements.
- The adapter retrieves any response from the Microsoft Message Queue and places it back into the business process context.
- The adapter passes the updated business process context back to the business process and places any MSMQ elements into process data.
The following table contains the MSMQ elements placed into the process data after the MSMQ adapter runs:
|MSMQ_ARRIVEDTIME||When the messaged arrived at the queue.|
|MSMQ_BODY_TYPE||Whether the message is a string or byte array.|
|MSMQ_CORRELATIONID||ID number used to correlate related messages.|
|MSMQ_EXTENSION||A place to put additional information associated with the message.|
|MSMQ_FIRST_IN_XACT||Whether the message was the first message in a transaction.|
|MSMQ_LAST_IN_XACT||Whether the message was the last message in a transaction.|
|MSMQ_XACTID||Message ID from a transaction queue.|
|MSMQ_LABEL||Label for the message.|
|MSMQ_MSGID||Message ID from a regular queue.|
|MSMQ_PRIORITY||Message priority level.|
|MSMQ_XACTIONAL QUEUE||Name of the transactional queue from which the message was received.|
Implementing the MSMQ Adapter
- Activate your license for the MSMQ adapter. See An Overview of Implementing Services.
- Install the MSMQPrime component.
- Create and configure an MSMQ adapter configuration. For general instructions on creating a service configuration, see Creating a Service Configuration. For descriptions of the MSMQ adapter configuration parameters, see Configuring the MSMQ Adapter.
- Use the MSMQ adapter in a business process.
A component of the MSMQ adapter, MSMQPrime, is deployed on the host where the MSMQ server resides. The MSMQ adapter connects to the MSMQPrime component, which in turn, performs the send and receive actions and interacts with the MSMQ server. MSMQPrime listens on the port that is part of the MSMQ adapter configuration.
- Locate msmqbundle_xxx.jar in Sterling B2B Integrator under <INSTALL_DIR>/client/msmq folder.
- On the Windows MSMQ server host, create a folder for MSMQPrime. For example, C:\MSMQ.
- Copy msmqbundle_xxx.jar to the folder you just created.
- Change directory to that folder and unbundle the .jar file.
- Install the Java jdk version 1.6.0. Note the installation path.
Modify start_msmqPrime.cmd to use the folder you created in step 2. Set the MSMQADAPTER parameter to the folder you created in step 2. Set the JAVA parameter to point to the bin directory in the Java path created in step 7 (C:\jdk1.6.0\bin).Note: If Java is installed in the default installation folder in C:\Program Files\Java\jdk1.6.0, you have to reference it as C:\Progra~1\Java\jdk1.6.0\bin.
Change MSMQ_SERVER_PORT in msmqprim.properties, if necessary. The default is 8085. This is the port msmqPrime will run on.
Run start_msmqPrime.cmd. This script should be run by the user who has permission to create queues, read, and send messages to the MSMQ server. This process must be running continually if your MSMQ adapter needs to access it. It is recommended to convert it to an automatically started Windows service.
Create a configuration of the MSMQ adapter in Sterling B2B Integrator and configure it to point to this msmqPrime.
- Configure a service instance of MSMQ adapter in Sterling B2B Integrator to point to this msmqPrime.
Verify that the MSMQ adapter configuration is talking to this msmqPrime by including it in a business process and running it.
If desired for testing purposes, turn on debug mode in msmqPrime with the following command by passing -debug as an argument to MSMQPrimaImpl in start_msmq.cmd. The debugon option generates detailed logs.Note: The msmqbundle_xxx.jar you use to create the MSMQPrime component must be from the same Application installation as the MSMQ adapter that it will talk to. You need to redeploy the msmqbundle_xxx.jar to the Windows MSMQ server host when a Sterling B2B Integrator patch is installed. This ensures the new code changes are synchronized with MSMQPrime.
Configuring the MSMQ Adapter
To configure the MSMQ adapter, you must specify field settings in Sterling B2B Integrator and in the GPM.
Sterling B2B Integrator Configuration
The following table describes the fields used to configure the MSMQ adapter in Sterling B2B Integrator:
|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:
|Hostname(HostName)||Host name of the MSMQ server with which this configuration of the adapter communicates. Send and Retrieve parameters. Required.|
|PortNumber(PortNumber)||The port number of the MSMQ server host. Required.|
|Queue Path Name(QueuePathName)||Typical queue path name in the form machineName\queueName. Send and Retrieve parameters. Required.|
|EX_TRANSACTION||To include send action in the Sterling B2B Integrator engine transaction. Valid values are TRUE and FALSE (default). Send parameter. Optional.|
|UseFormatName||To retrieve messages from MSMQ Dead Letter Queue or the Journal, set the MSMQ
Adapter BP parameter,
The following table describes the fields used to configure both Send and Retrieve configurations for the MSMQ adapter in the GPM:
|Config||Name of the adapter configuration.|
|Action||Values are Send and Retrieve. Required if the action is Retrieve. If the action is Retrieve, specify business process. If the Action is Send, specify body type.|
|BodyType||Valid values are String (default) and Byte array. Send parameter. Optional.|
|BusinessProcessName||Business process that is started upon receipt of a message from the queue. Retrieve parameter. Required.|
|Delivery||Valid values are Recoverable (default) and Express. Send parameter. Optional.|
|EncryptionAlgorithm||CALG_RC2 (default) or CALG_RC4. Send parameter. Optional.|
|MaxTimeToReachQueue||Maximum time allowed for a message to reach its destination. Send parameter. Default is 300 seconds. Optional.|
|MaxTimeToReceive||Maximum time, in seconds, for a message to be received before it is discarded
from the queue. Send parameter. Default is 0. Optional.
Note: If set to 0, the message is not discarded.
|MessageLabel||Label for message being sent to queue. Optional.|
|MessagePriority||Valid values are 0 - 7, where 7 represents the highest priority messages in the
queue. The highest priority messages are received first. Send parameter. Default is 3.
Note: This parameter setting does not apply to messages sent to a transactional queue, which will always have a message priority of 0.
|PrivacyLevel||Used to request encryption. Valid values are None (default), Base (40-bit) and Enhanced (128-bit, supported in MSMQ version 2.0 and later). Send parameter. Optional.|
Business Process Examples
The following examples illustrate using the MSMQ adapter for send and receive actions:
<process name = "MSMQ_Base"> <sequence name="Test Sequence"> <operation name="MSMQ Commn"> <participant name="MSMQAdapter"/> <output message="outmsg"> <assign to="Action">SEND</assign> <assign to="PortNumber">0000</assign> <assign to="QueuePathName">server1\testqueue</assign> <assign to="MaxTimeToReceive">3600</assign> <assign to="MaxTimeToReachQueue">3600</assign> <assign to="MessagePriority">3</assign> <assign to="Delivery">RECOVERABLE</assign> <assign to="PrivacyLevel">Base</assign> <assign to="MessageLabel">Base</assign> <assign to="BodyType">BYTE ARRAY</assign> <assign to="GIS_TRANSACTION">TRUE</assign> <assign to="." from="*" /> </output> <input message="inmsg"> <assign to="." from="*" /> </input> </operation> </sequence> </process>
<process name = "MSMQ_Receive"> <sequence name="Test Sequence"> <operation name="MSMQ Commn"> <participant name="MSMQAdapter"/> <output message="outmsg"> <assign to="Action" from="'RETRIEVE'" /> <assign to="PortNumber" from="'0000'" /> <assign to="QueuePathName" from="'server1\testqueue'" /> <assign to="MessageLabel" from="'Receive'" /> <assign to="BusinessProcessName" from="'MSMQ_FileSystem'" /> <assign to="." from="*" /> </output> <input message="inmsg"> <assign to="." from="*" /> </input> </operation> </sequence> </process>