Migration of WebSphere Partner Gateway to 6.1.1 version

Content

Migration is performed in the following sequence:

1. Preparation for Migration
2. Migration of the database
3. Deployment of WebSphere Partner Gateway 6.1.1 on WebSphere Application Server or WebSphere Application Server ND
4. Migration of WebSphere Partner Gateway components properties files
5. Migration of Security Configurations
6. Migration of user Exits
7. Converting existing metadata file to BDO attributes (applicable only for migration from WBI)
8. Multiple Internal Partner related changes
9. Admin tasks in WAS-ND in the context of WebSphere Partner Gateway Setting Trace and Debug Levels

1. Preparing for Migration of WebSphere Partner Gateway 6.1.1

A. Software Prerequisites

• AIX operating environment
• For 32 bit: AIX 5L, Version 5.2, 5.3.
• For 64 bit: AIX 5L, Version 5.2, 5.3.

• HP-UX operating environment
• For 64-bit Itanium: HP-UX 11i, Version 2,3.

• Linux for Intel (x86) operating environment
• Red Hat Enterprise Linux, Version 3, 4, and 5.
• SUSE Linux Enterprise Server, Version 9 and 10.

• Linux for Intel (x86-64) operating environment
• Red Hat Enterprise Linux AS , Version 5.
• SUSE Linux Enterprise Server, Version 10.

• Linux for POWER operating environment

32 bit (one of the following):

• Red Hat Enterprise Linux AS, Version 4 and Version 5.
• SUSE Linux Enterprise Server, Version 10.

64 bit (one of the following):

• Red Hat Enterprise Linux AS, Version 4 and Version 5.
• Linux Enterprise Server, Version 10.

• Sun Solaris Operating Environment
• For 32 bit: Sun Solaris (SPARC) Operating Environment, Version 9 or 10.

• Windows operating environment

32 bit (one of the following):

• Windows Server 2003 Standard.
• Windows Server 2003 Enterprise.

64 bit (one of the following):

• Windows Server 2003 Standard x64 Edition.
• Windows Server 2003 Enterprise x64 Edition.

B. Other software requirements

• Application server (one of the following)
• WebSphere Application Server Network Deployment, Version 6.1 (included with terms and conditions limitations for use with WebSphere Partner Gateway only).
• WebSphere Application Server, Version 6.1 (optional).
• Web browser for console access (one of the following).
• Microsoft Internet Explorer, Version 6.0 with Service Pack (SP) 1 or later.
• Mozilla, Version 1.4 or 1.7.

• A Simple Mail Transfer Protocol (SMTP)-based e-mail relay server for e-mail alert delivery and SMTP message delivery

• Databases (one of the following):
• DB2 Universal Database Enterprise Server Edition, Version 8.2 Fixpack 7.
• DB2 Enterprise Server Edition, Version 9.1 Fixpack 3 (included with terms and conditions limitations for use with WebSphere Partner Gateway only).
• Oracle Enterprise Edition 9i, Release 2 (9.2.0.8).
• Oracle Enterprise Edition 10g, Release 1 (10.1.0.5).
• Oracle Enterprise Edition 10g, Release 2 (10.2.0.3).

B. Hardware Prerequisites

• AIX operating environment
• Processor: System i or System p model at 600 MHz or faster.
• Main memory: 2 GB minimum.
• Hard disk: Minimum 1.3 GB (1350 MB) available disk space for installation.

• HP-UX on Itanium operating environment
• Processor: Intel Itanium 2 processor.
• Main memory: 2 GB minimum.
• Hard disk: Minimum 1 GB (1080 MB) available disk space for installation.

• Linux for Intel (x86 / x86-64) operating environment
• Processor: Intel Pentium® at 2 GHz or faster.
• Main memory: 2 GB minimum.
• Hard disk: Minimum 1.3 GB (1350 MB) available disk space for installation.

• Linux for POWER operating environment

Linux for IBM System i™ operating environment

• Processor: System i models that support logical partitioning (LPAR) (64-bit kernel support only) with a minimum of 450 commercial processing workload (CPW) in the Linux partition.
• Main memory: 2 GB minimum.
• Hard disk: Minimum 1.3 GB (1350 MB) available disk space for installation.

Linux for IBM System p™ operating environment

• Processor: System p models that support Linux (64-bit kernel support only).
• Main memory: 2 GB minimum.
• Hard disk: Minimum 1.3 GB (1350 MB) free disk space for installation.

