Prerequisite tasks

This section describes the installation and configuration tasks you must perform for WebSphere Commerce and other software before you can install and run the adapter.

These tasks are:

  1. Install and configure WebSphere Commerce
  2. Install and configure the Commerce Enhancement Pack
  3. Publish a WebSphere Commerce store
  4. Create and configure WebSphere MQ queues
  5. Configure JMS ConnectionSpec within WebSphere Commerce
  6. Update WebSphere Commerce JVM Settings
  7. Enable WebSphere Commerce Adapter

Installing and configuring WebSphere Commerce

Install WebSphere Commerce version 5.4, Business Edition, with Fixpack 2, WebSphere Commerce version 5.5 with Fixpack 4, or WebSphere Commerce version 5.6. Refer to the documentation that comes with the product for the installation steps and the post-install configuration. The WebSphere Commerce messaging system is equipped to handle the messages to interact with back-end systems.

You must update the CMDREG table, which is the command registry table in your WebSphere Commerce database, to use the XML message format.

Installing the Commerce enhancement pack

To install the Commerce Enhancement Pack, download the Commerce Enhancement Pack driver from the following URL and follow the instructions in the readme.txt file:
http://www.ibm.com/software/commerce/epacks

Publishing a store

You can use this adapter with an existing WebSphere Commerce published store, or you can create a new store.

Configuring WebSphere MQ queues

The WebSphere MQ queue configuration required for using the adapter depends in part upon the topology of your WebSphere Commerce and InterChange Server Express installations. You may be using any of the following topologies:

Single-machine topology

In this topology, WebSphere Commerce, InterChange Server Express and the adapter for WebSphere Commerce are all installed on a single machine. A single queue manager handles all the WebSphere MQ queues used in the solution. It is recommended that you use the queue manager that you set up when you installed InterChange Server Express.

This topology requires queues that perform the following roles:

All of the above queues are local in the single machine topology. If you create the queues manually, you choose the names that you assign for them; if you use the batch file provided with this solution (described below), the batch file will create the queues with pre-assigned names.

If you are using the adapter in a Windows environment, you can use a batch file to generate queues that are appropriate for a single machine topology. The file is installed with your product package in the \Connector\WebSphereCommerce\Utilities subdirectory within the root directory you used for your InterChange Server Express installation. To create the queues using the batch file, run the file ConfigureWebSphereCommerceAdapter.bat, as follows:

From the command prompt, enter:

ConfigureWebSphereCommerceAdapter
<InterChangeServerName>.queue.manager

Where, <InterChangeServerName> is the name of your InterChange Server Express.

This will create a queue manager named InterChange ServerName.queue.manager and it will create the required WebSphere MQ queues. The names of the created queues, as created by the batch file, are as follows:

WC_MQCONN.IN_PROGRESS In Progress queue for the adapter.

WC_MQCONN.ERROR InterChange Server Express Error Queue for the adapter.

WC_MQCONN.ARCHIVE Archive Queue for the adapter.

WC_MQCONN.REPLY Reply-To Queue for the adapter.

WC_MQCONN.UNSUBSCRIBED UnSubscribed Queue for the adapter.

WCS_Serial_Inbound Serial Inbound Queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce.

WCS_Outbound Outbound queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce.

WCS_Error Error queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce.

WCS_Inbound Inbound queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce.

Generating queues for an OS/400 environment

If you are using the queues in an i5/OS environment, you must create the queues.

Depending on your installation, there are 2 ways to create queues:

Using WebSphere Business Integration Server Express Console to create queues:

  1. Start the WebSphere Business Integration Server Express Console application.
  2. Select Start > Programs > IBM WebSphere Business Integration Express > Toolset Express > Administrative > Console.
  3. Enter the OS/400 system name or IP address and enter a user profile password.

    The user profile must have access to the WebSphere MQ queue, serverName.QUEUE.MANAGER, created during the installation of the Server Express component.

  4. From the InterChange Servers and Connector Agents' tab of the console, right-click the serverName which you wish to create the queues for, and select Configure Queue Manager. This will open a text window to allow you to define the queues for the server's queue manager.

    Notepad opens to the edit file, mq_temp.tst.

  5. Add the following lines to the top of the file:
  6. Click the Create Queues button from the window. The console creates the queues on OS/400 for you in the Queue Manager specified for the InterChange Server Express instance.
  7. Save and close Notepad.

    The console creates the queues on OS/400 for you.

Using the command line to create queues

