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:
Install WebSphere Commerce, Version 5.4, with Fix Pack 6 or later, or install WebSphere Commerce, Version 5.5, with Fix Pack 4 or later. 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.
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
You can use this adapter with an existing WebSphere Commerce published store, or you can create a new store.
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 Express installations. You may be using any of the following topologies:
WebSphere Commerce and IBM WebSphere InterChange Server Express and the adapter are all installed on the same machine
WebSphere Commerce is installed on one machine, and IBM WebSphere InterChange ServerExpress and the connector are installed on another machine. A different queue manager is used on each machine.
WebSphere Commerce is installed on one machine, and IBM WebSphere InterChange Server Express and the connector are installed on another machine. The same queue manager is used to manage the queues on both machines.
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:
WebSphere Commerce requires that this queue exist. However, the adapter does not make use of it in this solution.
WebSphere Commerce requires that this queue exist. However, the adapter does not make use of it in this solution.
For receiving messages sent from InterChange Server Express to WebSphere Commerce.
For sending messages from WebSphere Commerce to InterChange Server Express.
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.
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.
If a message is successfully parsed but does not correspond to any business object supported by the adapter, it is stored here.
If a message is not successfully converted to a business object and sent to the InterChange Server Express, it is stored here.
Stores messages that cannot be successfully processed by WebSphere Commerce.
Used only in configurations that are set up for synchronous data exchange.
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 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 WebSphere 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, as described in Configuring WebSphere Application Server JMS settings for WAS 4.x
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 for WAS 4.x
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 for WAS 4.x
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 for WAS 4.x
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 for WAS 4.x
If you are using the adapter in an OS/400 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
If you are using WebSphere Business Integration Server Express Console, create the queues as follows:
The user profile must have access to the WebSphere MQ queue, QWBIDFT.QUEUE.MANAGER, created during the install of the Server Express component.
Notepad opens to the edit file, mq_temp.tst.
DEFINE QL (WC_MQCONN.IN_PROGRESS)
DESCR (WBI Adapter In Progress Queue)
DEFINE QL (WC_MQCONN.ERROR)
DESCR (WBI Adapter Error Queue)
DEFINE QL (WC_MQCONN.ARCHIVE)
DESCR (WBI Adapter Archive Queue)
DEFINE QL (WC_MQCONN.REPLY)
DESCR (WBI Adapter Reply-To Queue)
DEFINE QL (WC_MQCONN.UNSUBSCRIBED)
DESCR (WBI Adapter UnSubscribed Queue)
DEFINE QL (WCS_Serial_Inbound)
DESCR (WebSphere Commerce MQ Adapter JMS Serial Inbound Queue)
DEFINE QL (WCS_Outbound)
DESCR (WebSphere Commerce MQ Adapter JMS Outbound Queue)
DEFINE QL (WCS_Parallel_Inbound)
DESCR (WebSphere Commerce MQ Adapter JMS Parallel Inbound Queue)
DEFINE QL (WCS_Error)
DESCR (WebSphere Commerce MQ Adapter JMS Error Queue)
DEFINE QL (WCS_Inbound)
DESCR (WebSphere Commerce MQ Adapter JMS Inbound Queue)
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:
where serverName is the InterChange Server Express instance (the default for OS/400 is QWBIDFT)
In this topology, WebSphere Commerce is installed on one machine and IBM WebSphere InterChange 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.
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. This queue is created as a remote queue definition, pointing
to ICS_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
|
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:
This completes the configuration tasks for the WebSphere Commerce machine.
Perform the following configuration tasks on the InterChange Server Express machine:
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.
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:
WebSphere Commerce requires that this queue exist. However, the adapter does not make use of it in this solution.
For sending messages from InterChange Server Express to WebSphere Commerce.
For receiving messages sent from WebSphere Commerce to InterChange Server Express.
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.
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.
If a message is successfully parsed but does not correspond to any business object supported by the adapter, it is stored here.
If a message is not successfully converted to a business object and sent to InterChange Server Express, it is stored here.
Stores messages that cannot be successfully processed by WebSphere Commerce.
Used only in configurations that are set up for synchronous data exchange.
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.
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
set MQ_JAVA_INSTALL_PATH=MQ_install_path\java
set PATH = WAS_Intall_Path\Java\bin;%PATH%
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
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.
Where JMS_QueueConnection_Factory is the name of the MQQueueConnectionFactory JMS object.
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.
The following syntax defines the JMS Queues:
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 InterChange Server Express. In the default
WebSphere MQ queue setup created by the batch file, this value should be
WCS_Outbound
|
Your_Serial_Inbound_Queue
|
The WebSphere MQ queue created for the serial inbound queue. This is
the queue into which WebSphere Commerce MQ Adapter places messages sent from
InterChange Server Express 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 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 and configuring WebSphere Commerce), the queue manager that you established for InterChange
Server Express 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 MQ application.
To exit the JMSAdmin tool, enter end. This completes your task for configuring the Java Messaging Service with WebSphere Application Server running WebSphere Commerce.
With the introduction of WebSphereCommerce 5.5, Commerce instances are created as a WebSphere Application Server in WAS 5.x. When configuring JMS for 5.x versions of WebSphere Application Server, the JMS settings must be configured through the WAS administrator user interface, and not using the JMSAdministrator tool as described for WAS 4.x versions. Once you are logged into the WAS administrator interface (see your WAS documentation for connecting to the admin interface), use the following general steps to configure JMS.
To configure JMS for WebSphere Application Server in WAS 5.x:
GRTMQMAUT OBJ(*ALL) OBJTYPE(*ALL) USER(<WAS_SubSystem_Name>) AUT(*ALL) MQMNAME(<ICSName>.QUEUE.MANAGER)
For example: GRTMQMAUT OBJ(*ALL) OBJTYPE(*ALL) USER(QEJBSVR) AUT(*ALL) MQMNAME(QWBIDFT.QUEUE.MANAGER)
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:
Configure JMSQueue names and JMS Connection Factory with the values that you are using for the connectionSpec in this instance, as follows:
When you are finished, exit the Configuration Manager.
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:
name= ws.ext.dirs value=MQ_INSTALL_PATH/java/lib
Where MQ_INSTALL_PATH is the path where you installed WebSphere WebSphere MQ.
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 InterChange Server Express. See the WebSphere Commerce Online Help guide for additional instructions if needed.