• Sun Solaris Operating Environment
• Processor: Sun SPARC at 750 MHz or faster.
• Main memory: 2 GB minimum.
• Hard disk: Minimum 1.3 GB (1350 MB) available disk space for installation.

• Windows operating environment
• Processor: Intel Pentium(x86 / x86-64) at 2 GHz or faster.
• Main memory: 2 GB minimum.
• Hard disk: Minimum 1.3 GB (1350 MB) available disk space for installation.

C. What has changed in WebSphere Partner Gateway 6.1.1?

• Topology Changes

• Simple Mode

The simple deployment topology is the simplest topology and is also referred to as a simple mode installation. A simple mode installation consists of a single server running all three WebSphere Partner Gateway components (Receiver, Community Console, and Document Manager). Although the recommended approach is to install the database on a separate dedicated server, you can install the Relational Management system on the same server.

This deployment should be used for:
- Low production volumes.
- Sales demonstrations.
- Development.

• Simple Distributed Topology

The simple distributed topology consists of one Application server containing the Receiver, Community Console, and the Document Manager components. A WebSphere Application Server Network Deployment environment is used to allow one or more additional computers to be installed that also has all three components on one Application server. A separate messaging cluster is used to allow internal communication between the components.

• Fully Distributed Topology

The fully distributed topology is similar to the simple distributed topology, except that each component (Receiver, Community Console, and the Document Manager) resides on a different application server. The fully distributed topology provides backward compatibility and is used when more sophisticated deployments are required. The distributed topology consists of one or more dedicated servers for each component.

• Topology mapping from 4.2.2/6.0 to 6.1.1

- WBIC/WebSphere Partner Gateway on single server Simple Mode

- WBIC/WebSphere Partner Gateway on 2 servers each with DocMgr, Receiver and Console
Simple Dist Mode

- WBIC/WebSphere Partner Gateway components deployed on multiple servers Full Dist Mode

• What needs to be saved before migration?

• Database

It is advisable to take a database backup so that in case of failure during migration of the database, you can always restore the database and start the migration process again.

• Common File System

To roll back in case of any migration failures, it is recommended to have a backup of the common file system.

• Property Files

WebSphere Partner Gateway does not use property files from the 6.1.0 release, but instead allow users to configure values for properties using the WebSphere Partner Gateway administration console. So while migrating from WBIC or WebSphere Partner Gateway 6.0, we need to backup the following property files:

From Console : bcg_console.properties
From Receiver : bcg_receiver.properties
From Document Mgr : bcg.properties,
ediparms.properties (WebSphere Partner Gateway only)
ediconfig.properties (WebSphere Partner Gateway only)

Later in this document we will discuss how to migrate these properties into WebSphere Partner Gateway 6.1.x repository.

• User Exits

Backup of all user exit jars must to be moved manually to the target system. Later in this document we will go through detailed steps on migrating user exits.


2. Migration of Database

A. Uninstall DB Loader of previous version
In order to install the latest version of the DB loader the older version needs to be uninstalled, but while uninstalling the previous DB loader, choose not to drop the database. We need this database so that we can migrate to WebSphere Partner Gateway 6.1.1 level.

B. Install 6.1.1 DB Loader
Before we migrate from WBI-C or WebSphere Partner Gateway to WebSphere Partner Gateway 6.1.1, DB loader of WebSphere Partner Gateway 6.1.1 should be installed, but do not select the option to run SQL files. This will extract the necessary scripts to the folders, but will not run them. We need them for migration.

C. Migrating the database
Refer to the information provided in Chapter 4 of Installation Guide for detailed instructions on migration of database.

3. Deployment of WebSphere Partner Gateway 6.1.1

A. Migrating from 6.1.0.x to 6.1.1

1. Uninstall MAS server and database (where applicable)
2. Uninstall WebSphere Partner Gateway components. Backup the common file system before starting the uninstall process. All the components of WebSphere Partner Gateway server should be uninstalled. WAS and the Deployment manager can be retained
3. Update WAS ND level to Fix Pack 13 and JAVA to SR6, and apply the required iFix before installing WebSphere Partner Gateway components (please refer to detailed system requirements for more details)
4. Install MAS server and also the database.
5. Install WebSphere Partner Gateway 6.1.1 in the same mode in which WebSphere Partner Gateway 6.1.0.x was installed.

