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:

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)

  1. 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.
  2. 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.
  3. 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\
  4. 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.
  5. 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.
  6. Configure the port connector.

    Using WebSphere Business Integration System Manager, open PortConnector in Connector Designer.
  7. 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.
  8. 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.
  9. 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.
  10. 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.

  1. Start the adapter if it is not already running.
  2. Start the Visual Test Connector (VTC) if it is not already running.
  3. Simulate a port connector. The following steps describe how to do this.
    1. Using the VTC, define a profile for "PortConnector." The following steps describe how to do this.
      1. From the VTC menu, select File > Create/Select Profile.
      2. Select File > New Profile from the Connector Profile menu.
      3. Select the Port Connector Configuration File "PortConnector.cfg" in the %SAMPLE% directory.
      4. Configure the 'Connector Name' and 'Broker Type' and select 'OK.'
      5. Select the profile you created, and then select 'OK.'
    2. Select File > Connect to begin simulating the connector agent.
  4. 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.
  5. 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.
  6. 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.

Copyright IBM Corporation 2003, 2005. All Rights Reserved.