Troubleshooting
Problem
You are having a migration problem in WebSphere Process Server. You would like to know what documentation you must collect (MustGather) so that the WebSphere Process Server Support team can diagnose your problem. If you gather this documentation before contacting support it will expedite the troubleshooting process, and save you time.
Resolving The Problem
Tab navigation
- Learning more
- Troubleshooting- selected tab,
- Collecting data
Table of contents
- Avoiding problems during migration
- Resolving problems during migration
- Verifying a migrated environment
Avoiding problems during migration
- Review "WebSphere Process Server Version-to-Version Migration Patterns and Best Practices" document and understand the concept and steps to complete the Version-to-Version migration.
- If you are migrating to WebSphere Process Server V6.2, review "Migrating to WebSphere Process Server V6.2" tutorial for understanding the step-by-step procedures to be followed to migrate a sample deployment environment.
- If you are migrating to WebSphere Process Server V7.0, review "Migrating to WebSphere Process Server Version 7" tutorial for understanding the step-by-step procedures to be followed to migrate a sample deployment environment.
- Bad configuration can cause unpredictable results during migration. Check the environment before migrating. Start the deployment manager and all the servers configured in the migration environment and check the SystemOut.log file of each server to make sure there are no errors.
- WebSphere Application Server base level must be at the minimum at V6.0.2 Fix Pack 11 for any cluster migration. The earliest WebSphere Process Server release that supports WebSphere Application Server V6.0.2 Fix Pack 11 level is WebSphere Process Server V6.0.1 Fix Pack 1. If needed, upgrade the environment before attempting to migrate.
- If possible, remove any unnecessary configuration (for example unused test data source, sample applications, unused profiles). This will help to speed-up the upgrade process.
- Back up your previous WebSphere Process Server installation and all the databases. Save the back up until you have fully migrated and tested all your applications.
- After installing the new version of WebSphere Process Server, upgrade the installation with the latest available fix pack before starting the migration utility.
Resolving problems during migration
This section describes the generic steps to follow during cluster migration, location of the logs and general troubleshooting tips. Depending on your topology, the steps may vary:
- There are a number of enhancement and concurrent WebSphere Process Server interim fixes that will be required to be able to complete migration. Upgrade all new installations to the latest available WebSphere Process Server fix pack.
- Check for INSTCONFSUCCESS message in the installation related log files:
<install_root>/logs/install/logs.txt
<install_root>/logs/wbi/logs.txt
WebSphere Process Server V6.1, V6.1.2 or V6.2
- If you are planning to use the command line utility to migrate or the new profile has to be installed in a user specified directory (non-default), create the required new profiles using the manageprofile command line Tool and make sure to use the same cell name and node name as the previous profile.
- If you are migrating to WebSphere Process Server V6.1, V6.1.2 or V6.2, follow the instructions from the corresponding WebSphere Process Server product documentation to migrate all profiles. Version-to-Version migration is accomplished by a series of scripts (WBIPreUpgrade, WBIPostUpgrade and WBIProfileUpgrade) invoked from command line or by using the Migration Wizard tool (a graphical interface, that guides you through migrating from an older version to a newer version of WebSphere Process Server). Non fatal errors do not stop the migration code from proceeding to the next step. Before proceeding to next migration step, check the following logs to make sure there are not warnings or errors:
WBIPreUpgrade
This command, which you run first, saves the existing WebSphere Process Server configuration and applications into a migration-specific backup directory. - If you are migrating to WebSphere Process Server V6,1, V6.1.2 or V6.2, the following command is used for invoking the migration wizard correctly:
install_root\bin\wbi_migration.bat (on Windows® systems)
install_root/bin/wbi_migration.sh (on UNIX®-based systems)
- Problems while starting the migration command line utilities and if you do not find log files being created, follow these steps to trace the shell script and look for additional clues concerning the failure:
- If you are migrating to WebSphere Process Server V6.1, V6.1.2 or V6.2, to capture additional Java™ trace you can add the -traceString parameter to the command line syntax. example:
- Upgrading databases for migration (V6.1, V6.1.2 or V6.2):
- Start the migrated deployment manager and check the log file for a clean start:
<deployment ManagerProfile>/logs/dmgr/Systemout.log
- Follow similar steps as for the deployment manager, to migrate other managed nodes one by one and check the logs to verify a clean migration.
- If you are migrating to WebSphere Process Server V6.1, V6.1.2 or V6.2, after completing all the profile migration before starting all the cluster members, upgrade the clusters using WBIProfileUpgrade.ant from the deployment manager profile bin directory. Depending on your platform, run one of the following commands for each cluster contained in the profiles migrated above:
- If you are migrating to WebSphere Process Server V6.1, V6.1.2 or V6.2, the database associated with Business Process Choreographer that is accessed by a migrated server needs to have its schema updated before you start the server. See Upgrading BPC Schema topic in the product documentation for details on manual updating the BPC database schema.
- If you are migrating to WebSphere Process Server V6.2 from a previous version then migrating the runtime data is mandatory. MigrteDB.py script is provided to upgrade the database. The script is run from a node where BPC is configured and is only required to run one time for the cluster . See the product documentation Migrating the Business Process Choreographer runtime data topic for additional details.
The following logs associated with this script are saved under <MirationBackupDirectory> directory
Migrating from WebSphere Process Server V6.0.2 to WebSphere Process Server V6.1.x OR WebSphere Process Server V6.2.0.x
- WASPreUpgrade.<timestamp>.log
WBIPreUpgrade.<timestamp>.log
logs/WBIPreUpgrade.trace
logs/WBIPreMigrationSummary.log
logs/WBIPreUpgrade.trace
logs/WBIPreMigrationSummary.log
logs/backupConfig.<profileName>.<timestamp>.log
logs/WBIPreUpgrade.<timestamp>.log
WBIPostUpgrade
This command, which you run second, processes the contents of the migration-specific backup directory that was created with the WBIPreUpgrade command and imports it into the new WebSphere Process Server environment.
The following logs associated with this script are saved under <MirationBackupDirectory> directory.
Migrating from WebSphere Process Server V6.0.2 to WebSphere Process Server V6.1.x OR WebSphere Process Server V6.2.0.x
WBIPostUpgrade.<timestamp>.log
WBIProfileUpgrade.ant.<timestamp>.log
logs/WBIPostUpgrade.trace
logs/WBIPostMigrationSummary.log
logs/WBIPostUpgrade.trace
logs/WASProfileLog.log
logs/WBIPostMigrationSummary.log
logs/restoreConfig.<profileName>.<timestamp>.log
logs/WBIProfileUpgrade.ant.<profileName>.<timestamp>.log
logs/WBIProfileUpgrade.<profileName>.<timestamp>.traceout
Profile creation summary will be saved under WBIProfileCreation.<profileName>.log if migration wizard was used for creating new profiles also check the logs <wpsInstallRoot>/profiles/<profileName>/logs directory for any new profile creation issues.
Check the Graphical User Interface (GUI) log file for errors:
<defaultSystemtempDirectory>\WASMigrationGUISysOut.log
On UNIX-based operating systems, insert "set -x" as the second line of the script.
On Windows operating systems, insert "echo on" as the first line of the script.
WBIPostUpgrade.bat "<backup_directory>" -traceString "*=all=enabled" -traceFile logfileName.trc
If you use the Migration Wizard for migrating, Java™ trace is enabled by default and the traces are saved under:
<MirationBackupDirectory>/
logs/WBIPreUpgrade.trace
logs/WBIPostUpgrade.trace
When the server is first started the database tables are migrated to the new schema version. However, if the server has insufficient permission to access the database schema, or if other database-specific requirements are not met, you must update the database manually before starting the server. See the details in the product documentation for Upgrading the Common database manually and Upgrading the Business Process Choreographer database manually.
- To manually update the common WebSphere Process Server database (default name is WPRCSDB) schema using the following SQL file (example for DB2 database used):
<InstallRoot>/dbscripts/CommonDB/DB2/upgradeSchema602.sql
-To manually upgrade the schema of a Business Process Choreographer database from WebSphere Process Server V6.0.2 before starting any migrated servers, execute the following SQL script for BPEDB (example for DB2 database used):
<InstallRoot>/dbscripts/ProcessChoreographer/DB2/upgradeSchema602.sql
Tip: If there is no script with a number at the end of the script name that matches the release being migrated from, that means that there were no schema changes between that release and the next release.
Windows operating systems
<deploymentManagerProfile>\bin\ws_ant
–f <wbiInstallRoot>\util\WBIProfileUpgrade.ant
–DmigrationDir=<migrationBackupDirectory>
-Dcluster=<clusterName>
UNIX-based and Linux operating systems
<deploymentManagerProfile>/bin/ws_ant.sh
–f <wbiInstallRoot>/util/WBIProfileUpgrade.ant
–DmigrationDir=<migrationBackupDirectory>
-Dcluster=<clusterName>
Where <migrationBackupDirectory> is the directory you chose for the deployment manager migration-specific backup during WBIPreUpgrade command and <clusterName> is the name of the cluster to process.
The WBIProfileUpgrade script creates a log when it runs that is written to the <migrationBackupDirectory> /WBIProfileUpgrade.ant.<DmgrName>-<timestamp>.log directory for each cluster migration
The sample command should be run from a node:
wsadmin -conntype NONE
-tracefile <Backup>/logs/migrateDB.traceout
-f install_root/ProcessChoreographer/admin/migrateDB.py
-cluster WPSCluster
-dbUser DBAUSER -dbSchema BPCDBSCHEMA
-dbPassword secret -slice 5000
Note that -DbUser and -dbSchema options are required if the user configured for server to access BPCDB does not have privileges to create tables or drop tables . For details see migrateDB.py document.
WebSphere Process Server V7,
- If you are planning to use the command line utility to migrate or the new profile has to be installed in a user specified directory (non-default), create the required new profiles using BPMCreateTargetProfile command-line utility
- If you are migrating to WebSphere Process Server V7, follow the instructions from the corresponding WebSphere Process Server product documentation to migrate all profiles. Version-to-Version migration is accomplished by a series of scripts (BPMSnapshotSourceProfile, BPMCreateTargetProfile, BPMMigrateProfile and BPMMigrationStatus ) invoked from command line or by using the Migration Wizard tool (a graphical interface, that guides you through migrating from an older version to a newer version of WebSphere Process Server). Non fatal errors do not stop the migration code from proceeding to the next step. Before proceeding to next migration step, check the following logs to make sure there are not warnings or errors:
BPMSnapshotSourceProfile
This command, which you run first, saves the existing WebSphere Process Server configuration and applications into a migration-specific backup directory. For more information about this command, review "BPMSnapshotSourceProfile command-line utility".
The following logs associated with this script are saved under <SnapshotDirectory>/logsdirectory.
BPMSnapshotSourceProfile.<source_profile_name>.<timestamp>.log
WASPreUpgrade.<timestamp>.log
BPMCreateTargetProfile
This command creates a new profile in the target environment. The following logs associated with the scripts are saved under install_root/logs/manageprofiles directory.
BPMCreateTargetProfile.<source_profile_name>.<timestamp>.log
BPMMigrateProfile
This command, which you run last, processes the contents of the Snapshot directory that was created with the BPMSnapshotSourceProfile command and imports it into the new profile created by BPMCreateTargetProfile command. For more information about this command, review"BPMMigrateProfile command-line utility".
The following logs associated with this script are saved under <SnapshotDirectory>/logsdirectory.
BPMMigrateProfile.<source_profile_name>.<timestamp>.log
WASPostUpgrade.<source_profile_name>.<timestamp>.log
You can use BPMMigrationStatus command to find out the status of the whole migration. Review "BPMMigrationStatus command-line utility" for more information.
- If you are migrating to WebSphere Process Server V7, the following command is used for invoking the migration wizard correctly:
install_root\bin\BPMMigrate.bat (on Windows® systems)
install_root/bin/BPMMigrate.bat (on UNIX®-based systems)
- If you are migrating to WebSphere Process Server V7, to capture additional Java™ trace you can add the -traceString parameter to the command line syntax. example:
- Upgrading databases for migration (V7):
- Start the migrated deployment manager and check the log file for a clean start:
<deployment ManagerProfile>/logs/dmgr/Systemout.log
- Follow similar steps as for the deployment manager, to migrate other managed nodes one by one and check the logs to verify a clean migration.
- If you are migrating to WebSphere Process Server V7, after completing all the profile migration before starting all the cluster members, upgrade the clusters using BPMMigrateCluster from the deployment manager profile bin directory. Depending on your platform, run one of the following commands for each cluster contained in the profiles migrated above:
Check the Graphical User Interface (GUI) log file for errors:
install_root/logs/bpm_migration
BPMMigrateProfile.bat "<snapshot_directory>" -traceString "*=all=enabled" -traceFile logfileName.trc
If you use the Migration Wizard for migrating, Java™ trace is enabled by default and the traces are saved under:
<Snapshot_directory>/
logs/BPMSnapshotSourceProfile.<source_profile_name>.trace
logs/BPMMigrateProfile.<source_profile_name>.trace
When the server is first started the database tables are migrated to the new schema version. However, if the server has insufficient permission to access the database schema, or if other database-specific requirements are not met, you must update the database manually before starting the server. See the details in the product documentation for Upgrading the Common database manually and Upgrading the Business Process Choreographer database manually.
- Windows operating systems
- If you are migrating to WebSphere Process Server V7, the database associated with Business Process Choreographer that is accessed by a migrated server needs to have its schema updated before you start the server. See Upgrading BPC Schema topic in the product documentation for details on manual updating the BPC database schema.
- If you are migrating to WebSphere Process Server V7 from a previous version then migrating the runtime data is mandatory. Review Migration of runtime data for more information.
<deploymentManagerProfile>\bin\BPMMigrateCluster.bat <Snapshot_directory>\<Dmgr_profile_name> <cluster_name> <Dmgr_profile_name>
UNIX-based and Linux operating systems
<deploymentManagerProfile>/bin/BPMMigrateCluster.sh <Snapshot_directory>/<Dmgr_profile_name> <cluster_name> <Dmgr_profile_name>
Where <Snapshot_directory>/<Dmgr_profile_name> is the directory you chose for the deployment manager snapshot during BPMSnapshotSourceProfile command and <cluster_name> is the name of the cluster to process.
The BPMMigrateCluster script creates a log when it runs that is written to the
<Snapshot_directory>/logs/BPMMigrateCluster.<Dmgr_profile_name>.<timestamp>.log directory for each cluster migration.
If you have a missing applications problem, check the <migrationBackupDirectory>/Dmgr for files with the pattern install_<applicationName>.ear.jacl . These files contain the wsadmin scripts used for installing the applications to the new environment. These file are not available if migrating from WebSphere Process Server V6.1.x to WebSphere Process Server V6.2 since during deployment manager migration previous configuration is restored and jacl scripts are not used for installing the application.
Verifying a migrated environment
Start all of the nodes, clusters, and servers. Check the corresponding SystemOut.log files, There should be no error messages. After starting up the server, check the common functions below:
- Datasource connection test
- Messaging engine status check
- Common Event Infrastructure (CEI) migration verification
- Failed Event Manager verification
- Business Rule Manager and BPC Explorer verification
Open the Business Process Choreographer explorer and browse for business rules using the Business Rules Manager (example for Business Rules Manager using the default port):
https://localhost:9443/br/webclient Open the Business Process Choreographer Explorer and check whether it can be opened successfully and those business process instances before migration still exist (if there are any).
Open the administrative console, select JDBC providers > DB2 Universal JDBC Driver Provider (XA) > Data sources, click the Test connection button to check whether these data sources are connected successfully.
Open the administrative console, select Service integration > Buses > busName > Messaging engines to check that the messaging engines started successfully. In this topology, you need to check the Messaging engines of the following buses:
BPC.<cellName>.Bus
CommonEventInfrastructure_Bus
SCA.APPLICATION.<cellName>.Bus
SCA.SYSTEM.<cellName>.Bus
Open the administrative console, select Enterprise Applications, the applications named EventServer and EventServerMdb should not exist after full migration to WebSphere Process Server V6.1.
In the administrative console, select Integration Applications > Common Base Event Browser, input "cell/clusters/CEICluster/ejb/com/ibm/events/access/EventAccess" as Event Data Store, check whether it can get events successfully.
In the administrative console, select Integration Applications > Failed Event Manager > Get all failed events, you should be able to browse the previous generated failed events (if there are events available) and re-submit them successfully.
What to do next
- Use IBM Support Assistant to search for known problems in the product documentation, forums, and technotes.
- Review all the IBM WebSphere Process Server migration related known problems on the Support website.
- If you cannot find related problems or cannot solve the problem, send the information you have collected to IBM by following the instructions in Exchanging Information with IBM Technical Support.
For a listing of all technotes, downloads, and educational materials specific to WebSphere Process Server, search the WebSphere Process Server support page.
Related Information
[{"Product":{"code":"SSQH9M","label":"WebSphere Process Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Migration","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"7.0;6.2","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]
Product Synonym
WPS
Was this topic helpful?
Document Information
Modified date:
15 June 2018
UID
swg21320119