Note: If you have overridden the system-properties using WAS runtime properties, create them manually. This information will be lost once you uninstall WebSphere Partner Gateway 6.1.0.x.


B. Migrating from 4.2.2 / 6.0.x

WBIC and WebSphere Partner Gateway 6.0 uses embedded version of WAS for receiver, document manager, and console. From WebSphere Partner Gateway 6.1.x.x we use Websphere Application Server 6.1 ND. So there are no migration steps for HUB (Receiver, Document Manager and console). The new hub installation is as follows:

1. Uninstall the existing WBIC to WebSphere Partner Gateway 6.0.x.x installation
2. Install Websphere Application server ND 6.1 and apply necessary fix packs.
3. For the Common File System, before uninstalling this, we need to take a back up of this folder so that we do not loose information in case of any errors while uninstalling.
4. Based on your topology plan, install HUB in one of the following modes:

• Simple
• Simple Distributed
• Fully Distributed modes.

4. Migration of properties files (applicable for 6.0 and 4.2.2)
Move the contents of the properties files saved earlier into the database by running the utility {INSTALL_DIR}/bcghub/bin/bcgPropMigrate. The Input parameters are:

• Schema owner
• Schema owner password v
• Directory, where saved properties files are located.

For Example: BcgPropMigrate db2admin password C:\PropertiesFilesDirectory

5. Migration of security settings
Certificates and Keys that are used for SSL (outbound), Digital Signature, and Encryption are migrated when the database gets migrated to the new level (6.1.1), but the certificates and keys that were used to enable SSL for incoming message have to be manually migrated. For more details, refer to Migrating of WebSphere Partner Gateway Security Configurations section, Chapter 4 of the Installation Guide.

6. Migration of user Exits
The configuration of user exits gets carried forward when the database is migrated. Users do not have to repeat the steps to configure user exits, but the class files have to be migrated manually.
There are no changes made to WebSphere Partner Gateway API that are exposed for user exits. The recompilation must be done using the supported version of java and the new version of WebSphere Partner Gateway jars.
Once they are compiled, the new jars has to be placed under
<WPG611_Install Dir>\bcghub-<mode>\<component>\lib\userexits\classes.

7. Converting existing metadata file to BDO attributes (applicable only for migration from WBI)
Move existing WebSphere Partner Gateway document metadata files (*.vmd) by:

• Creating a directory migration/lib under {INSTALL_DIR}/bcghub.
• Copying the saved common jar file to directory {INSTALL_DIR}/bcghub/migration/lib.
• Running the utility {INSTALL_DIR}/bcghub/bin/bcgBDOMigrate.

Input Parameters are
Schema owner userid and Schema owner password

8. Multiple Internal Partner related changes
In the prior version of Websphere Partner gateway or Websphere Business Integration Connect, we had only one internal partner (A.K.A Community Manager) per instance. In WebSphere Partner Gateway 6.1.1 we support the creation of more than one internal partner (A.K.A Community Manager). To work around the constraint of having just one internal partner, you can define internal partners as external partners although WebSphere Partner Gateway / WBI-C are designed to work for internal to external and vice versa.

In case the existing instance uses such a step up, this may not work as desired when migrating to WebSphere Partner Gateway 6.1.1, as we do not allow Private keys to be associated to external partner. To resolve this inconsistent state, after migrating to WebSphere Partner Gateway 6.1.1, we recommend the changing of partner types, that is, the internal partners that were named external must be changed to internal.

To do so, follow the steps mentioned below:

1. Log into WebSphere Partner Gateway administrative console as the Hub administrator.
2. Navigate to System Administration.
3. In the Common Properties page, click Edit icon.
4. Change the value of property bcg.allow.partner.type.edit to True (by default, the value is False).
5. Navigate to Account Admin > Profiles > Partners.
6. Search for the partners to be changed to Internal from External partner.
7. Edit the partner’s profile and change the partner type.
8. Save the changes.
9. Repeat steps from 6 to 8 for all the required partners.
10. Repeat steps from 2 to 8 to change the partner from External to Internal.
11. Navigate to Common Properties page and change the property value of bcg.allow.partner.type.edit to False. This is to prevent the editing of partner type in future.

WARNING: It is recommended to use this feature only during migration; we strongly recommend keeping the value of bcg.allow.partner.type.edit as FALSE after completion of migration steps. Keeping it to TRUE post migration completion might lead WebSphere Partner Gateway to an irreversible inconsistent state.

