MSMQ Adapter

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:

Category	Description
System name	MSMQ
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: Send mode – Sends a message from a business process to a named queue on a specified Microsoft Windows® MSMQ server. The MSMQ adapter also returns pertinent message metadata to the business process after sending the message. Retrieve mode – In a business process, the MSMQ adapter retrieves messages from a specified queue on a specified MSMQ server. When in retrieve mode, the MSMQ adapter continues to retrieve messages until the queue is empty. The MSMQ adapter also runs a specified business process for each message in the queue and passes the message body and selected metadata parameters to the business process that is running.
Business Usage	Processing messages from an MSMQ server as part of a business process.
Preconfigured?	No
Requires third party files?	No
Platform availability	All supported Sterling B2B Integrator platforms
Related services	No
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: Success – The run was successful for the specified action Error – An error occurred when the specified action was executed
Restrictions	Restrictions: The MSMQ adapter supports single message transactions for guaranteed exactly-once delivery of messages. Other transaction modes are not supported. The MSMQ adapter supports external transactions to MSMQ; that is, a transaction from Sterling B2B Integrator for a SEND action. This only applies to transactional queues in MSMQ. The MSMQ adapter does not support MSMQ acknowledgements.
Persistence Level	Full (default). Note: When running in transactional mode, this setting is overridden at the business process level and set to Zero persistence.

Requirements

To use the MSMQ adapter, you need:

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 following steps summarize how the MSMQ adapter works in a business process within Sterling B2B Integrator:

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 Element	Description
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_RETURNED_MESSAGE	Retrieved message.
MSMQ_XACTIONAL QUEUE	Name of the transactional queue from which the message was received.

Implementing the MSMQ Adapter

To implement the MSMQ adapter, complete the following tasks:

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.

Installing MSMQPrime

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.

To install MSMQPrime, complete the following steps:

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:

Note: This table contains configuration parameters for both Send and Retrieve. The field names in parentheses represent the corresponding field names in the GPM. This information is provided for your reference.

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: None – You do not want to include this configuration in a group at this time. Create New Group – You can enter a name for a new group in this field, which will then be created along with this configuration. Select Group – If you have already created one or more groups for this service type, they are displayed in the list. Select a group from the list.
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, `UseFormatName` to True. This prepends the `QueuePathName` with "FormatName:". Valid values are True and False.

GPM Configuration

The following table describes the fields used to configure both Send and Retrieve configurations for the MSMQ adapter in the GPM:

Field	Description
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. Optional. 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:

Send Action

<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>

Retrieve Action

<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>