How Do Users Migrate WAS Customized Configuration Between Two Environments?

Body

 

Most of the Business Process Manager (BPM) migration scenarios require migrating configuration data from source to target. It doesn't matter if it is for a version-to-version migration or a hardware migration for the same version of the product, how we migrate the configuration data completely and accurately is a very important element for the success of a migration project. As you might know, starting from BPM 8.5.5, BPM uses the command utility BPMConfig -migrate / -export to extract the source configuration data. However, some of the customized WebSphere Application Server (WAS) configuration, like new data sources or JDBC providers, are not able to be exported successfully using these command lines. This article will introduce the use of command line exportWASConfig/importWASConfig to help you solve this issue. Also, we will focus on a typical problem that is caused by these two commands and provide more detailed instruction on how we are supposed to migrate WAS customized configuration data safely.

 

I. Differences of the configuration data exported by BPMConfig –migrate/export and exportWASConfig

When it comes to this topic, the very first question we might want to ask is "Why do we even need an extra command to export or import the WAS configuration data?" The obvious answer is that because the scopes we use with these two commands are different, and the data they export from the source environment is quite distinctive as well.

For BPMConfig -migrate/-export, the following data will be exported accordingly to a specified output directory.

• Cell and deployment environment
• Deployment manager and managed node
• Cluster and cluster member
• Data source and JDBC provider information
• Authentication alias and role mapping
• LDAP
• Deployment environment and Process Portal context root prefix (if set in the current deployment environment)
• Business Process Choreographer customization
• Additional performance tuning configuration properties

The output folder will be like the picture below:

 

 

If you open the files exported and take a close look at them, you will notice that most of the properties generated are predefined BPM properties or default BPM properties that must be input during initial configuration. Very few customized configurations on WAS scope will be exported here.

On the other hand, the command exportWASConfig.py exports the following WAS configurations including data sources, authentication aliases, and JDBC and JMS providers.

• Data sources
• JDBC providers
• JMS providers
• Connection factories
• Activation specifications
• JMS queue and topic specifications
• Namespace bindings
• Authentication aliases
• Secure Sockets Layer (SSL)
• Service integration buses (SIBs) and messaging engines

One point I want highlight here is that if you choose any option like –exportAllDataSource and -exportALLAuthAliases (-exportAllxxx), it will extract all existing data sources or authentication aliases for a particular cell and cluster. That means it does not classify which one is the BPM default and which one is customized by the user.

 

For example, if you run the following command line to export all data sources that exist:

wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportAllDataSources /tmp/exportedDataSources -cell Cell01 -cluster AppCluster

 

The data source output property will be like below (both BPM and customized data sources are extracted)

 

 

Therefore, it directly leads to a very typical issue: overwrite problem. We are going to talk about in next section.

 

II. The most frequent issue caused by exportWASConfig/importWASConfig

The scenario here is that a group of end-users are performing BPM version-to-version migration. Once they used command BPMConfig –migrate to export BPM configuration data, they also ran script exportWASConfig.py to extract all data sources, authentication alias, and JDBC providers because there are a few customized data sources defined within its WAS cell.

Later they completed each migration steps and every BPM component worked as expected. The administrator ran the command importWASConfig to import the customized WAS configurations they exported during migration. However, once the command importWASConfig for all targets was run successfully, the user failed to start any of the servers successfully.

 

We checked the configurations and user’s command line applied to export the WAS configuration settings and noticed that there were two problems existing:

1. The parameter options they used to extract the source WAS configuration are for ALL data sources and authentication aliases as below:
   
   wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportAllDataSources /tmp/exportedDataSources -cell Cell01 -cluster AppCluster
   
   wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportAllJDBCProviders /tmp/exportedJDBCProviders -cell Cell01
   
   wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportAllAuthAliases /tmp/exportedAuthAliases
2. 
   
3. They did not modify the exported objects and properties. So all of the data sources and JDBC providers including both BPM default as well as customized objects were generated in the output folder. Then the command line importWASConfig overwrote the existing BPM predefined properties with the old values extracted from the source environment.

 