9. Admin tasks in WAS-ND in the context of WebSphere Partner Gateway
Setting Trace and Debug Levels
Following are the steps to follow to set Log and Trace Level for WebSphere Partner Gateway applications:

1. Log into WAS administration console.
2. In the left frame, expand Troubleshooting.
3. Click Log And Trace. The list of servers are displayed (the list may vary based on the installation mode).
4. Click the server for which you want to modify the trace level.
5. Click Change Log detail level.
6. Click RuntimeTab.
7. In the displayed tree, select com.ibm.bcg.* to enable trace for all components. In case you just want to trace a specific Package / Class, expand this tree till you reach the package or Class.
8. Now, click the selected package / class.
9. Select Message and Trace Levels.
10. Select the appropriate level of trace you want, finest being the max trace setting.
11. Select the check box on the top to Save runtime changes to configuration as well. (This is to avoid restart of server).
12. Click OK. On the top of the window, you will see Messages
13. Click Save to save the changes directly to master configuration.

Controlling # of threads (e.g. BPE)
To control the number of threads that will be used for MAIN_INBOUND, SIGNAL_IN, and SYNC_IN queues in WBIC and WebSphere Partner Gateway 6.0, we used the following properties in bcg.properties: ,

• bcg.in_thread_count.main
• bcg.in_thread_count.signal
• bcg.in_thread_count.synchronous

Although this may get migrated while migrating the properties file contents to system properties, this is not used in WebSphere Partner Gateway 6.1.x.x.

To control the number of threads, use the following steps:

1. Log into WAS administration console
2. In the left frame, expand Resources
3. Expand JMS
4. Select Activation Specifications

• jms.bcg.as.BPEMainAS is used for the main_InboundQ
• jms.bcg.as.BPESignalAS is used for signal_InboundQ
• jms.bcg.as.BPESyncAS is used for sync_InboundQ

For example, in bcg.properties, take the MAIN_INBOUNDQ and assume the value of bcg.in_thread_count.main as 4. To make the corresponding setting in 6.1.1, follow the below steps:

1. Log into WAS administration console
2. In the left frame, expand Resources
3. Expand JMS
4. Select Activation Specifications
5. Click jms.bcg.as.BPEMainAS
6. Change the value in Maximum concurrent endpoints to the value set for property of bcg.in_thread_count.main.
7. Click OK and save the configuration changes to the master settings.

Configuring JMS Gateway/Receiver with external MQ through JNDI

Create JMS Queue Connection Factory

Under WAS Admin console trace links (Resources->JMS->Queue Connection factory), create JMS queue connection factory (Importantly select WebSphere MQ option for external MQ).

• For gateway configuration, create under the scope of document manager server/node (node scope would be helpful in case of clusters. For simple mode create under server scope)
• For receiver configuration, create under the scope of receiver server/node (node scope would be helpful in case of clusters. For simple mode create under server scope)

Figure-1




Figure-2

• In the configuration screen (Figure 3), provide appropriate queue manager, host, port, channel, and transport type values. The default values of the optional fields in the below screen are left as is.

Figure-3

Create JMS Queue

Under WAS Admin console trace links (Resources->JMS->Queue), create JMS queue (Importantly select WebSphere MQ option for external MQ).

• For gateway configuration, create under the scope of document manager server/node (node scope would be helpful in case of clusters. For simple mode create under server scope).
• For receiver configuration, create under the scope of receiver server/node (node scope would be helpful in case of clusters. For simple mode create under server scope)

Figure-4


Figure-5

• In Figure 6, provide appropriate queue manager, queue, host, port, and channel values. The other fields that are beyond the scope of the screen are optional other than name and JNDI name.

Figure-6

Configure JMS Gateway on WebSphere Partner Gateway

Create a JMS based gateway with the artifacts created in the above sections - queue connection factory and queue JMS objects. The following screen (Figure-7) shows the mandatory values to be entered.



Figure-7


In the Address attribute substitute appropriate hostname and port from the WebSphere Application Server under which Queue Connection Factory or Queue objects were created.

corbaloc:iiop:<hostname>:<bootstrapportnumber>

First two segments signify the protocol used for the communication between Client (WebSphere Partner Gateway) look up on the Server (WebSphere Application Server).

