4EAI MSMQ Transport

EAI MSMQ Transport

This chapter discusses Oracle’s implementation of Microsoft Message Queuing (MSMQ) support with the EAI MSMQ Transport business service. It includes the following topics:

• About Microsoft Message Queuing (MSMQ)

• Configuring the EAI MSMQ Transport Servers

• Configuring EAI MSMQ Transport for Various Send and Receive Scenarios

About Microsoft Message Queuing (MSMQ)

Many large organizations are integrating various enterprise business applications into application networks. These networks allow applications to communicate with each other and share data, either automatically or by request. Technologies such as Microsoft Message Queuing (MSMQ) provide a messaging infrastructure for transporting data from one application to another, without the need for programming.

MSMQ allows applications running at different times to communicate across heterogeneous networks and systems, even when one or many of those systems are temporarily offline. Because applications send messages to queues and read messages from queues, the messages are always available and remain in the queue for as long as required. For example, the messages are still there when a system that was offline comes back online to retrieve them. Optionally, messages can be sent to a dead letter queue after a predetermined amount of time has passed to help make sure that only timely, relevant messages are received.

The following subtopics are described in this topic:

• About the EAI MSMQ Transport

• Methods for Sending and Receiving Messages

• EAI MSMQ Transport Named Subsystems

About the EAI MSMQ Transport

EAI MSMQ Transport is a Siebel business service that can be customized using Siebel Tools. With Siebel Tools, you define integration objects to be transported across the EAI MSMQ Transport business service. EAI MSMQ Transport is responsible for sending and receiving messages between a Siebel application and MSMQ queues. EAI MSMQ Transport allows you to:

• Send a message to an external system

• Send and receive synchronous messages between a Siebel application and an external system

• Receive a message and perform an action based on that message within a Siebel application

• Receive a message, perform an action within a Siebel application, and then send a synchronous response to the external system

Methods for Sending and Receiving Messages

EAI MSMQ Transport supports two transport modes: sending messages and receiving messages. The following methods are supported:

• Send

• Send and Receive Response (SendReceive)

• Receive

• Receive and Execute Service (ReceiveDispatch)

• Receive, Execute, Send Response (ReceiveDispatchSend)

Messages from a Siebel Application to an External System

You configure EAI MSMQ Transport using the Siebel Business Process Designer, where you specify various parameters, such as the queue where Siebel outbound messages are sent. You configure the message itself using the integration object feature within Siebel Tools. The message can be in any text or binary format, including XML. The default format is XML, where the integration object defines the XML Schema Definition (XSD) or the Document Type Definition (DTD) associated with the XML document.

You configure the EAI MSMQ Transport at design time to specify the MSMQ queue computer name and the queue name. You use the EAI MSMQ Transport along with the Siebel Business Process Designer Manager to model business processes for sending messages to the external system.

You can configure the EAI MSMQ Transport to send messages to external systems when an event occurs in a Siebel application. For example, suppose that one of your sales representatives enters a new opportunity for an account into a Siebel application. This information needs to be sent to other business units that might or might not be using a Siebel application. The message can be sent using EAI MSMQ Transport as the transport mechanism to inform these external systems.

EAI MSMQ Transport can also be used synchronously to send a message and receive a response back from an external system in a single session. For example, suppose that one of your customers calls your Call Center requesting information on an account. The sales agent initiates a process to send a request with the account name from a Siebel application to an external mainframe system using the EAI MSMQ Transport. In response, the sales agent then receives a list of transaction details for that customer displayed within a Siebel application form.

Messages to a Siebel Application from an External System

External applications can send messages to a Siebel application using EAI MSMQ Transport. These messages are received and routed by the EAI MSMQ Receiver in conjunction with the MSMQ system.

The EAI MSMQ Receiver is a Siebel Server component that waits for messages in a specified queue. If you select the Receive, Execute, Send Response method, then the EAI MSMQ Receiver waits for a response from a Siebel application and places the output into a response queue.

EAI MSMQ Transport Named Subsystems

The EAI MSMQ Transport can read parameters from a named subsystem. For this transport, the named subsystem type is MSMQSubsys.

For a discussion of named subsystems for Siebel EAI, see EAI Transports and Interfaces Overview. For more information about named subsystems, see Siebel System Administration Guide.

Configuring the EAI MSMQ Transport Servers

The instructions in this topic are for configuring the EAI MSMQ Transport servers. Use a two-server setup, configured as listed in the following topic. However, you can implement a single server or multiple servers.