When trying to start the server, you will see the error related to database connections or authentications errors that are referring to some old values:

[10/26/16 12:56:32:743 SGT] 00000001 WsServerImpl  E   WSVR0009E: Error occurred during startup

com.ibm.ws.exception.RuntimeError: Failed to create database connection to [jdbc/TeamWorksDB].

Please check ffdc log for detail information, ensure the database server is started, both database connection information and user credential are correct.

            at com.ibm.bpm.migration.database.ValidateDatabaseVersion.verifyStandardDB(ValidateDatabaseVersion.java:400)

            at com.ibm.bpm.migration.database.ValidateDatabaseVersion.verifyStandardDB4SA(ValidateDatabaseVersion.java:332)

            at com.ibm.bpm.migration.database.ValidateDatabaseVersion.start(ValidateDatabaseVersion.java:141)

            at com.ibm.ws.runtime.component.ContainerHelper.startComponents(ContainerHelper.java:540)

 

Therefore, problems like this can be easily identified by comparing the target and source configuration files. If any changes made on the properties file exported by BPMConfig –export, the configuration files captured from target and source should not be different.

 

III. How do we use exportWASConfig/importWASConfig wisely

More importantly, to clearly understand what information is extracted by which command line is the key to successfully migrate configuration objects from source to target. Here is a procedure and also a checklist for users who have extra configuration needs to migrate in addition to the ones exported by BPMConfig –migrate/-export:

1. During migration, if there are any customized configuration data that you need to migrate, you have the following two choices to export your objects:
   1. Use parameter option for individual objects like data source or authentication alias rather than ALL.
      
      Example:
      
      wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportDataSource /tmp/exportedDataSources jdbc/CUSTDB -cell Cell01
      
      wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportAuthAlias CUST_Auth_Alias /tmp/exportedAuthAliases
   2. 
      
   3. If there are a relatively large number of objects that need to be exported, you could use the exportALL option, but please make sure you remove all of the BPM default/predefined objects from the output files. Please refer to the example below.
      
      ** One point to highlight here is to please make sure you remove the BPM objects from both .properties files as well as .obj files.
      
      Example:
      
      wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportAllDataSources /tmp/exportedDataSources -cell Cell01 -cluster AppCluster
      
      wsadmin -conntype NONE -f /tmp/exportWASConfig.py -exportAllAuthAliases /tmp/exportedAuthAliases
      
      
   
    
2. Once the migration steps are performed successfully, verify the BPM components as usual.
3. 
   
4. Take a backup for current target BPM Configurations (command backupConfig.sh/bat) before running command importWASConfig.py.
   
   ** This step is very important because the changes made on these objects will be serialized into BPM WCCM, and it’s irreversible from any mistakes and overwriting.
5. 
   
6. Run the command importWASConfig accordingly to import the exported objects at step #1.
   
   ** When the import script meets the duplicated object in the same BPM scope, there's a prompt message in the command line window to ask whether you want to continue to proceed. See below message for authentication alias and data source:
   
             INFO: Importing J2C authentication with name [BPM_DB_PS_ALIAS].  J2C authentication alias with name BPM_DB_PS_ALIAS already exists.
   
             Would you like to overwrite it?(Y/N)
   
   
             Input the number to select the scope where you want to import this object:10
   
             Data source with JNDI name jdbc/TeamWorksDB already exists. Would you like to overwrite its configuration?(Y/N)
   
   
   Note: In case you missed to delete any BPM predefined objects, you will be reminded at this step to skip the step or go back to modify your exported properties.

 

In summary, most of the critical configuration objects will be covered by command BPMConfig –export/-migrate. In case you need to use our utility exportWASConfig/importWASConfig, please make sure that you are clear about the configuration objects you try to export and import, and always take a good backup before making any changes.

 

IV. Useful links:

• Command line Utility for exportWASConfig
• Command line Utility for importWASConfig