Third segment represents the hostname or ipaddress of the machine where WebSphere Application Server resides, that is, under which Queue Connection factory and Queue objects were created.

Fourth segment represents the bootstrap port number of the Server where Queue Connection Factory and Queue objects are bound. To get the above bootstrap port number, login to WAS (WebSphere Application Server) admin console and check for the items marked in Figure-8.



Figure-8

Three more attributes to be understood for gateway creation are:

• JMS Factory Name

JMS Factory Name is the JNDI name provided for JMS Queue Connection Factory.

• JMS Queue Name

JMS Queue Name is the JNDI name provided for JMS Queue.

• JMS JNDI Factory Name

JMS JNDI Factory Name is the factory that is used for the JNDI communication. As we use WebSphere Application Server, it is better to use com.ibm.websphere.naming.WsnInitialContextFactory.

Configuring JMS Receiver on WebSphere Partner Gateway

Create a JMS based receiver with above artifacts - queue connection factory and queue JMS objects. Figure 9 shows the mandatory values to be entered. Refer to gateway level attributes explanation for receiver as well.

Figure-9

Creating a service integration bus

1. Create and name a bus.

1. Click Service integration > Buses.
2. Click New and provide a bus name. For example, SIBUS.
3. Click Apply.
4. Save the configuration by clicking Save in the Messages window that appear. This message is to confirm that you want to apply the changes to the master configuration.
5. Click Save again when asked to update the master repository with your changes.

2. Add bus members to the bus.

1. Click on the name of the newly created bus.
2. In the Additional Properties pane, click Bus members.
3. Click Add and select the server or cluster to be added.
4. Click Next and then click Finish to confirm the addition of the new bus members.
5. Save the configuration by clicking Save in the Messages window that appears. This message is to confirm that you want to apply the changes to the master configuration.
6. Click Save again when asked to update the master repository with your changes.

3. Create a destination queue:

1. In the WebSphere Application Server default Console, click System Integration (left panel).
2. Click Buses < SIBUS (or the name of the bus created in step 1).
3. In the Additional Properties pane, click Destinations.
4. Click New.
5. Select the Queue radio button for the destination type and click next.
6. Enter an Identifier. For example, Request. This will create the destination queue on the bus.

4. Save the configuration by clicking Save in the Messages window that appear. This message is to confirm that you want to apply the changes to the master configuration.

5. Click Save again when asked to update the master repository with your changes.



Creating a JMS Queue Connection Factory

For point-to-point messaging, a JMS queue connection factory is used to create connections to the associated JMS provider of JMS queues.

1. Create a Queue Connection Factory by populating the Name and JNDI name fields using the following syntax:
2. Name: SIBUS.JMSTargetQCF
3. JNDI name: SIBUS/JMSTargetQCF

Where SIBUS is the name of the bus created in the previous steps.

2. Select the bus. For example, SIBUS.

3. In the resulting window, click on the Queue Connection Factory that you just created and enter the Provider endpoints as: IPaddress/Name:7276:BootstrapBasicMessaging, where IPaddress is the IP address or the name of the machine on which WebSphere Application Server is running. It is expected that the Message Engine for this service integration bus is running on this machine. 7276 is the port number specified for SIB_ENDPOINT_ADDRESS of WebSphere instance. If your Messaging Engine is running on the system with the IP address 9.26.234.100 and SIB_ENDPOINT_ADDRESS for the WebSphere instance running on this server is specified as 7276, specify Provider endpoints will be 9.26.234.100:7276:BootstrapBasicMessaging

4. Save the configuration by clicking Save in the Messages window that appear. This message is to confirm that you want to apply the changes to the master configuration.

5. Click Save again when asked to update the master repository with your changes.

Creating a JMS queue

A JMS queue is used as a destination for point-to-point messaging. Using the WebSphere Administrative Console:
1. Expand the Resources menu and click JMS Providers > Default messaging.
2. Click JMS queues in the Destinations section of the resulting page.
3. Click New.
4. Enter a queue name for both Name and JNDI name fields using the following syntax:

1. Name: Request.JMSTarget
2. JNDI name: Request/JMSTarget

5. Select the Bus Name (For example, SIBUS) and Queue name from the drop-down lists.
6. Click OK.
7. Save the configuration by clicking Save in the Messages window that appear. This message is to confirm that you want to apply the changes to the master configuration.
8. Click Save again when asked to update the master repository with your changes.