Prerequisite software and tasks

Before you attempt to install and run the adapter, be sure that you have installed the prerequisite software and performed the prerequisite planning and configuration tasks described in this section.

Integration broker compatibility

The adapter framework that an adapter uses must be compatible with the version of the integration broker (or brokers) with which the adapter is communicating. The 2.3.x version of the Adapter for WebSphere Commerce User Guide is supported on the following adapter framework and integration brokers:

Adapter framework: WebSphere Business Integration Adapter Framework version 2.x

Integration brokers:

Prerequisite software

Important:
Because the adapter has not been internationalized, do not run it against ICS version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will be processed.

Client setup with NT server

See the description in WebSphere MQ Quick Beginnings for NT.

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. Install IBM ICS
  5. Create and configure WebSphere MQ queues
  6. Configure WebSphere Application Server JMS settings
  7. Configure JMS ConnectionSpec within WebSphere Commerce
  8. Update WebSphere Commerce JVM Settings
  9. Enable WebSphere Commerce Adapter

Installing and configuring WebSphere Commerce

Install WebSphere Commerce Version 5.4, Business Edition, with FixPack 2. 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.

Installing IBM WebSphere InterChange Server

The integration solution provided by this adapter requires InterChange Server (ICS) as the integration broker and also requires the XML data handler. The XML data handler is installed to your system when you install the adapter. When you run the installer for the adapter, be sure that the box for XML data handler is also checked.

To install IBM WebSphere InterChange Server, consult the IBM WebSphere InterChange Server System Installation Guide for Windows or for UNIX, for instructions on running the installer utility and for performing other installation tasks. When you run the WebSphere InterChange Server installation utility, it automatically selects and installs ICS and the data handlers.

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 IBM WebSphere InterChange Server installations. You may be using any of the following topologies:

Single-machine topology

In this topology, WebSphere Commerce, ICS 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 ICS.

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 IBM ICS 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 InterChangeServer.

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 ICS 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, as described in Configuring WebSphere application server JMS settings

WCS_Outbound Outbound queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce, as described in Configuring WebSphere application server JMS settings

WCS_Parallel_Inbound Parallel inbound queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce, as described in Configuring WebSphere application server JMS settings

WCS_Error Error queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce, as described in Configuring WebSphere application server JMS settings

WCS_Inbound Inbound queue for WebSphere Commerce. Must match a JMS queue name defined for WebSphere Commerce, as described in Configuring WebSphere application server JMS settings

Two-machine, two-Queue Manager topology

In this topology, WebSphere Commerce is installed on one machine and IBM WebSphere ICS 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 ICS machine

WCS_Outbound Queue

For sending messages from WebSphere Commerce to ICS. This queue is created as a remote queue definition, pointing to ICS_Inbound on the ICS machine as the remote queue.

ICS_Inbound queue

For receiving messages sent from WebSphere Commerce to ICS.

WCS_Serial Inbound queue

For receiving messages sent from ICS to WebSphere Commerce.

ICS_Outbound queue

For sending messages from ICS 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 ICS

Transmission queue from WebSphere Commerce system to ICS.

To WebSphere Commerce

Transmission queue from ICS 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 ICS 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 ICS 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 ICS 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 ICS 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 ICS 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 ICS 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 ICS 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 WebSphere application server JMS settings

You must configure WebSphere Application Server (WAS) to create the Java Messaging Service Connection Factory and JMS queues to work with WebSphere MQ. To do so, perform the following steps.

  1. From the command prompt:
    1. Update your classpath variable by typing the following command on one line:
      set classpath= %classpath%;
       MQ_install_path\java\lib\com.ibm.mqjms.jar;
       MQ_install_path\java\lib\com.ibm.mq.jar;
       MQ_install_path\java\lib\com.ibm.mq.iopp.jar;
       MQ_install_path\java\lib\com.ibm.ibmorb.jar;WAS_install_path\lib\ns.jar
       

      MQ_install_path
      The path in which you installed WebSphere MQ

      WAS_install_path
      The path in which you installed the WebSphere Application Server
    2. Add a new environment variable named MQ_JAVA_INSTALL_PATH by typing the following command:
      set MQ_JAVA_INSTALL_PATH=MQ_install_path\java
       

      MQ_install_path
      The path in which you installed WebSphere MQ
    3. Update the environment to use the JDK (Java Development Kit) that comes with WebSphere Application Server by typing the following command:
      set PATH = WAS_Intall_Path\Java\bin;%PATH%
       

      WAS_install_path
      The path in which you installed the WebSphere Application Server
  2. Ensure that the WebSphere Application Server is running and the correct classpath and environment variablesdefined in Step 1 above are added. Also check to make sure the JDK being used is the one in WAS by executing java -version and checking the version with the one found in WAS_Install_Path\Java\bin.
  3. In the MQ_install_path\java\bin directory, open the JMSAdmin.config file and set the following values:

    INITIAL_CONTEXT_FACTORY=com.ibm.ejs.ns.jndi.CNInitialContextFactory PROVIDER_URL=iiop://localhost:900

    The values above assume that WebSphere Commerce and WebSphere MQ are installed on the same machine.

    SECURITY_AUTHENTICATION=none

  4. Run the JMSAdmin program by providing the JMSAdmin.config file as a command line input:

    CommandPrompt:> JMSAdmin -cfg JMSAdmin.config -t -v

    Executing this command should enable you to lookup the JNDI (Java Naming and Directory Interface) service provided by WebSphere Application Server. You will see an InitCtx> prompt that you can use to run the JMS administration commands.

  5. Register the QueueConnectionFactory and set the coded character set identifier by typing the following commands:

    When you execute the above set of commands, an entry for this queue connection factory is created in the WebSphere Application Server database under the BINDINGBEANTBL table. These objects are registered in the WebSphere Application Server database.

  6. Define the following JMSQueues to map to the names you have established for your WebSphere MQ queues and the WebSphere MQ queue manager you are using. You can customize the JMSqueue names according to your own requirements, but the WebSphere MQ names to which you define them must match exactly, including casing, queue names you have established in WebSphere MQ. If you are using the batch file provided with this adapter for creating the appropriate WebSphere MQ queues for a single-machine topology, be sure to use those generated WebSphere MQ queue names as the values to which you define the JMS queues, as described in the table below.

    The following syntax defines the JMS Queues:

Note:
If you are using a remote queue definition for the outbound queue, as you would in a two-machine, two-queue manager topology, the JMS_Outbound_Queue should not be defined to a local WebSphere MQ queue. If you are using a remote queue definition, the syntax for the outbound queue would be: define q(JMS_Outbound_Queue)qmanager(Your_Queue_Manager_Name)
define q(JMS_Outbound_Queue)qmanager
  (Your_Queue_Manager_Name)
   queue(Your_Outbound_QueueName
define q(JMS_Inbound_Queue)qmanager
  (Your_Queue_Manager_Name)
   queue(Your_Inbound_QueueName)
 
define q(JMS_Parallel_Inbound_Queue)qmanager
   (Your_Queue_Manager_Name)queue
     (Your_Parallel_Inbound_Queue_Name
define q(JMS_Serial_Inbound_Queue)qmanager
   (Your_Queue_Manager_Name)queue
    (Your_Serial_Inbound_Queue_Name
define q(JMS_Error_Queue)qmanager
   (Your_Queue_Manager_Name)
    queue (Your_Error_Queue_Name)
 

Table 6. Defining JMS queue names

Your_Outbound_QueueName

The WebSphere MQ queue created for the outbound queue. By default, this is the queue which the adapter polls to pick up messages from WebSphere Commerce to pass to ICS. In the default WebSphere MQ queue setup created by the batch file, this value should be WCS_Outbound

Your_Serial_Inbound_Queue

The WebSphere WebSphere MQ queue created for the serial inbound queue. This is the queue into which WebSphere Commerce MQ Adapter places messages sent from ICS to Websphere Commerce. In the default WebSphere MQ queue setup created by the batch file, this value should be WCS_Serial_Inbound

Your_Parallel_Inbound_Queue_Name

This is the WebSphere WebSphere MQ queue created for the parallel inbound queue

Your_Error_Queue_Name

The WebSphere MQ queue created for the error queue. This is where WebSphere Commerce MQ Adapter sends messages when it encounters an error with the message. In the default WebSphere MQ queue setup created by the batch file, this value should be WCS_Error

Your_Queue_Manager_Name

The name of the queue manager handling WebSphere MQ queues in your set up for the WebSphere Commerce system. In a typical single machine setup, such as the setup created by the batch file ConfigureAdapterQueues.bat (see Installing the files), the queue manager that you established for ICS would be used to manage the queues for the WebSphere Commerce system as well. For such a setup, the default would be <InterchangeServerName>.queue.manager

After creating the queues, set the following property for the outbound and error queues using the JMSAdmin console. This procedure specifies that JMS is dealing with a native WebSphere WebSphere MQ application.

Type end to exit the JMSAdmin tool. This completes your task for configuring the Java Messaging Service with WebSphere Application Server running WebSphere Commerce.

Configuring JMS ConnectionSpec within WebSphere Commerce

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 WAS. Enter the Inbound, Error and Outbound queue names created above.
  5. Click Apply.
  6. Expand Inbound->JMSInbound CCF Connector-Serial
  7. Select the ConnectionSpec
  8. Input the ConnectionFactory Name, SerialInbound, Error and Output JMS queues.
  9. Click Apply.
  10. Expand Inbound-JMSInbound CCF Connector-Parallel
  11. Select the ConnectionSpec
  12. Input the ConnectionFactory, ParralelInbound, Error and Output JMS queues.
  13. Click Apply.

Exit the Configuration Manager.

Updating WebSphere Commerce JVM settings

You must update the WebSphere Application Server 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.

  10. Restart the WebSphere Application Server service for all the changes to take affect.

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 IBM WebSphere ICS. See the WebSphere Commerce Online Help guide for additional instructions if needed.

Copyright IBM Corp. 1997, 2003