MSMQ Primary Enterprise Controller

You configure the MSMQ Primary Enterprise Controller with the following components:

• Windows Server (for supported versions, see the Certifications tab on My Oracle Support)

  Note: For information about the Certifications application, see 1492194.1 (Article ID) on My Oracle Support.

• MSMQ Server

• As many MSMQ queues as needed

• Relevant ODBC driver

• Siebel Server

• Siebel Gateway

• Siebel Web Client

• Siebel Tools

Regional Enterprise Server and MSMQ Client

You configure the Regional Enterprise Server and MSMQ Client with the following components:

• Windows Server (for supported versions, see the Certifications tab on My Oracle Support)

  Note: For information about the Certifications application, see 1492194.1 (Article ID) on My Oracle Support.

• MSMQ Client

• As many MSMQ queues as needed

• The relevant ODBC driver

• Siebel Server

• Siebel Gateway

• Siebel Web Client

Note: The MSMQ Server can reside on either the MSMQ Primary Enterprise Controller or the Regional Enterprise Server. This functionality is independent of the underlying database. You can use any supported database, including IBM DB2, DB2 for z/OS, Oracle Database, and Microsoft SQL Server.

Configuring EAI MSMQ Transport for Various Send and Receive Scenarios

The EAI MSMQ Transport and the Siebel Business Process Designer Manager work in tandem to transfer data using MSMQ from one Siebel application to another Siebel application or to an external application. You can set up a workflow and choose attributes and values to define the transport for a particular send or receive scenario.

The following topics are described:

• EAI MSMQ Transport Prerequisites

• EAI MSMQ Transport Parameters

• About Defining Integration Objects

• Sending Outbound Messages with EAI MSMQ Transport

• Receiving Inbound Messages with MSMQ Receiver

EAI MSMQ Transport Prerequisites

You must set up both Microsoft SQL Server and MSMQ before configuring the EAI MSMQ Transport. In addition, the Siebel Business Process Designer Manager functionality must be available within Siebel Tools and Siebel Web Client.

EAI MSMQ Transport Parameters

The following information presents the parameters used for configuring the EAI MSMQ Transport.

Parameter	Description
EndOfData	Set to True to indicate end of data.
MsmqPhysicalQueueName	Name of the MSMQ Queue. Can be used for both sending and receiving messages.
MsmqQueueMachineName	Computer that owns the queue specified by the physical queue name.
MsmqRespQueueMachineName	Computer that owns the queue specified by MsmqRespQueueName.
MsmqRespQueueName	Name of the response queue.
MsmqSleepTime	Default is 20000 milliseconds. The amount of time that the EAI MSMQ Transport business service waits to receive a message.
TimedOut	If no message is received in seconds specified in SleepTime, then the TimedOut argument in the Output Property set is set to True.
IgnoreCorrelationId	Default is False. Set to ignore Correlation Id value on the inbound messages. If this flag is True, then the message is picked up from the queue regardless of the correlation Id on the message. This parameter is ignored for the SendReceive Method because Correlation Id is required to match the response with the original message.
LargeMessageSupport	Default is True. Set to enable or disable large-message (messages over 4 MB) support. Set IgnoreCorrelationId to False for Large Message Support.

About Defining Integration Objects

Before you use the EAI MSMQ transport, you must define integration objects for use with the transport. The various methods explained in the following pages assume that this integration object has already been defined. You define your Siebel messages as integration objects using Siebel Tools. These messages correspond to the information that you want to exchange between the Siebel application and an external application. An example of an integration object would be an order, an account, a quote, or a contact.

After you have created an integration object, you can then send the message corresponding to this integration object through the EAI MSMQ Transport, either as part of a workflow or as a custom business service.

For information about creating integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Sending Outbound Messages with EAI MSMQ Transport

With the Siebel application as the sender (outbound messaging), you design a workflow that queries for a record (such as a contact) and then converts that record to an XML document. The XML document is then sent to an MSMQ queue.

Because MSMQ imposes a limit of four megabytes on the size of the messages it can handle, the EAI MSMQ Transport separates outbound Siebel messages larger than four megabytes into smaller messages acceptable to MSMQ. The message is then reassembled after it has left MSMQ and arrived at your partner’s system.

There are two methods for sending messages from a Siebel application to MSMQ:

• Send

• Send and Receive Response (SendReceive)

Sending Messages with EAI MSMQ Transport

The following procedure describes how to set up your system to send a message to an external system using the EAI MSMQ Transport.

