IBM Support

Collect troubleshooting data for migration problems in WebSphere Process Server

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

Table of contents




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.

  • 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

    Migrating from WebSphere Process Server V6.1.x to WebSphere Process Server V6.2.0.x

      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
    Migrating from WebSphere Process Server V6.1.X to WebSphere Process Server V6.2.0.x

      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.

  • 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)

  • Check the Graphical User Interface (GUI) log file for errors:
    <defaultSystemtempDirectory>\WASMigrationGUISysOut.log


  • 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:


  • 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.

  • 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:


  • 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



  • Upgrading databases for migration (V6.1, V6.1.2 or V6.2):

  • 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.

  • 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:


  • 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


  • 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 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)

  • Check the Graphical User Interface (GUI) log file for errors:
    install_root/logs/bpm_migration

  • 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:


  • 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


  • Upgrading databases for migration (V7):

  • 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.

  • 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:
    Windows operating systems
    <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 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.


    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

  • 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.

  • Messaging engine status check

  • 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



  • Common Event Infrastructure (CEI) migration verification

  • 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.

  • Failed Event Manager verification

  • 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.

  • 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).



What to do next

  1. Use IBM Support Assistant to search for known problems in the product documentation, forums, and technotes.

  2. Review all the IBM WebSphere Process Server migration related known problems on the Support website.

  3. 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.

[{"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

Document Information

Modified date:
15 June 2018

UID

swg21320119