Troubleshooting migration

If your deployment environment was not migrated successfully, you can take steps to resolve issues.

Consider the following possibilities:
  • A SOAP invocation timeout might have occurred
  • Migration commands for the target environment might have failed for other reasons. You can diagnose some failures by enabling tracing for specific command-line utilities and rerunning those specific commands.

If you ran all the migration commands on the source environment and created a snapshot before the migration failed, you do not need to rerun all the migration commands again from the beginning. If the migration failed on the target, for example at the database upgrade step or when you ran the BPMMigrate command, you can restore the database and rerun the commands on the target only.

SOAP invocation timeout

If you are using a SOAP connection, the migration command can take longer to complete than the specified SOAP timeout value. You might see an exception like java.net.SocketTimeoutException: Read timed out.

To prevent this problem, modify the value of the com.ibm.SOAP.requestTimeout property in the soap.client.props file.
  • If you installed the new version of the product on the same computer as the source environment, the file is found in BPM_home_8.5/util/migration/resources/.
  • If you installed the new version of the product on a different computer and copied the migration files to the source environment, the file is found in remote_migration_utility/util/migration/resources/.

Enabling tracing

To diagnose the reason for a migration failure, you can enable tracing and rerun a command. To enable tracing for migration commands, complete the following steps:
  1. Locate the logging.properties file.
    For the DBUpgrade command-line utility, the file is in BPM_home_8.5/util/dbUpgrade. For example:
    • For UNIX operating systemFor Linux operating system/opt/ibm/WebSphere/AppServer/util/dbUpgrade/logging.properties
    • For Windows operating systemC:\bpm 85\util\dbUpgrade\logging.properties
    For the following command-line utilities:
    • BPMExtractSourceInformation
    • BPMManageApplications
    • BPMMigrate
    The file is in BPM_home_8.5/util/migration/resources. For example:
    • For UNIX operating systemFor Linux operating system/opt/ibm/WebSphere/AppServer/util/migration/resources/logging.properties
    • For Windows operating systemC:\bpm 85\util\migration\resources\logging.properties
  2. Set the log level in the logging.properties file. The default log level is FINE for both global logging level and file output log level. Change both properties to FINEST to capture more detail in the log. For example: 
    # default global logging level. Logging level possible values: FINEST, FINER, FINE, INFO, WARNING, SEVERE.
.level = FINEST
# file output properties
com.ibm.bpm.migration.logging.NonBlockingFileHandler.level = FINEST

If you see exceptions for any of the following commands, change the log level to FINEST, run the command again, and then check the results, as described for each command.