To send messages from a Siebel application to MSMQ

1. Access the Windows Computer Management tool by choosing the Start menu, Programs, Administrative Tools, and then Computer Management.

2. Set up an MSMQ queue to receive messages from the Siebel application. Give the queue an easily identified name, such as fromsiebel. The MSMQ queue you create (for example, fromsiebel) will appear in the list of queues.

3. Set the queue to be Transactional.

   Note: This flag allows Siebel Business Applications to group a number of Send or Receive messages. This is critical when large data sets are being used because it allows a commit or a rollback to be executed without failure.

4. Set up a workflow in Siebel Tools to send a message to MSMQ. The workflow should contain the following steps, as show in the following image:

   1. Siebel Adapter (Query)

   2. XML Converter (PropSet ToXML)

   3. EAI MSMQ Transport (Send)

   

   Note: For details on the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.

5. Create the following process properties:

   Name	Data Type	In/Out	Value
   Employee Message	Hierarchy	In/Out	Not applicable
   Employee XML	Binary	In/Out	Not applicable
   Error Code	String	In/Out	Not applicable
   Error Message	String	In/Out	Not applicable
   Object Id	String	In/Out	Row Id of an Employee record
   Siebel Operation Object Id	String	In/Out	Not applicable

6. Set up the first step of the workflow, after Start, to use the EAI Siebel Adapter business service with the Query method to query the information from the Siebel database using the following input and output arguments:

   Input Argument	Type	Value	Property Name
   OutputIntObjectName	Literal	Sample Employee	Not applicable
   PrimaryRowId	Process Property	Not applicable	Object Id

   Property Name	Type	Output Argument
   Employee Message	Output Argument	SiebelMessage

7. Set up the second step to use the EAI XML Converter business service with the PropSetToXML method to convert the data extracted from the Siebel Database to XML format using the following input and output arguments:

   Input Argument	Type	Property Name
   SiebelMessage	Process Property	Employee Message

   Property Name	Type	Output Argument
   Employee XML	Output Argument	<Value>

8. Set up the third step to use EAI MSMQ Transport with the Send method to send the information to the external system, using the following input arguments:

   Input Argument	Type	Value	Property Name
   <Value>	Process Property	Not applicable	Employee XML
   MsmqPhysicalQueueName	Literal	private$\FromSiebel	Not applicable
   MsmqQueueMachineName	Literal	SiebelServer Computer name where the Siebel MSMQ Transport is running.	Not applicable

9. Save the workflow and run it from the Workflow Simulator.

   Confirm that a message was sent to the queue using the MSMQ Explorer. In this example, if the simulation is successful, then a message is in the fromSiebel queue and contains an XML file with employee information.

Sending and Receiving Messages with EAI MSMQ Transport

The following procedure describes how to set up your system to send a message to an external system using the EAI MSMQ Transport and receive a synchronous message back from the external system by the EAI MSMQ Transport.

To send a literal to MSMQ and receive a response

1. Access the Windows Computer Management tool by choosing the Start menu, Programs, Administrative Tools, and then Computer Management.

2. Set up an MSMQ queue to receive messages from the Siebel application, and give the queue an easily identified name, such as fromsiebel.

3. Set up another queue to send messages to the Siebel application, and give the queue an easily identified name, such as tosiebel.

4. Set up a workflow in Siebel Tools to send a message out and receive a message back in response using EAI MSMQ Transport. The workflow should contain the following steps, as shown in the following image:

   1. EAI Siebel Adapter (Query)

   2. EAI XML Converter (PropSet to XML)

   3. EAI MSMQ Transport (Send Receive)

   4. XML Converter (XML to PropSet)

   5. Siebel Adapter (Upsert)

   

   Note: For details on the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.

5. Create the following process properties:

   Name	Data Type	In/Out
   Test Message	Hierarchy	In/Out
   Test XML	Binary	In/Out
   Error Code	String	In/Out
   Error Message	String	In/Out
   Object Id	String	In/Out
   Siebel Operation Object Id	String	In/Out

6. Set up the first step of the workflow after Start to use EAI Siebel Adapter with the Query method to query the information from the Siebel Database using the following input and output arguments:

   Input Argument	Type	Value	Property Name	Property Data Type
   OutputIntObjectName	Literal	Sample Employee	Not applicable	Not applicable
   PrimaryRowId	Process Property	Not applicable	Object Id	String

   Property Name	Type	Output Argument
   Test Message	Output Argument	SiebelMessage