If you are using CL commands to create queues, from the command prompt, enter:

  1. STRMQM MQMNAME (serverName.QUEUE.MANAGER)
  2. CRTMQMQ QNAME (WC_MQCONN.IN_PROGRESS) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WBI Adapter In Progress Queue)
  3. CRTMQMQ QNAME (WC_MQCONN.ERROR) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WBI Adapter Error Queue)
  4. CRTMQMQ NAME (WC_MQCONN.ARCHIVE) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WBI Adapter Archive Queue)
  5. CRTMQMQ QNAME (WC_MQCONN.REPLY) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WBI Adapter Reply-To Queue)
  6. CRTMQMQ QNAME (WC_MQCONN.UNSUBSCRIBED) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WBI Adapter Unsubscribed Queue)
  7. CRTMQMQ QNAME (WCS_Serial_Inbound) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WebSphere Commerce MQ Adapter JMS Serial Inbound Queue)
  8. CRTMQMQ QNAME (WCS_Outbound) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WebSphere Commerce MQ Adapter JMS Outbound Queue)
  9. CRTMQMQ QNAME (WCS_Parallel_Inbound) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WebSphere Commerce MQ Adapter JMS Parallel Inbound Queue)
  10. CRTMQMQ QNAME (WCS_Error) QTYPE (*LCL) MQMNAME (serverName.QUEUE.MANAGER) TEXT (WebSphere Commerce MQ Adapter JMS Error Queue)
  11. CRTMQMQ QNAME (WCS_Inbound) QTYPE (*LCL) MQMQNAME (serverName.QUEUE.MANAGER) TEXT (WebSphere Commerce MQ Adapter JMS Inbound Queue)

    where the serverName is the InterChange Server Express instance (the default for OS/400 is QWBIDFT44).

Two-machine, two-Queue Manager topology

In this topology, WebSphere Commerce is installed on one machine and WebSphere Integration Server Express and the adapter for WebSphere Commerce are installed on another machine.

WebSphere MQ must be installed on each machine, and each installation uses a different queue manager. These are the queues you create on each machine.

Note:
In this table, the queue names indicate the role of each queue, but you can establish different queue names, as long as you synchronize the queue names with JMS queue names used on your WebSphere Commerce system.
In the table, the prefix WCS indicates a queue that is created on the machine on which the WebSphere Commerce system is installed, and that is managed by a queue manager that resides on that machine.
The prefix ICS indicates a queue that is created on the machine on which ICS and the connector are installed, and that is managed by a queue manager that resides on that machine.

Queues on the WebSphere Commerce machine

Queues on the InterChange Server Express machine

WCS_Outbound Queue

For sending messages from WebSphere Commerce to InterChange Server Express machine. This queue is created as a remote queue definition, pointing to InterChange Server Express _Inbound on the InterChange Server Express machine as the remote queue.

ICS_Inbound queue

For receiving messages sent from WebSphere Commerce to InterChange Server Express.

WCS_Serial Inbound queue

For receiving messages sent from InterChange Server Express to WebSphere Commerce.

ICS_Outbound queue

For sending messages from InterChange Server Express to WebSphere Commerce. This queue is created as a remote queue definition, pointing to WCS_Serial Inbound on the WebSphere Commerce machine as the remote queue

To InterChange Server Express

Transmission queue from WebSphere Commerce system to InterChange Server Express.

To WebSphere Commerce

Transmission queue from InterChange Server Express to WebSphere Commerce system.

WCS_Error_queue

Stores messages that cannot be successfully processed by WebSphere Commerce.

ICS_Error_queue

If a message is not successfully converted to a business object, it is stored here.

WCS_Parallel Inbound

The adapter does not make use of a parallel inbound queue.

ICS_InProgress queue

The original versions of valid messages sent from WebSphere Commerce to InterChange Server Express are stored here until the adapter completes processing; when processing is completed, the original message is moved to the local Archive queue.

ICS_Archive_queue

When a message has been fully processed by the adapter and sent to InterChange Server Express from WebSphere Commerce, the original version of the message is stored here.

ICS_Unsubscribed_queue

If a message is successfully converted to a business object but does not correspond to any business object supported by the adapter, it is stored here.

To enable communication between the two systems, use channels and transmission queues.

Channels that perform the following roles must be created on each machine for this topology.

Channels On the WebSphere Commerce machine Channels On the InterChange Server Express machine

Sender_WCS

Sender_ICS

Receiver_ICS

Receiver_WCS

Creating the channels

In the following instructions, specific server and queue manager names are specified so that they correlate the different machines and queues. Channels are used to make sure that the correct queues refer to each other; the "local" versions of the queues are used to hold the actual information.

Perform the following configuration tasks on the WebSphere Commerce machine:

Note:
The channel names used here are examples only.
  1. Create two channels in the WebSphere Commerce system using WebSphere MQ Explorer. One sender channel named 'WCS' and one receiver channel named 'ICS'.
  2. Create a local queue, for example, using the name 'ToICSSystem'.
  3. Set the ToICSSystem queue as the transmission queue.
  4. Set the following properties for the WCS_Outbound queue.
    1. Remote queue name ICS_InboundRemote queue manager name ICS_server_name.queue.manager. For example, ICS.queue.manager.
    2. Set the transmission queue name property to 'ToICSSystem' as created in step 2.
  5. To configure the sender channel do the following:
    1. Specify the connection name with the IP address and the port, for example, 9.182.12.235(1414). Where, 9.182.12.235 is the IP address of the machine where InterChange Server Express is running and 1414 is the default listener port.
    2. Specify the transmission queue name as 'ToICSSystem'.

