The new Queues feature was implemented in 4.2 to maintain multiple queue types and multiple messaging protocols. A queue serves as a gateway to handle inbound and outbound messaging with external sources/destinations, including EAI platforms and web servers.
Note: Continue to the section "Implementing Messaging Framework" for information on setting up a Messaging Framework.
For reference, the following terms are defined:
- Queue - a WebSphere Product Center construct serving as a receiving and transmission point for messages. A script supports each Queue.
- Message - an XML document provided by UCCnet, EAI platform, data pool, or other message source
With the new queue feature, messages can be used as part of a process, in that when jobs are imported or exported, status messages can be sent to all required parties.
Accessing the Queue Console
Use the menu path Collaboration Manager > Queues > Queue Console, the Queue Console displays.
View Queue Details
To view the details of a Queue click on the Queue Name and the Queue Detail screen appears. The following information is provided:
- Queue Name
- Description
- Protocol
- Script
View Message in Queue
The Queue Console has a column called Messages with a hyperlink to the number of messages that have been received by a queue. Click on the number of messages to view the contents of the message.
Search for message in a Queue
1. To search for a message in a queue, use the menu path Collaboration Manager > Queues > Message Console. The Queue Messages Search screen appears.
2. Select a value for the following fields
- Arrival Date From
- Arrival Date To
3. Click Search and the results appear in the Queue Messages table below.
Creating a Queue
1. Use the menu path Collaboration Manager > Queues > New Queue
2. Enter the required information:
Queue Name: Enter a name for the queue
Description: Enter a description for the queue
Protocol: Select from the list of messaging protocols that will be used to tie the external source to/from the queue.
Script: Select from a list of pre-written scripts that can be run to route messages to/from the queue. A typical message for destinations/sources include:
- A workflow collaboration area, which is supported by an in or out script in the workflow step
- A catalog that is supported by a pre-processing, post-processing, or post-save script
The implementation of WebSphere Product Center's messaging framework allows for integration with the following target EAI platforms:
- IBM WBI
- SeeBeyond
- Tibco
- WebMethods
The platform of choice should provide a reliable transport mechanism and a consistent interface for programs to communicate with each other across different systems or platforms.
WebSphere Product Center's messaging framework was designed to support the following process:
- Receiving a message containing an item set, including providing acknowledgement messages upon receipt
- Sending a message containing an item set, including receiving acknowledgement messages after the transmission
WebSphere Product Center ships with the ability to parse and create XML documents, and to send messages to, and collect messages from an EAI platform queue. A message is defined as an XML document provided by an external source. All this functionality is accessible to the WebSphere Product Center scripting engine. To enable interaction between WebSphere Product Center and the EAI platform adapter, it is necessary to install scripts that take advantage of this functionality.
WebSphere Product Center supports queues, which are a construct for serving as a receiving and transmission point for messaging. The WebSphere Product Center queue serves as a gateway to handle inbound and outbound messaging with external sources/destinations and each queue is supported by WebSphere Product Center Scripting Operations.
A queue provides the following functionality:
Enables setting up a message transmission protocol to tie the external message source to/from the queue and provides the following message transmission protocols:
- MQ
- JMS Point-to-Point
- JMS Publish and Subscribe
- HTTP
- HTTP/S
Runs a script to route messages to/from the queue. Typical message destinations/sources include -
- A workflow collaboration area -Supported by an in or out script in a workflow step
- A catalog - Supported by a pre-processing, post-processing, or post-save script
The following list depicts the framework for the messaging functionality:
- An external source sends a message to the EAI Platform. The matter in which this is handled will vary depending on the external source and has no effect on how WebSphere Product Center will retrieve the message.
- The setup of the EAI platform should include an inbound and outbound queue. This setup is done by a third party and the only information WebSphere Product Center needs to know in order to retrieve and send messages, is the identification of the queues that will be accessed by WebSphere Product Center.
- As files are placed into the EAI platform queue, a corresponding queue setup on WebSphere Product Center is able to retrieve the message via a supported protocol (MQ, HTTP/s, or JMS).
- Using WebSphere Product Center Scripts, the message of the body is parsed to obtain the message type, message ID, and message source. This information is routed to a target WebSphere Product Center catalog that has been created to contain all messages.
- The events that occur in D are tracked using a workflow and when the message has been recorded successfully, an event triggers the Acknowledgement Workflow to check out the new record from the Message Catalog into the collaboration area setup.
- The Acknowledgement Workflow sends an acknowledgement message to the message source for confirmation. When this is done, the Acknowledgement Workflow checks in the message back into the catalog.
In order for this process to function, a messaging framework must be built.
Building a messaging framework
The following process outlines a suggested method of integrating an EAI platform framework. This process may be customized based on specific requirements.
Receiving a message
This section describes the process of receiving a message containing an item set, including providing acknowledgement messages upon receipt. The two processes, Setup and Runtime support the process of receiving a message. The process is generic and applicable to most purposes.
Setup
1. A technical business process analyst creates the following:
2. A technical business process analyst builds an inbound Queue containing a script. The script supports three functions - message receipt, message body parsing, and routing.
Message Receipt
The message receipt section of the script supports the following functionality:
- Obtains message from source via a supported protocol - including MQ, HTTP/S, or JMS
- Parses message body to obtain message type, message ID, message source
- Creates record in Message Catalog containing message type, message ID, sender ID, and datetime
- Triggers event to Acknowledgement Workflow. See below for the Acknowledgment Workflow functionality.
Message Body Parsing
The message body parsing section of the script supports the following functionality:
- Includes as parameters the source-to-destination map name and the target catalog name
- Parses the message body per the source-to-destination map name and the target catalog name to render an item set
Message Routing
The routing section of the script supports the following functionality:
Adds/modifies/deletes items in the item set from the target catalog
- A technical business process analyst sets up an Acknowledgement Workflow for sending a receipt acknowledgement message. The workflow has the following functionality:
- Checks out new record from Message Catalog into a collaboration area in a step in the Acknowledgement Workflow.
- A next step in the Acknowledgement Workflow sends an acknowledgement message to the message source containing the message ID, sender ID, datetime, and any required commands by the message source (e.g.: Received).
- A next step in the Acknowledgement Workflow checks in the message catalog record.
Runtime
Once the setup has been properly configured, the following runtime events should occur.
1. Queue receives message via message receipt section of queue script
2. Message receipt section of queue script parses message body to obtain message type, message ID, and sender ID
3. Message receipt section of queue script creates record in Message Catalog containing message type, message ID, sender ID, and datetime
4. Message receipt section of queue script checks out new record from Message Catalog into a collaboration area in a step in the Acknowledgement Workflow.
5. A next step in the Acknowledgement Workflow sends an acknowledgement message to the message source containing the message ID, sender ID, datetime, and any required commands by the message source (e.g.: Received).
6. A next step in the Acknowledgement Workflow checks in the message catalog record.
7. Message body parsing section of queue script parses the message body (using a new script operation cited below) per the map name and the target catalog name to render an item set
8. Routing section of queue script adds/modifies/deletes items in the item set from the target catalog using existing script operations for catalog adds/modifies/deletes
Create WebSphere Product Center inbound/outbound queue
WebSphere Product Center inbound and outbound queues are created using the Queue Console. Before any queue is created, a Trigger script must be created from the Scripts Console. The trigger scripts appear in the drop-down Trigger Script Path field of the New Queue screen.
1. In the Queue Console, click New.
2. In the Queue Detail screen, enter a queue name, description; select a protocol and a trigger script path. The trigger script is created in the Scripts Console of type "Message Queue Processor".
3. Click Save.
WebSphere Product Center script operations provide a flexible way to write WebSphere Product Center script applications with defining capabilities in the arguments of each script operations. The following script operations identified in this section are used to support the messaging feature supported by WebSphere Product Center using MQ or JMS. These methods allow the import and export of messages from an external queue.
Note: The scripting operations listed in this section are subject to change. Refer to the Script Sandbox for the most up-to-date script operations.
MQ Scripting Operations
When creating a script application, the script operation mqGetQueueMgr returns a handler to MQQueueManager, with that handle, multiple MQ operations can be made before calling mqDisconnect to release the handle.
mqGetQueueMgr
- Prototype: MQQueueManager mqGetQueueMgr(String hostname, String port, String channel, String queueMgrName)
- Description: Creates and returns a new MQ queue manager with the given properties.
mqDisconnect
- void MQQueueManager::mqDisconnect()
- Disconnects from the given queue manager.
mqSendTextMsg
- Prototype: MQMessage MQQueueManager::mqSendTextMsg(String msgText, String queueName, String queueOpenOptions, String messagePutOptions)
- Description: Sends a message provided in the String msgText over queueName. Returns the MQMessage
Note: If trying to send a reply to a given message using mqSendReply, an error will return if the mqSendTextMsg is used. To avoid this, use mqSendTextMsgWithReply
mqSendTextMsgWithReply
- Prototype: MQMessage MQQueueManager::mqSendTextMsgWithReply(String msgText, String queueName, String replyQueueName, String queueOpenOptions, String messagePutOptions)
- Description: Sends a message provided in the String msgText over queueName. The reply queue is specified. Returns the MQMessage object.
mqGetTextFromMsg
- Prototype: String mqGetTextFromMsg(MQMessage mqMessage)
- Description: Returns a string containing the entire content of a MQMessage, including headers.
mqGetReceivedMsg
- Prototype: MQMessage MQQueueManager::mqGetReceivedMsg(String queueName, String queueOpenOptions, String messageGetOptions)
- Description: Receives a message from queueName. Returns the message, as a MQMessage, or null.
Note: When messages are retrieved, they are removed from the queue. Unless specifying a message ID, the first message in the queue is obtained.
mqSendReply
- Prototype: MQMessage MQQueueManager::mqSendReply(MQMessage receivedMsg, String msgText, String passedInQueueOpenOptions, String passedInMessagePutOptions)
- Description: Sends a reply to the given message, without indicating success or failure.
mqSendReplyWithStatus
- Prototype: MQMessage MQQueueManager::mqSendReplyWithStatus(MQMessage receivedMsg, String msgText, String status, String passedInQueueOpenOptions, String passedInMessagePutOptions)
- Description: Sends a reply to the given message, setting the feedback field to indicate the given status. Status must be one of the following (in upper or lower case): SUCCESS, FAIL, VALCHANGE, VALDUPES, MULTIPLE_HITS, FAIL_RETRIEVE_BY_CONTENT, BO_DOES_NOT_EXIST, UNABLE_TO_LOGIN, APP_RESPONSE_TIMEOUT, NONE.
Note: Only one status value can be used.
mqGetXMLMessageContent
- Prototype: String mqGetXMLMessageContent(String orgXmlMsg)
- Description: Discards any garbage at the beginning of the input string to get a XML document. More precisely, behaves as follows: If the input string is of the form A + B, where B is a valid XML document and A is any (possibly empty) string, this operation returns B. Otherwise, returns null.
Note: Use this method to pares incoming messages.
mqGetResponseToMsg
- Prototype: MQMessage MQQueueManager::mqGetResponseToMsg(MQMessage outgoingMessage, String queueOptions, String messageOptions)
- Description: Gets the response to the given message from the given queue.
mqGetMessageDiagnostics
- Prototype: String mqGetMessageDiagnostics(MQMessage message)
- Description: Returns a string containing diagnostic information about the given message.
mqGetMessageId
- Prototype: String MQMessage::mqGetMessageId()
- Description: Returns the ID of the given message as a String containing a hexadecimal number.
mqGetReceivedMsgByMessageID
- Prototype: MQMessage MQQueueManager::mqGetReceivedMsgByMessageID(String queueName, String messageId, String passedInQueueOpenOptions, String passedInMessageGetOptions)
- Description: Finds the message in the given queue with given message ID. The ID is passed in a a String containing a hexadecimal number. Returns null if there is no such message in the given queue.
JMS Script Operations
When creating a script application, the script operation jmsGetConnectionFactory returns a handler to QueueConnectionFactory, with that handle, multiple JMS operations can be made before calling jmsDisconnect to release the handle.
jmsGetContext
- Prototype: Context jmsGetContext(String url, String jndiFactory)
- Description: Creates a JMS context.
jmsGetConnectionFactory
- Prototype: QueueConnectionFactory Context::jmsGetConnectionFactory(String jmsFactory)
- Description: Creates and returns a jms connection factory with the specified context.
jmsGetMQConnectionFactory
- Prototype: QueueConnectionFactory jmsGetMQConnectionFactory(String mqQueueManager, String mqHostname, String mqChannel, Integer mqPort)
- Description: Creates and returns a JMS connection factory for communicating with MQ queues. Note that you do not need a Context to get an MQ connection factory whereas you need a Context for connecting to other JMS queues.
jmsGetQueueByName
- Prototype: javax.jms.Queue jmsGetQueueByName(Context ctx, String name)
- Description: Returns a javax.jms.Queue object from the given JNDI Name and Context.
jmsGetQueueConnection
- Prototype: QueueConnection QueueConnectionFactory::jmsGetQueueConnection()
- Description: Returns a JMS queue connection from the given connection factory.
jmsGetQueueSession
- Prototype: QueueSession QueueConnection::jmsGetQueueSession()
- Description: Returns a JMS queue connection from the given connection factory.
jmsDisconnect
- Prototype: void QueueSession::jmsDisconnect(QueueConnection qcon)
- Description: Disconnects from the given queue manager.
jmsCreateTextMsg
- Prototype: Message QueueSession::jmsCreateTextMsg(String msgText)
- Description: Creates a new JMS TextMessage using QueueSession information with the text provided.
jmsSendMsg
- Prototype: Message QueueSession::jmsSendMsg(Message msg, String queueName[, HashMap properties, Message messageToReplyTo])
- Description: Sends a message MSG over queue with name queueName and returns MSG or null. If a MESSAGETOREPLYTO is provided, the reply to queue and message id are read from it. PROPERTIES is a map from string keys to string values. There are three special keys "WPC_REPLY_TO_QUEUE", "WPC_COPY_CORRELATION_ID_BYTES", and "WPC_COPY_CORRELATION_ID". If WPC_REPLY_TO_QUEUE is provided, then it overrides the QUEUENAME or replyto queue in MESSAGETOREPLYTO provided. replyto queue in MESSAGETOREPLYTO overrides QUEUENAME. "WPC_COPY_CORRELATION_ID" and "WPC_COPY_CORRELATION_ID_BYTES" copy over correlation id from MESSAGETOREPLYTO to MSG. Both can be provided. Their values need to be boolean (as opposed to strings - as described above)
jmsReceiveMsgFromQueue
- Prototype: JMSMessage QueueSession::jmsReceiveMsgFromQueue(javax.jms.Queue queue, Integer timeout[, String messageSelector, JMSMessage messageToReceiveReplyFor])
- Description: Receives a JMS Message. Times out after TIMEOUT milliseconds. If INBOUNDQUEUE is not null, looks on that queue. If INBOUNDQUEUE is null, and MESSAGETORECEIVEREPLYFOR is not null, looks on the queue defined in the Reply-To field of MESSAGETORECEIVEREPLYFOR. If INBOUNDQUEUE is null and MESSAGETORECEIVEREPLYFOR is null, throws an AustinException. We now know which queue will be used. If MESSAGESELECTOR and MESSAGETORECEIVEREPLYFOR are both null, selects the first message from that queue. Otherwise selects the first message from the queue (if any) fulfilling all of the conditions defined by MESSAGESELECTOR and MESSAGETORECEIVEREPLYFOR. If MESSAGETORECEIVEREPLYFOR is not null, rejects any message not having a correlation ID equal to MESSAGETORECEIVEREPLYFOR's message ID. If MESSAGESELECTOR is not null, rejects any message not fulfilling the condition defined in messageSelector. If no appropriate message is found, returns null.
jmsGetTextFromMsg
- Prototype: String Message::jmsGetTextFromMsg()
- Description: Returns a string containing the entire content of a JMS message, including headers.
jmsGetMessageID
- Prototype: String Message::getJMSMessageID()
- Description: Returns a string containing the JMS message id.
jmsGetMessageCorrelationID
- Prototype: String Message::getJMSMessageCorrelationID()
- Description: Returns a string containing Correlation Id for the JMS message.
jmsGetMessageProperties
- Prototype: HashMap Message::getJMSMessageProperties()
- Description: Returns a hashmap from string property names to string values for those priorities.
jmsSendMsgToQueue
- Prototype: JMSMessage QueueSession::jmsSendMsgToQueue(JMSMessage msg, javax.jms.Queue outboundQueue [, HashMap properties, JMSMessage messageToReplyTo,])
- Description: Sends message MSG and returns MSG or null. The message is sent to the queue specified by OUTBOUNDQUEUE, unless OUTBOUNDQUEUE is null. If OUTBOUNDQUEUE is null, MSG is sent to the reply-to queue of MESSAGETOREPLYTO, if MESSAGETOREPLYTO is provided. If OUTBOUNDQUEUE is null and MESSAGETOREPLYTO is not provided, throws an AustinException. If MESSAGETOREPLYTO is provided, the message id is read from it. PROPERTIES is a map from string keys to string values. There is one special (non-JMS) key: WPC_INCOMING_REPLY_QUEUE. WPC_INCOMING_REPLY_QUEUE indicates a javax.jms.Queue object to which an external application should send replies to this message.
jmsSetMessageText
- Prototype: void Message::setJMSMessageText(String msgText)
- Description: Sets the provided text for the JMS TextMessage. Only JMS TextMessage type is supported.
Creating a new web service
Use the menu path: Collaboration Manager > Web Services > New Web Service. The "Web Service Detail" screen appears.
Enter the appropriate information into the following fields:
Web Service Name Enter the name of the web service. This name becomes part of the URL of the SOAP service. It must not contain any white space. For example, Web Service Description Enter a description for the web service. Protocol The protocol used for the web service. Currently, SOAP over HTTP is the only supported protocol. The default value is “SOAP_HTTP”. URL Provides the URL where the service may be accessed. This field is automatically populated after the web service has been saved.
WSDL URL The URL where the WSDL for the web service may be accessed. This field is automatically populated after the web service has been saved. WSDL Enter WSDL for this service. A WSDL document is a description of the interface, URL and protocol of the service in XML format. You must enter this document manually, but we provide a sample WSDL document below. You must enter valid XML for the web service to save successfully. Implementation script Enter a Trigo script that implements this service. The incoming parameters for the service are available in the array variable "soapParams". The return value for the service must be a String, and can be written to the "out" writer variable. To return a SOAP fault, write the fault code to the "soapFaultCode" writer variable and write the fault message to the "soapFaultMsg" writer variable. A sample implementation script is provided below. Store requests? If this is checked, Trigo will store the parameters of all incoming requests in the docstore. They will be available from the Transaction Console. Store replies? If this is checked, Trigo will store the content of all responses in the docstore. They will be available from the Transaction Console. Deployed If this is checked, the service will be deployed. Otherwise this service will not be available. A sample implementation script and WSDL document
The following design of the sample implementation script and WSDL document checks the number of parameters of the incoming SOAP request. If there are exactly four parameters, it returns a string listing those parameters. If there are more or less than four parameters, it throws a SOAP fault.
Implementation Script
nParams = soapParams.size();if (nParams != 4){
soapFaultCode.writeln("WRONG_NUM_PARAMS");
soapFaultMsg.writeln("Wrong number of parameters. This service requires 4. You have " + nParams + " parameters.");}
else{
out.writeln("Success.");
for (i = 0; i < nParams; i++)
{
out.writeln("Parameter " + (i + 1) + " is " + soapParams[i]);
}
}
WSDL
<?xml version="1.0" encoding="UTF-8"?><wsdl:definitions targetNamespace="http://my.trigo-instance.com/soap/services/CheckParams"xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:apachesoap="http://xml.apache.org/xml-soap"
xmlns:impl="http://my.trigo-instance.com/soap/services/CheckParams"
xmlns:intf="http://my.trigo-instance.com/soap/services/CheckParams"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<wsdl:message name="invokeRequest">
<wsdl:part name="param1" type="xsd:string"/>
<wsdl:part name="param2" type="xsd:string"/>
<wsdl:part name="param3" type="xsd:string"/>
<wsdl:part name="param4" type="xsd:string"/>
</wsdl:message>
<wsdl:message name="invokeResponse">
<wsdl:part name="invokeReturn" type="xsd:string"/>
</wsdl:message>
<wsdl:portType name="CheckParams">
<wsdl:operation name="invoke" parameterOrder="param1 param2 param3 param4">
<wsdl:input message="intf:invokeRequest" name="invokeRequest"/>
<wsdl:output message="intf:invokeResponse" name="invokeResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="CheckParamsSoapBinding" type="intf:CheckParams">
<wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="invoke">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="invokeRequest">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://DefaultNamespace"
use="encoded"/>
</wsdl:input>
<wsdl:output name="invokeResponse">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://my.trigo-instance.com/soap/services/CheckParams"
use="encoded"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="CheckParamsService">
<wsdl:port binding="intf:CheckParamsSoapBinding"
name="CheckParams">
<wsdlsoap:address location="http://my.trigo-instance.com/soap/services/CheckParams"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>