Ch 9 Queues and messaging

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:

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.


Queues Console

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:

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

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:


Implementing messaging framework

The implementation of WebSphere Product Center's messaging framework allows for integration with the following target EAI platforms:

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:

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:

Runs a script to route messages to/from the queue. Typical message destinations/sources include -

The following list depicts the framework for the messaging functionality:

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:

Message Body Parsing

The message body parsing section of the script supports the following functionality:

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.


Messaging Script Operations

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

mqDisconnect

mqSendTextMsg

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

mqGetTextFromMsg

mqGetReceivedMsg

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

mqSendReplyWithStatus

Note: Only one status value can be used. 

mqGetXMLMessageContent

Note: Use this method to pares incoming messages.

 mqGetResponseToMsg

mqGetMessageDiagnostics

mqGetMessageId

mqGetReceivedMsgByMessageID

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

jmsGetConnectionFactory

jmsGetMQConnectionFactory

jmsGetQueueByName

jmsGetQueueConnection

jmsGetQueueSession

jmsDisconnect

jmsCreateTextMsg

jmsSendMsg

jmsReceiveMsgFromQueue

jmsGetTextFromMsg

jmsGetMessageID

jmsGetMessageCorrelationID

jmsGetMessageProperties

jmsSendMsgToQueue

jmsSetMessageText


Web Services

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>