This completes the configuration tasks for the WebSphere Commerce machine.

Perform the following configuration tasks on the InterChange Server Express machine:

  1. Create two channels using WebSphere MQ Explorer: One sender channel named 'ICS' and one receiver channel named 'WCS'.
    Note:
    The name of the sender channel in the WebSphere business integration system must be identical to the name of the receiver channel in WebSphere Commerce. The name of the receiver channel in the WebSphere business integration system must be identical to the name of the sender channel in WebSphere Commerce.
  2. Create a new local queue, for example 'ToWCSSystem'. Set the ToWCSSystem queue as the transmission queue.
  3. Create a remote definition queue in the WebSphere business integration system. This remote definition queue must be used in the connector component as the output queue. Set the following properties:
    1. Remote queue name WCS_SerialInbound
    2. Remote queue manager name <wcssytems_Q_manager_name>. For example, QM_wcsfvt3.
    3. Set the transmission queue name property to 'ToWCSSystem'.
  4. To configure the sender channel do the following:
    1. Specify the connection name with the IP address and the port, for example, 9.182.12.18(1414). Where, 9.182.12.18 is the IP address of the machine where WebSphere Commerce is running and 1414 is the default listener port.
    2. Specify the transmission queue name as 'TOWCSSystem'.

After you finish configuring the WebSphere MQ queues and channels on both the WebSphere Commerce machine and the InterChange Server Express machine, start the receiver channel and then the sender channel.

Two-machine, one-queue manager topology

In this topology, WebSphere Commerce is installed on one machine and InterChange Server Express and the adapter for WebSphere Commerce are installed on another machine. Only one instance of WebSphere MQ is running, and the queues used by both machines are managed by a single queue manager. This scenario uses only local queues.

This topology requires queues that perform the following roles:

Configuring JMS ConnectionSpec within WebSphere Commerce Version 5.4

Note:
The JMSQueue names and JMS connection factory must be the same as the values entered in the connectionSpec section of Commerce Configuration Manager, in the instance XML file. You can find the details under the Transports section in the WebSphere Commerce Configuration Manager. Also see the instructions below.

Start the WebSphere Commerce Administration Console. Log in as a Site Administrator, go to the Configuration section and choose the Transport option. Select WebSphere MQ as your transport and change the status to active. Log out from the Administration Console.

The WebSphere Commerce solution requires the creation and use of a "store," as described in the WebSphere Commerce Installation Guide. When you have completed publishing the store as described in "Publishing a Sample Store" section of that guide, log into the Administration Console, this time as a Store Administrator, and select the store you are using. In the Configuration section, add MQ Transport to the store. An entry for this is made in the STORETRANS table.

To enable the messaging system transport adapter, launch the WebSphere Commerce Configuration Manager and do the following:

  1. Select Host name -> Instance, and then open the Components folder.
  2. Select TransportAdapter.
  3. Select the Enable Component checkbox and click Apply.

Configure JMSQueue names and JMS Connection Factory with the values that you are using for the connectionSpec in this instance, as follows:

  1. Select the Host Name -> Instance
  2. Select Transports, then expand Outbound->JMS
  3. Select the ConnectionSpec
  4. Input the ConnectionFactory name created when configuring the JMS settings for WebSphere Application Server.
  5. Enter the Inbound, Error, and Outbound queue names created above.
  6. Click Apply.
  7. Expand Inbound->JMSInbound CCF Connector-Serial
  8. Select the ConnectionSpec
  9. Input the ConnectionFactory Name, SerialInbound, Error and Output JMS queues.
  10. Click Apply.
  11. Expand Inbound-JMSInbound CCF Connector-Parallel
  12. Select the ConnectionSpec
  13. Input the ConnectionFactory, ParralelInbound, Error and Output JMS queues.
  14. Click Apply.

Exit the Configuration Manager.

Updating WebSphere Commerce JVM settings

You must update the WebSphere Application Server Version 4.x class path for the instance, adding the additional jar file entries. To do so, open the WebSphere Application Server Advanced Administrative Console and complete the following:

  1. Select the host on which you are running your WebSphere Commerce instance.
  2. Select the WebSphere Administrative Domain.
  3. Select Nodes.
  4. Select your host name.
  5. Select Application Servers.
  6. Select the WebSphere Commerce Server instance_name, where instance_name is the name of your WebSphere Commerce instance.
  7. Go to the JVM settings of the instance.
  8. Select Add a new system property.
  9. Type in the following system property:
    name= ws.ext.dirs value=MQ_INSTALL_PATH/java/lib

    Where MQ_INSTALL_PATH is the path where you installed WebSphere WebSphere MQ.

Enabling WebSphere MQ for the adapter

In WebSphere Commerce, use the configuration option under the Administration console to configure WebSphere Commerce to communicate with the WebSphere MQ queues for outbound and inbound messaging that you are using in your implementation of WebSphere Commerce and InterChange Server Express. See the WebSphere Commerce Online Help guide for additional instructions if needed.

Copyright IBM Corp. 2004, 2005