7. Set up the second step to use the EAI XML Converter business service with the IntObjHierToXMLDoc method to convert the data extracted from the Siebel Database to XML format, using the following input and output arguments:

   Input Argument	Type	Property Name	Property Data Type
   SiebelMessage	Process Property	Test Message	Hierarchy

   Property Name	Type	Output Argument
   Test XML	Output Argument	<Value>

8. Set up the third step of the workflow, after Start, to use the EAI MSMQ Transport business service with the SendReceive method to receive the incoming XML message, using the following input and output arguments:

   Input Argument	Type	Value	Property Name	Property Data Type
   <Value>	Process Property	Not applicable	Test XML	Binary
   MsmqPhysicalQueueName	Literal	fromsiebel	Not applicable	Not applicable
   MsmqQueueMachineName	Literal	SiebelServer1 Computer name where the Siebel MSMQ Transport is running.	Not applicable	Not applicable
   MsmqRespQueueMachineName	Literal	SiebelServer2	Not applicable	Not applicable
   MsmqRespQueueName	Literal	tosiebel	Not applicable	Not applicable

   Property Name	Type	Output Argument
   Test XML	Output Argument	<Value>

9. Set up the fourth step to use the EAI XML Converter business service with the XMLDocToIntObjHier method to convert the XML message to a Siebel Message using the following input and output arguments:

   Input Argument	Type	Property Name	Property Data Type
   <Value>	Process Property	Test XML	Binary

   Property Name	Type	Output Argument
   Test Message	Output Argument	SiebelMessage

10. Set up the last step to use the EAI Siebel Adapter with the Upsert method to update the Siebel Database, using the following input argument:

    Input Argument	Type	Property Name	Property Data Type
    SiebelMessage	Process Property	Test Message	Hierarchy

11. Save the workflow and run a test using the Workflow Simulator.

    The output property set must have a message in the Value field. Additionally, the EndOfData argument in the property set must be set to True.

    Note: To test this scenario adequately, you must have a partner application that can accept the message and return a response. The correlation ID of the response message must be set to the message ID of the message originally sent by the Siebel application.

Receiving Inbound Messages with MSMQ Receiver

With the Siebel application as the receiver (inbound messaging), you design a workflow that reads from the queue and converts the XML messages found there into Siebel message format. Then, the EAI Siebel Adapter updates the appropriate tables within the Siebel Database.

Note: MSMQ Receiver must run on the same computer where you have defined the receiving queue.

There are two methods for receiving messages for a Siebel application:

• Receive and Execute Service (ReceiveDispatch)

• Receive, Execute, Send Response (ReceiveDispatchSend)

Receiving and Dispatching MSMQ Messages with MSMQReceiver

The following procedure describes how to set up your system to receive an inbound message from MSMQ by MSMQ Receiver, then perform an action based on that message within the Siebel application.

To receive and dispatch messages using the EAI MSMQ Transport (MSMQ Receiver)

1. Access the Windows Computer Management tool by choosing the Start menu, Programs, Administrative Tools, and then Computer Management.

2. Set up a queue to send messages to the Siebel application:

   1. Name the queue an easily identified name, such as toSiebel.

   2. Create a message in the queue.

   Note: To test this procedure adequately, you must have a partner application that can send a valid message for the Siebel application to the queue.

3. Create a named subsystem for the MSMQ Receiver using the following lines:

   create named subsystem MyMSMQSubsys for subsystem MSMQSubsys with 
   MsmqQueueMachineName=SiebelServer1, MsmqPhysicalQueueName=fromSiebel, 
   MsmqRespQueueMachineName=SiebelServer2, MsmqRespQueueName=toSiebel
   
   create named subsystem SiebelEcho for subsystem EAITransportDataHandlingSubsys 
   with DispatchService="Workflow Process Manager", DispatchMethod=RunProcess, 
   DispatchWorkflowProcess="MyMSMQWorkflow"
   
   start task for comp MSMQRcvr with ReceiverConnectionSubsystem=MyMSMQSubsys, 
   ReceiverDataHandlingSubsystem=SiebelEcho, ReceiverMethodName=ReceiveDispatch
   

   Note: The DispatchService and DispatchMethod parameters are optional.

4. Set up a workflow in Siebel Tools to receive and dispatch a message from MSMQ. The workflow should contain the following steps, as shown in the following image:

   1. XML Converter (XMLto PropSet)

   2. Siebel Adapter (Insert)

   

   Note: For details on the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.

