BPMMigrateProfile command-line utility

The BPMMigrateProfile command migrates a source profile from the snapshot directory to a target profile.

Synopsis

BPMMigrateProfile [options] snapshot_directory source_profile_name

Description

The BPMMigrateProfile command migrates the configuration files that were copied from a source profile specified by the snapshot_directory parameter and the source_profile_name parameter to a target profile created with the BPMCreateTargetProfile command.

Note: The BPMMigrateProfile command should be invoked from the target_install_root/bin directory.
CAUTION:
On Solaris 64-bit operating systems, to avoid OutOfMemory errors during profile migration, determine whether the default JVM heap size of 768 MB will work. Depending on the number of applications that are part of the profile being migrated, this parameter might need adjustment. Use the -javaoption option to override the default value and specify a custom value for JVM heap size.

Options

-username source_profile_user_name
Use this option to pass the source profile's administrative user name if the source profile has security configured.
-password source_profile_password
Use this option to pass the source profile's administrative password if the source profile has security configured.
-targetProfileName target_profile_name
Use this option to identify the target profile name created by the BPMCreateTargetProfile command if the name of the target profile is different from that of the source profile.
-javaoption JVM_Heap_Size
Use this option to set the JVM heap size configuration for the migration process. If the BPMMigrateProfile command fails with an OutOfMemory exception because of an unusually large number of applications, you can use this parameter to adjust the JVM heap size. The default value used by the command is 768 MB. The minimum value that can be specified is 256.
-requestTimeout SOAP_timeout_value
Use this option to adjust the timeout configuration if the default value fails and the migration fails with SOAP timeout errors. The default value is 80 seconds. This option is applicable only for federated profiles that connect to the deployment manager during migration.
-basePort basePort
Use this option to define the base port number to be used for assigning new ports during the migration process. The initial request for a port will use the base port number, and each subsequent request will be assigned the next consecutive port number.
-replacePorts [true | false]
Use this option to specify how to map port values for virtual hosts and web container transport ports.

By default, do not replace the version 6.2.0 port definition during migration. The source version's configuration is left alone and no channels are deleted. The following four named channels are set to values that are equivalent to the values set for the source version:

  • WC_adminhost
  • WC_defaulthost
  • WC_adminhost_secure
  • WC_defaulthost_secure

This option is supported for stand-alone profile migration only.

The migration process creates transports or channels, based on the -scriptCompatibility setting, for any ports in the source version. The migration process sets all non-web-container ports to the values set for the previous release.

Port conflicts might arise if the migration process creates a transport or channel that is the same as one defined in the web container. This is the default.

If this option is specified, replace all virtual host alias port settings during migration with version 8.0 port definitions.

By default, the migration process adds configuration data from the previous environment to the data in the new IBM® Business Process Manager environment. In some cases, however, this might not be the correct behavior for these port values. For example, existing port definitions from the earlier release might have been carefully set to avoid port conflicts with other products. In such cases, it is likely that you would want to migrate these settings into the new version's configuration.

Specify true for this parameter to cause any ports of matching virtual hosts to be removed from the newer version's configuration before the new values are added. All transport channels associated with the web container are deleted except for the following four named channels, which are set to values that are equivalent to the values set for the previous release:
  • WC_adminhost
  • WC_defaulthost
  • WC_adminhost_secure
  • WC_defaulthost_secure
The migration process creates transports or channels, based on the -scriptCompatibility setting, for any ports in the previous release. The migration process sets all non-web-container ports to the values set for the previous release.

If the -replacePorts parameter is set to true, the migration process uses all port values from the old configuration in the new configuration. All ports from the old configuration supersede the settings for the same ports in the new configuration.

If the -replacePorts parameter is set to false, the default port definitions in the new profile are not replaced with the values from the old configuration during migration. All port values from the new configuration supersede the settings for the same ports in the old configuration.

If the -replacePorts parameter is not set, a conflicting port is renumbered incrementally from its original value until a nonconflicting port is identified. If the -basePort parameter is set, a conflicting port is renumbered incrementally from the port block number until a nonconflicting port is identified.

-scriptCompatability [true | false]
This is an optional parameter that specifies whether migration should create the following WebSphere® Application Server Version 6.x or Version 7.x configuration definitions:
  • Transport
  • ProcessDef
  • Version 6.x SSL
instead of these version 8.0 configuration definitions:
  • Channels
  • ProcessDefs
  • Version 7.5 SSL

The default value is true. Specify true to minimize impacts to existing administration scripts. For example, if you have existing wsadmin scripts or programs that use third-party configuration APIs to create or modify the Version 6.x configuration definitions, you might want to specify true for this option during migration.

Note: This is temporary until all of the nodes in the environment are at the version 8.0 level. When they are all at the 8.0 level, perform the following actions:
  • 1. Modify your administration scripts to use all of the Version 8.0 settings.
  • 2. Use the convertScriptCompatibility command to convert your configurations to match all of the Version 8.0 settings. See convertScriptCompatibility command for more information.
-keepSourceDMgrEnabled [true | false]
This option is pertinent only to deployment manager profiles.

