Sample scenario
1: Sending and receiving business objects
Sample scenario 1 demonstrates how the WBI adapter for
WebSphere MQ can be used to send business objects to and receive
business objects from an application communicating using WebSphere
MQ. This scenario is designed to be simple and show the basic functionality
of the adapter.
Summary
The fictitious scenario involves an application ("ApplicationX")
that can exchange information regarding corporate contacts being
created, updated or deleted.
We create business object "Sample_WebSphereMQ_LegacyContact"
to match the fields defined in messages from ApplicationX. Fortunately,
in this fictitious scenario, ApplicationX sends and receives messages
in a format that is compatible with the Delimited DataHandler provided
with the WBI EDK.
We create the template and collaborations needed to deliver "Sample_MQSeries_LegacyContact" business
objects between the WebSphere MQ connector and the Port connector.
The Port connector is included with every installation of IBM WebSphere
Business Integration products, and as it is comprised of only a
connector definition with no underlying code, it acts as a "dummy" connector
for our collaborations. One can easily change this to another connector
such as JText if they so choose.
Once started, the adapter retrieves contact messages posted by
ApplicationX to its input queue. Using the Delimited DataHandler,
the adapter converts these messages to "Sample_WebSphereMQ_LegacyContact"
business objects and delivers them to the IBM WebSphere Interchange
Server (ICS) broker. Using the Test Connector (also included in
the WBI installation), we simulate the Port connector, retrieve
the business object posted by the adapter, and examine the attributes.
After changing the data, we re-deliver the message to the broker
where it is sent to the adapter, converted to a message, and delivered
to the input queue of ApplicationX.
This fictitious scenario is demonstrated with the adapter configured
for ICS as an integration broker.
Assumptions
Before you can install and run the sample scenario, you
must meet the following requirements:
- You have installed and are experienced with the WebSphere ICS
4.2.x product or later.
- You have installed and are experienced with IBM WebSphere MQ
5.1 or higher.
- You have installed the WebSphere MQ client libraries for Java.
- You have installed the WebSphere Business Integration Adapter
for WebSphere MQ in the WebSphere ICS home directory.
- Your WebSphere MQ queue manager is named "crossworlds.queue.manager" (the
default value during installation). If your queue manager is named otherwise,
substitute your queue manager name whenever this document refers to
"crossworlds.queue.manager".
Installing and configuring the sample scenario
For this test scenario, we show a simple business object
exchange between the WebSphere MQ adapter and VTC, for a InterchangeServer
(ICS) broker type configuration. The following steps describe how
to install and configure the sample scenario.
Note 1:
Whenever %SAMPLE_FOLDER% is mentioned in this document,
it refers to the folder in which you found this document.
Note 2:
Whenever %CROSSWORLDS% is mentioned in this document,
it refers to the folder containing your current WebSphere ICS installation.
All environment variables and file separators are specified in the
Windows NT/2000 format. Please make the appropriate changes if running
on UNIX. (ex. %CROSSWORLDS%\connectors would be ${CROSSWORLDS}/connectors)
- Create queues.
This sample scenario requires that three queues be defined
in your queue manager. To create the necessary queues, type "RUNMQSC crossworlds.queue.manager"
from the command line and issue the following commands:
DEFINE QL('MQCONN.IN')
DEFINE QL('MQCONN.ERROR')
DEFINE QL('LEGACYAPP.IN')
Note 1:
The MO has a default attribute with ASI for OutputQueue=LGACYAPP.IN (in URI format), which the user can change to the appropriate
queue manager name.
Note 2:
LEGACYAPP.IN is the input queue of the application, which is the same
as the output queue of the adapter. It is configured in the default
attribute of the MO.
- Start InterChange Server and System Manager.
Start WebSphere Interchange Server from the shortcut.
Start WebSphere Business Integration System Manager and open the
Component Navigator Perspective. Register and connect your server
as a Server Instance in the Interchange Servers view.
-
Load the WebSphere MQ sample solution.
From the Component Navigator Perspective, create a new
Integration Component Library, and import the repos file named WebSphereMQSample.jar located
in: %CROSSWORLDS%\connectors\WebSphereMQ\samples\WebSphereICS\
- Compile the collaboration templates.
Using WebSphere Business Integration System Manager,
right-click the folder labeled "Collaboration Templates," and then
select "Compile all" from the drop-down list.
- Configure the adapter.
Using WebSphere Business Integration System Manager,
open WebSphere MQ adapter in Connector Designer. If you have not
done so already, configure the adapter as described in the installation
guide according to your system. Additionally, ensure that the adapter
configuration properties match the values listed below.
- Standard Properties:
- Set property "Broker Type" value to "ICS".
- Set property "DeliveryTransport" value to "IDL".
- Connector-Specific Properties:
- Set property "ConfigurationMetaObject" to value "Sample_WebSphereMQ_MO_Config".
- Set property "DataHandlerConfigMO" to value "Sample_WebSphereMQ_MO_DataHandler".
- Set property "DataHandlerMimeType" to value "text/delimited".
- Set property "DataHandlerClassName" to value "com.crossworlds.DataHandlers.text.delimited".
- Set property "ErrorQueue" to value "queue://crossworlds.queue.manager/MQCONN.ERROR".
- Set property "InputQueue" to value "queue://crossworlds.queue.manager/MQCONN.IN".
- Set the "hostname" property to the name of your machine.
- Set the "port" property to 1414.
- Set the "channel" property to CHANNEL1.
- Set property "UnsubscribedQueue" to value "queue://crossworlds.queue.manager/MQCONN.UNSUBSCRIBED".
- Supported business objects:
In order to use business objects, the adapter must first
support them. Using Connector Designer, select the "Supported Business
Objects" tab, select the following business objects from the Business
object name drop-down list, and then check the agent supported check
boxes.
- "Sample_WebSphereMQ_MO_Config"
- "Sample_WebSphereMQ_MO_DataHandler"
- "Sample_WebSphereMQ_LegacyContact"
- Configure the port connector.
Using WebSphere Business Integration System Manager,
open PortConnector in Connector Designer.
- Standard properties:
- Set property 'Broker Type' value to 'ICS'.
- Set property "DeliveryTransport" value to "IDL".
- Supported business objects:
Using Connector Designer, select the "Supported Business
Objects" tab, select the following business objects from the drop-down
list, and then check them as agent supported business objects.
- "Sample_WebSphereMQ_LegacyContact"
Save the Port Connector Configuration File as "PortConnector.cfg"
in the %SAMPLE_FOLDER%.
- Configure the meta objects.
If your WebSphere MQ Queue Manager is not named "crossworlds.queue.manager"
you will need to update the URI in the "default" attribute's "AppSpecificInfo"
field in the Sample_WebSphereMQ_MO_Config Business Object.
Important:
Be sure to save your changes in Connector Configurator.
-
Create a WebSphere MQ user project.
Using WebSphere Business Integration System Manager,
create a new user project. Select all of the components from the
Integration Component Library that was created in Step 3.
- Add and deploy the user project to InterChange Server.
From the Server Instance view, add the user project
created in Step 8 to WebSphere
ICS, and then deploy all of the components from this user project
to InterChange Server.
- Reboot InterChange Server.
Reboot Interchange Server to ensure that all changes
take effect. Use the System Monitor tool to ensure that all of the
Collaboration objects, connector controllers, and maps are in a
green state.
Running the sample scenario
The following steps describe how to run the sample scenario.
- Start the adapter if it is not already running.
- Start the Visual Test Connector (VTC) if it is not already running.
- Simulate a port connector. The following steps describe how
to do this.
- Using the VTC, define a profile for "PortConnector." The following
steps describe how to do this.
- From the VTC menu, select File > Create/Select Profile.
- Select File > New Profile from the Connector Profile
menu.
- Select the Port Connector Configuration File "PortConnector.cfg"
in the %SAMPLE% directory.
- Configure the 'Connector Name' and 'Broker Type' and select
'OK.'
- Select the profile you created, and then select 'OK.'
- Select File > Connect to begin simulating the connector
agent.
- Test consume events.
Using the VTC, create a new instance of business object "Sample_WebSphereMQ_LegacyContact"
by selecting the business object in the 'BoType' drop-down box,
and then selecting 'Create' for the BOInstance. Change the default
values if desired, and send the message.
- Check that a message was delivered.
Using WebSphere MQ Explorer or another similar application,
open queue "queue://crossworlds.queue.manager/LEGACYAPP.IN" to see
if a new contact message with format 'LC_CR' has arrived from the
adapter.
- Test the subscription-delivery.
Note:
this step requires that you have a utility capable
of sending messages to a queue. If none are available, you can set
the adapter's "InputQueue" property equal to "queue://crossworlds.queue.manager/LEGACYAPP.IN"
so that the adapter will poll its own messages (easiest approach).
Once you have a message in the input queue, the adapter
will poll it and attempt to convert into a "Sample_WebSphereMQ_LegacyContact"
business object. The key to having the adapter poll the message
is to ensure that the message format equals the value associated
with the "Sample_WebSphereMQ_LegacyContact" business object in meta
object "Sample_WebSphereMQ_MO_Config". In this scenario, that format
is "LC_CR".
If the adapter identifies the message format as "LC_CR",
it will use the data handler to convert the message to business
object "Sample_WebSphereMQ_LegacyContact" with the verb create. The newly created business object will be subsequently delivered
to the Test Connector.
When you are finished
If you have performed all of the previous steps successfully,
you should have a working sample scenario that enables the WBI Adapter
for WebSphere MQ to retrieve messages and convert them to "Sample_WebSphereMQ_LegacyContact"
business objects, and vice-versa, convert "Sample_WebSphereMQ_LegacyContact"
business object to contact messages.