5. Create the following process properties:

   Name	Data Type	In/Out
   Test Message	Hierarchy	In/Out
   Test XML	Binary	In/Out
   Error Code	String	In/Out
   Error Message	String	In/Out
   Object Id	String	In/Out
   Siebel Operation Object Id	String	In/Out

6. Set up the first step of the workflow after Start to use the EAI XML Converter business service with the XMLDocToIntObjHier method to convert the XML message to a Siebel Message using the following input and output arguments:

   Input Argument	Type	Property Name	Property Data Type
   <Value>	Process Property	Test XML	Binary

   Property Name	Type	Output Argument
   Test Message	Output Argument	SiebelMessage

7. Set up the second step to use the EAI Siebel Adapter with the Upsert method to update the Siebel Database, using the following input arguments:

   Input Argument	Type	Property Name	Property Data Type
   SiebelMessage	Process Property	Test Message	Hierarchy

   Note: In order to test this scenario adequately, you must have a partner application that can send a valid message for the Siebel application to the queue.

8. Save the workflow.

Receiving, Dispatching, and Sending MSMQ Messages with MSMQ Receiver

The following procedure shows you how to set up your system to receive an inbound message from MSMQ by MSMQ Receiver, perform an action within a Siebel application based on that message, and then send a synchronous response back to the external system.

To receive, dispatch, and send messages using the EAI MSMQ Transport (MSMQ Receiver)

1. Access the Windows Computer Management tool by choosing the Start menu, Programs, Administrative Tools, and then Computer Management.

2. Set up an MSMQ queue to receive messages from the Siebel application.

   Give the queue an easily identified name, such as fromSiebel.

3. Set up another queue to send messages to the Siebel application.

   1. Name the queue an easily identified name, such as toSiebel.

   2. Create a message in the queue.

   Note: To test this procedure adequately, you must have a partner application that can send a valid message for the Siebel application to the queue.

4. Create a named subsystem for the MSMQ Receiver using the following lines:

   create named subsystem MyMSMQSubsys for subsystem MSMQSubsys with 
   MsmqQueueMachineName=SiebelServer1, MsmqPhysicalQueueName=fromSiebel, 
   MsmqRespQueueMachineName=SiebelServer2, MsmqRespQueueName=toSiebel
   
   create named subsystem SiebelEcho for subsystem EAITransportDataHandlingSubsys 
   with DispatchService="Workflow Process Manager", DispatchMethod=RunProcess, 
   DispatchWorkflowProcess="MyMSMQWorkflow"
   
   start task for comp MSMQRcvr with ReceiverConnectionSubsystem=MyMSMQSubsys, 
   ReceiverDataHandlingSubsystem=SiebelEcho, 
   ReceiverMethodName=ReceiveDispatchSend
   

   Note: The DispatchService and DispatchMethod parameters are optional.

5. Set up a workflow in Siebel Tools to receive and dispatch a message from MSMQ. The workflow should contain the following steps, as shown in the following image:

   1. XML Converter (XMLto PropSet)

   2. Siebel Adapter (Upsert)

   

   Note: For details on the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.

6. Create the following process properties:

   Name	Data Type	In/Out	Value
   Test Message	Hierarchy	In/Out	Not applicable
   Test XML	Binary	In/Out	Test Message from Siebel Server
   Error Code	String	In/Out	Not applicable
   Error Message	String	In/Out	Not applicable
   Object Id	String	In/Out	Not applicable
   Siebel Operation Object Id	String	In/Out	Not applicable

7. Set up the first step of the workflow after Start to use the EAI XML Converter business service with the XMLDocToIntObjHier method to convert the XML message to a Siebel Message using the following input and output arguments:

   Input Argument	Type	Property Name	Property Data Type
   <Value>	Process Property	Test XML	Binary

   Property Name	Type	Output Argument
   Test Message	Output Argument	SiebelMessage

8. Set up the second step to use the EAI Siebel Adapter with the Upsert method to update the Siebel Database, using the following input arguments:

   Input Argument	Type	Property Name	Property Data Type
   SiebelMessage	Process Property	Test Message	Hierarchy

   Note: To test this scenario adequately, you must have a partner application that can send a valid message for the Siebel application to the queue.

9. Save the workflow.

   After running the workflow, confirm that the message is removed from the queue using the MSMQ Explorer. In this example, the Siebel Database is updated with the message in the fromSiebel queue. Also, a response message is in the queue specified by the MSMQRespQueueName and MSMQRespQueueMachineName arguments.