By default, when a source deployment manager profile is migrated to a target deployment manager profile, the source deployment manager profile is disabled. Disabling the source deployment manager by default ensures that the source and target deployment managers are not started at the same time.

CAUTION:
Use this parameter as true with care.WebSphere Application Server Version 6.x deployment manager configurations normally are stopped and disabled to prevent multiple deployment managers from managing the same nodes. If you do not stop the Version 6.x or Version 7.x deployment manager before you start using the Version 8.0 deployment manager, port conflicts might occur when the second instance of the deployment manager is started.

Specifying true for this parameter means that any configuration changes made in the old configuration during migration might not be migrated.

-keepAppDirectory
This is an optional parameter that specifies whether to install all applications to the same directories in which they are currently located. The default is false. If this parameter is specified as true, each individual application retains its location.
Restriction: If this parameter is specified as true, the location is shared by the existing IBM Business Process Manager and the new installation. If you keep the migrated applications in the same locations as those of the previous version, the following restrictions apply:
  • The version 8.0 mixed-node support limitations must be followed. This means that the following support cannot be used when evoking the wsadmin command:
    • Precompile JSP
    • Use Binary Configuration
    • Deploy EJB
  • You risk losing the migrated applications unintentionally if you later delete applications from these locations when administering your previously existing installation (for example, when uninstalling it).
-appInstallDirectory user_specified_directory
Use this optional parameter to pass the directory name to use when installing all applications during migration. The default of profile_name\installedApps is used if this parameter is not specified. Quotation marks must be used around the directory name if one or more blanks are in the name.
Tip: You can include the variable ${USER_INSTALL_ROOT} in your argument. This variable expands to WPS HOME\profiles\ profile name. For example, if IBM Business Process Manager version 7.0 is installed at C:\wps\ and the target profile is ProcSrv01, ${USER_INSTALL_ROOT} represents C:\wps70\profiles\ProcSrv01.
-trace [fine|finer|finest|all]
Use the -trace option to generate detailed trace information. Specify the granularity of the trace as fine, finer, finest, or all. By default, the trace information is written to these files: snapshot_directory/logs/command.timestamp.trace. For example: 
BPMMigrateProfile.timestamp.trace
BPMProfileUpgrade.timestamp.trace
WASPostUpgrade.timestamp.trace
-traceFile file_name
Use the -traceFile parameter to specify the file where the trace information is written.
-wasTraceString trace_spec
Use this option to specify the trace for the base WebSphere Application Server migration command WASPreUpgrade to generate detailed trace information. To gather all trace information, specify: 
-wasTraceString *=all
To get a trace for a specific component, specify, for example:
-wasTraceString com.ibm.ws.migration.preupgrade.*=all:com.ibm.ws.admin.*=finer
By default, the trace information is written to the snapshot_directory/logs/WASPostUpgrade.profile_nametimestamp.log file.
-help
Provides the command usage.
This topic applies only to the Distributed platforms

Examples

Migrate the configuration for the source profile named profile1 copied to the /MigrationSnapshots/ProcServer directory:

Migrate the configuration for the source profile named profile1 (which has security turned on) that is copied to the /MigrationSnapshots/ProcServer directory:

Migrate the configuration for the source profile named profile1 that is copied to the /MigrationSnapshots/ProcServer directory to a target profile that was created with a different name of profile2:

Migrate the configuration for the source profile named profile1 copied to the /MigrationSnapshots/ProcServer directory with trace turned on to the finest level and specify a non-default trace log file:

Problem Determination

Errors are logged in the snapshot directory in a file whose name begins with BPMMigrateProfile and ends with .error.

To turn on trace, use the -trace option. By default, the trace information is written to the snapshot_directory/logs/BPMMigrateProfile. timestamp.log file. To specify an alternative trace file, use the -traceFile parameter.

The BPMMigrateProfile command displays status to the screen while it is running. This command also saves a more extensive set of logging information in the BPMMigrateProfile.profilename.timestamp.log file located in the snapshot_directory/logs directory. You can view the BPMMigrateProfile.profilename.timestamp.log file with a text editor.

If the profile migration fails, check the logs to identify the problem and fix it. You can then rerun the BPMMigrateProfile command.

If the keepSourceDMgrEnabled option is specified, make sure that both deployment managers are not started at the same time. If they are, port conflict errors will likely result and managed profiles will receive conflicting configuration information. If the keepSourceDMgrEnabled option is not specified, and it is necessary to roll back a deployment manager profile migration, use the migrationDisablementReversal command.

When migrating a managed node, if you see a ConnectorException error, as shown here, ensure that your deployment manager is running and then rerun the command. 
MIGR0380E: The JMX connection is not established with the deployment manager node qaxs06, 
using connector type of SOAP on port 8879. The WASPostMigration program is now closing. 
No changes are made to the local Application Server environment. 
com.ibm.websphere.management.exception.ConnectorException: ADMC0016E: The system cannot 
create a SOAP connector to connect to host qaxs06 at port 8879. 
com.ibm.ws.migration.utility.UpgradeException: com.ibm.websphere.management.exception.ConnectorException: 
ADMC0016E: The system cannot create a SOAP connector to connect to host qaxs06 at port 8879.
Parent topic: Command-line utilities