Prerequisite tasks

The following steps must be made to convert the pre-installed WebSphere MQ adapter to a FRONT ARENA adapter.

These tasks are:

  1. Load the following application-specific business object definitions:
  2. Set the connector's standard property, ApplicationName, to the name assigned to the adapter (for example, FrontArenaConnector).
  3. Set the connector's application configuration properties DataHandlerConfigMO, DataHandlerMIMIType, and ConfigurationMetaObject as described in Default adapter configuration properties.
  4. Define the objects imported in step 1 as supported business objects of the adapter (with Agent Support on).
  5. Copy the adapter's message file to the messages subdirectory of the connectors directory of the WebSphere Interchange Server installation.
  6. Copy the adapter's data handler JAR file to the Datahandlers subdirectory of the connectors directory of the WebSphere Interchange Server installation.

Configuring WebSphere MQ queues

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

Single-machine topology

In this topology, FRONT ARENA, InterChange Server, and the Adapter for FRONT ARENA 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.

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 the product package in the \Connector\WebSphereCommerce\Utilities subdirectory within the root directory used for the IBM InterChange Server 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.

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, can be seen in the following table.

Table 7. WebSphere MQ queues

WebSphere MQ queue name Description
WC_MQCONN.IN_PROGRESS The in-progress queue for the adapter.
WC_MQCONN.ERROR The InterChange Server error queue for the adapter.
WC_MQCONN.ARCHIVE The archive queue for the adapter.
WC_MQCONN.REPLY The reply-to queue for the adapter.
MC_MQCONN.UNSUBSCRIBED The unsubscribed queue for the adapter.
WCS_Serial_Inbound The serial inbound queue for FRONT ARENA. This queue name must match a JMS queue name defined for FRONT ARENA, as described in Configuring WebSphere Application Server JMS settings.
WCS_Outbound An outbound queue for FRONT ARENA. This queue name must match a JMS queue name defined for FRONT ARENA, as described in Configuring WebSphere Application Server JMS settings.
WCS_Parallel_Inbound An inbound parallel queue for FRONT ARENA. This queue name must match a JMS queue name defined for FRONT ARENA, as described in Configuring WebSphere Application Server JMS settings.
WCS_Error An error queue for FRONT ARENA. This queue name must match a JMS queue name defined for FRONT ARENA, as described in Configuring WebSphere Application Server JMS settings.
WCS_Inbound An inbound queue for FRONT ARENA. This queue name must match a JMS queue name defined for FRONT ARENA, as described in Configuring WebSphere Application Server JMS settings.

Two-machine, two-Queue Manager topology

In this topology, FRONT ARENA is installed on one machine and IBM WebSphere InterChange Server and the Adapter for FRONT ARENA 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.

InTable 8, 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 FRONT ARENA system.

In the table, the prefix WCS indicates a queue that is created on the machine on which the FRONT ARENA 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 InterChange Server and the connector are installed, and the queue is managed by a queue manager that resides on that machine.

Table 8. FRONT ARENA and InterChange Server queue names

Queues on the FRONT ARENA machine Queues on the InterChange Server machine

WCS_Outbound Queue

For sending messages from FRONT ARENA to InterChange Server. This queue is created as a remote queue definition, pointing to ICS_Inbound on the InterChange Server machine as the remote queue.

ICS_Inbound queue

For receiving messages sent from FRONT ARENA to InterChange Server.

WCS_Serial Inbound queue

For receiving messages sent from InterChange Server to FRONT ARENA.

ICS_Outbound queue

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

To InterChange Server

Transmission queue from FRONT ARENA system to InterChange Server.

To FRONT ARENA

Transmission queue from InterChange Server to the FRONT ARENA system.

WCS_Error_queue

Stores messages that cannot be successfully processed by FRONT ARENA.

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 FRONT ARENA to InterChange Server 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 from FRONT ARENA, the original version of the message is stored here.

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

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

Table 9. Channel roles

Channels On the FRONT ARENA machine Channels On the InterChange Server machine

Sender_WCS

Sender_ICS

Receiver_ICS

Receiver_WCS

Creating the channels

In the following example 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.

FRONT ARENA machine configuration tasks
Note:
The channel names used here are examples only.
  1. Create two channels in the FRONT ARENA 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 is running and 1414 is the default listener port.
    2. Specify the transmission queue name as ToICSSystem.

This completes the configuration tasks for the FRONT ARENA machine.

InterChange Server machine configuration tasks
  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 FRONT ARENA. The name of the receiver channel in the WebSphere business integration system must be identical to the name of the sender channel in FRONT ARENA.
  2. Create a new local queue, for example ToICSSystem. Set the ToICSSystem 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 ToICSSystem.
  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 FRONT ARENA is running and 1414 is the default listener port.
    2. Specify the transmission queue name as ToICSSystem.
  5. Once the WebSphere MQ queues and channels on both the FRONT ARENA machine and the InterChange Server machine are configured:
    1. Start the receiver channel.
    2. Next, start the sender channel.

This completes the configuration tasks for the InterChange Server machine.

Two-machine, one-queue manager topology

In this topology, FRONT ARENA is installed on one machine and InterChange Server and the Adapter for FRONT ARENA 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

To configure the WebSphere Application Server to create the Java Messaging Service Connection Factory and JMS queues to work with WebSphere MQ, 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 variables defined in Step 1 above are added. Also check to make sure the JDK being used is the one in WebSphere Application Server 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 FRONT ARENA and WebSphere MQ are installed on the same machine.

    SECURITY_AUTHENTICATION=none

  4. Run the MJSAdmin 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 JMSQueues 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 10. 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 FRONT ARENA to pass to InterChange Server. 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 the Adapter for FRONT ARENA places messages sent from InterChange Server to FRONT ARENA. 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 the Adapter for FRONT ARENA 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 FRONT ARENA system. In a typical single machine setup, such as the setup created by the batch file ConfigureAdapterQueues.bat, the queue manager that you established for ICS would be used to manage the queues for the FRONT ARENA 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.

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

Configuring the JMS ConnectionSpec within FRONT ARENA

Note:
The JMSAdmin 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 FRONT ARENA Configuration Manager. Also see the instructions below.

Start the FRONT ARENA 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 FRONT ARENA solution requires the creation and use of a "store," as described in the FRONT ARENA 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 FRONT ARENA Configuration Manager and do the following:

  1. Select Host name ->Instance.
  2. Open the Components folder.
  3. Select, TransportAdapter.
  4. Select the Enable Component check box.
  5. 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.
  3. Expand Outbound->JMS.
  4. Select the ConnectionSpec.
  5. Input the ConnectionFactory name created when configuring the JMS settings for WebSphere Application Server.
  6. Enter the Inbound, Error and Outbound queue names created above.
  7. Click Apply.
  8. Expand Inbound->JMSInbound CCF Connector-Serial.
  9. Select the ConnectionSpec.
  10. Input the ConnectionFactory Name, SerialInbound, Error and Output JMS queues.
  11. Click Apply.
  12. Expand Inbound-JMSInbound CCF Connector-Parallel.
  13. Select the ConnectionSpec.
  14. Input the ConnectionFactory, ParallelInbound, Error and Output JMS queues.
  15. Click Apply.

Exit the Configuration Manager.

Updating FRONT ARENA 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 FRONT ARENA instance.
  2. Select the WebSphere Administrative Domain.
  3. Select Nodes.
  4. Select your host name.
  5. Select Application Servers.
  6. Select the FRONT ARENA Server instance_name, where instance_name is the name of your FRONT ARENA 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.

Copyright IBM Corp. 1997, 2004