A quick guide for migrating to WebSphere Application Server V7

IBM® WebSphere® Application Server V7 includes simple and straightforward tools that remove the complexity of migrating from a previous version of WebSphere Application Server to Version 7. This overview of the migration process will prepare you for what you need to do and what you can expect so that your migration can be as quick and easy as possible.

Share:

Mark Luchini (mluchini@us.ibm.com), Staff Software Engineer, IBM

Mark Luchini is a Staff Software Engineer at IBM located in Rochester, Minnesota. Prior to his current roll on the Migration Development team, he was a member of the WebSphere Application Server's System Verification Test (SVT) Migration team for 4 releases, as well as the team lead for JDBC 3.0 testing in v6.0, Migration focal point for 6.0.2, and co-founder and team lead for the Existing Customer SVT for v6.1. Mark holds a Bachelors degree in Computer Science, Engineering from Michigan State University, and a Masters degree in Software Engineering from SMU, Texas. You can reach Mark at mluchini@us.ibm.com.



Dana Duffield (dmd@us.ibm.com), Senior Software Engineer, IBM

Dana Duffield is a Senior Software Engineer and is the Migration and Interoperability Architect for WebSphere Application Server in IBM Rochester. He is a software engineer who has worked at the IBM Rochester Lab for over 24 years on various development projects. He holds a Bachelor of Science degree in Computer Science from the University of Illinois, Champagne-Urbana. He has significant experience in object-oriented and distributed system development in architecture, development and leadership positions. Prior to working at IBM, he worked at Bell Laboratories in Naperville, Illinois. You can reach Dana at dmd@us.ibm.com.



Rongzhong (Alex) Guo (guorong@us.ibm.com), Staff Software Engineer, IBM

Rongzhong (Alex) Guo is a Staff Software Engineer at IBM located in Rochester, Minnesota. Prior to his current roll as Migration Developer and L3 Lead, he was a member of the WebSphere Application Server Functional Verification Test (FVT) team for four releases, as well as the developer for I18N, scheduler, asynchronous beans. Alex holds a Master degree in Computer Science, from NC A&T State University. You can reach Alex at guorong@us.ibm.com.



17 December 2008

Also available in Chinese Japanese

Introduction

This article will help you get started migrating from IBM WebSphere Application Server V5.1 or V6 to WebSphere Application Server V7. This article presents a high level overview of the WebSphere Application Server V7 migration tools and their usage, plus a summary of some special considerations that will apply when migrating from specific versions, for both single server and a managed cell. For detailed information on any of the steps in the migration process, see WebSphere Application Server V7 Information Center.

Terminology used in this article
TermDefinition as used in this document

Backup directory

Directory structure created by the WASPreUpgrade tool that contains all the information necessary for migrating from the previous version of WebSphere Application Server.

Cell

Collection of one or more nodes controlled by a single deployment manager.

convertScriptCompatibility

Command that converts the V7 configuration from a mode in which script compatibility is supported to a mode in which script compatibility is no longer supported. For example, transports from V5 are converted to channels.

Deployment Manager profile (dmgr)

This profile acts as the deployment manager, and is the destination for the migration of the V5.1 or V6.x deployment manager. There can be only one Deployment Manager profile for each cell.

Federate or Federated

Refers to the action of adding a node to a cell, or to a node that is already part of a cell, respectively.

FirstSteps

Tool provided in V6 and V7 to simplify and organize many initial actions that you might wish to perform with a newly installed system. This tool can be found in the firststeps directory under each profile and can be used to launch the Migration wizard. (Not available for IBM i or z/OS®.)

Migrated <item>

When used to describe an element of WebSphere Application Server configuration, indicates that this item was carried forward during migration and now resides in the target profile.

Migration

For our purposes, migration is limited to the actions associated with moving Java™ 2 Enterprise Edition (J2EE) applications (EAR files) and WebSphere Application Server configuration data (such as resources and security settings) from a previous version of WebSphere Application Server to V7.

Migration wizard

Refers to the graphical user interface (GUI) that interactively performs the migration. This GUI tool performs both the WASPreUpgrade and WASPostUpgrade steps. (Not available for IBM i or z/OS).

New <item>

When used to describe an element of WebSphere Application Server configuration, indicates that this item resides in the target (or migrated) profile.

Previous <item>

When used to describe an element of WebSphere Application Server configuration, indicates that this item resides in the source profile.

Profiles

This concept expands on the idea of instances in V5, and refers to the collection of all the configuration data for a WebSphere Application Server in V6 and V7. WebSphere Application Server V7 provides for multiple profiles with only one installation of the binaries. A single profile is required as the destination for the data being migrated from a previous version.

Source profile

Refers to your V5.1 or V6.x WebSphere Application Server configuration, from which information will be carried forward into V7.

Standalone or Application Server profile

Refers to a profile that is analogous to a single node WebSphere Application Server installation. This type of profile is the destination for the migrations of a node both in a cell and not in a cell, although the Custom profile is recommended for federated nodes.

Target profile

Refers to the V7 profile into which your configuration will be migrated. Analogous to your WebSphere Application Server V7 configuration.

V6, V5, and so on

This style of notation refers to various versions of WebSphere Application Server. For example, V6 will be used when information applied to both WebSphere Application Server Version 6.0.2 and 6.1.

WASPreUpgrade

Tool that performs the first step of the two-step migration process. This step extracts information from the previous version of WebSphere Application Server and stores it in a backup directory. This tool can be run by itself from the command line or as part of the Migration wizard.

WASPostUpgrade

Tool that performs the second step of the two-step migration process. This step takes information from a directory created by the WASPreUpgrade tool and imports it into a V7 profile. This tool can be run by itself from the command line or as part of the Migration wizard.

Migration support across WebSphere Application Server

The basics of migration support and tooling are similar across all the operating systems supported by WebSphere Application Server V7. The root of this tooling is described in Run the command line tools. However, there are differences in what interfaces are available for some operating systems, as well as some characteristics that are unique to some operating systems. Following is a high level overview of this support:

z/OS

Migrating WebSphere Application Server for z/OS to V7 involves customizing a set of batch jobs and then running those jobs to migrate a node. Customization is accomplished using the z/OS Migration Management tool which is included in the WebSphere Customization Tools for V7. Each node in a cell will have its own customized jobs; a cell is migrated node by node, starting with the Deployment Manager node.

The z/OS Migration Management tool is the only interface to the migration support on z/OS. The unique characteristics of the z/OS operating system, as well as the migration steps for z/OS, are covered in the white paper Migrating to WebSphere z/OS V7 by Don Bagwell. This white paper, along with information in the WebSphere Application Server V7 Information Center, do an excellent job of describing the migration support for z/OS. We will not duplicate that information in this article.

IBM i

Migrating WebSphere Application Server for IBM i to V7 involves evoking the tools is described in the Run command line tools section. Using these command line tools is the only interface to the migration support on IBM i. You can use this article to guide your IBM i migration, but keep in mind that the support described in the Migration wizard section is not applicable to IBM i. Also, a migration CD is not available for IBM i.

Distributed platforms

Distributed platforms essentially include all the operating systems that are supported by WebSphere Application Server, other than z/OS and IBM i. See the List of supported software for WebSphere Application Server V7 for a complete list of these operating systems and their system requirements. These operating systems are supported by either using the command line tools or the Migration wizard.

1. Prepare to migrate

This section covers important issues you need to review prior to attempting a migration from a previous version of WebSphere Application Server to V7. Unless otherwise specified, all points discussed here apply when migrating from either V5.1 or V6.

  1. Confirm prerequisite software levels. Review the List of supported software for WebSphere Application Server V7 for minimum version and fix level requirements for your operating system and associated software. If your existing WebSphere Application Server V5.1 or V6 installation is on an operating system version that does not meet V7 prerequisites (such as AIX® 5.1 or Sun™ Solaris™ 8), then an operating system upgrade will be required before you can install WebSphere Application Server V7 on that system.

  2. Gather information. Before starting the migration procedure using the command line tools, it is important to track down the names of all nodes in the V5.1 or V6 cell, in addition to the cell name. These values are used when creating V7 profiles for each node in the cell. Profiles will be discussed more in the next section.

  3. Backup your environment. Backup your WebSphere Application Server environments before attempting any migration. This is especially critical if you will be performing an incremental cell upgrade. You can use the WebSphere Application Server backup tool to save the current environment; to learn more about this, review articles related to the backupConfig utility in either the V5.1 or V6 Information Center (see Resources.

  4. Leave your previous version of WebSphere Application Server intact. This point cannot be stressed enough: Do not uninstall your existing WebSphere Application Server V5.1 or V6 configuration, leave it as is. WebSphere Application Server V7 will co-exist safely with these previous versions -- assuming that only one version of WebSphere Application Server is running at any given moment. Besides being required for the first step of migration, having the previous version of WebSphere Application Server intact also enables you to rollback your environment to the previous version, if desired or necessary.

2. Install WebSphere Application Server V7

The installation process for V7 has changed from the process used in V5. One important change is that migration has been decoupled from the installer. As mentioned earlier, a Migration wizard (for distributed operating systems only) will guide you through the migration after you have installed V7. If you previously used the Silent option to install and migrate to a previous version, you can still install silently, after which you will need to use the migration command line tools manually.

Introduced in V6, WebSphere Application Server V7 uses the concept of profiles, which are independent instances of the WebSphere Application Server configuration and application file sets. In essence, profiles enable multiple configurations of V7 with only one copy of the WebSphere Application Server core binary files. Profiles offer an improvement over V5.1 instances, and V7 has tooling that can be used to create and manage these profiles.

You will use the FirstSteps tool to access the Profile Management tool, shown in Figure 1.

Figure 1. Profile management tool
Profile management tool

In WebSphere Application Server Network Deployment V7 (hereafter referred to as Network Deployment), there are five types of profiles available:

  • Deployment manager
  • Job manager
  • Administrative agent
  • Custom
  • Application server.

Only the application server profile is available in the other editions of WebSphere Application Server V7. Figure 1 shows the Network Deployment Profile Management tool, from which you can select from four predefined profile layouts, called environments.

A profile does not need to exist prior to running the Migration wizard. However, if you plan to use the migration command line tools, then you will need to create profiles for your environment.

When creating a profile for migrating from a previous release, certain values must match between the previous version and the new version. Specifically, when migrating a deployment manager to V7, the cell name value of the V7 profile must match the cell name from V5.1 or V6; when migrating to a V7 federated node, the node name of the V7 profile must match the node name from the previous version’s federated node, and so on. For nodes that are not part of a cell, such as a standalone system, there are no such naming requirements for the V7 profile.

In all cases, if there is a valid mismatch between the node and cell names of the old and new profiles, the values from the new profiles will be used and the migration will update all the configuration information owned by WebSphere Application Server to use the new profile names.

If you use the Migration wizard or the z/OS customization jobs to create your profile and to migrate, then these values are filled in for you.

For a Network Deployment migration, profiles must be migrated in this specific sequence:

  1. Deployment manager profile. This profile must be migrated first whenever a cell is being migrated. The V7 migrated Deployment Manager profile can manage all V5.1 and V6 nodes in the cell. WebSphere Application Server V7 restricts the migrated deployment manager by letting it manage only V5.1 nodes that were in the cell prior to migration. Specifically, V5.1 nodes cannot be federated into a V7 deployment manager -- but V6.02 and later nodes can be added to a V7 deployment manager. For V5.1 users, the Deployment Manager profile is analogous to WebSphere Application Server Network Deployment V5.1 and deployment manager installations. Each cell must have exactly one deployment manager.

  2. Job manager profile. This profile is new in V7 and has no analogous profile from previous releases, therefore no configurations can be migrated into a V7 Job Manager profile.

  3. Administrative agent profile. This profile is new in V7 and has no analogous profile from previous releases, therefore no configurations can be migrated into a V7 Job Manager profile.

  4. Custom profile. This profile is ideal for a federated node migration. There are no default applications or application servers created for this profile. Each node of the previous release can be migrated to exactly one Custom profile. The nodes will be members of the V7 mixed cell and can, at any time, be migrated to V7 nodes.

  5. Application server profile. This profile is analogous to a single node installation in V5 or V6. The profile is created with an application server called server1, plus several default applications

3. Perform the migration

The next steps you will perform will depend on the migration method you have chosen. You will either:

  1. Run the Migration wizard, or
  2. Run the command line tools.

3a. Run the Migration wizard

The Migration wizard is new and improved for V7 and replaces the migration panels that were a part of the Application Server Installer for V5.1. The Migration wizard is not available for IBM i or z/OS platforms. The Migration wizard is found on the FirstSteps panel. To run the Migration wizard:

  1. Launch FirstSteps from the profile directory, if one exists; for example: C:\WebSphere\AppServer\profiles\default\. On Windows®, you can launch FirstSteps from either the profile directory’s firststeps folder or from the Start Menu.

  2. After FirstSteps is launched, select Migration wizard to begin the migration process (Figure 2).

    Figure 2. First steps panel
    First steps panel
  3. After the Welcome panel displays, select the prior version of WebSphere Application Server you want to migrate from a list of detected versions (Figure 3). It is important that you make sure the location of the previous version is correct by verifying the location displayed in the Installation root directory of the previous version field. If the previous version you want to migrate is not detected by the wizard, use this field to specify its location after first checking Specify the installation location if your existing product is not listed.

    Figure 3. Detected versions of WebSphere Application Server
    Detected versions of WebSphere Application Server
  4. Select which profile in the previous version you want to migrate (Figure 4). For V5, you will typically migrate the defaultinstance; however, if you created more than one instance, you can select any one of your other V5 instances. For V6, you can select which profile you want to migrate, but remember that the deployment manager must always be migrated before the federated nodes.

    Figure 4. Source profile selection panel
    Source profile selection panel
  5. e. If you have defined one or more profile, such as a V7 deployment manager and a V7 node profile on the same system, you must select the profile to be used as your target profile (Figure 5). If you have not already created a V7 profile, the Migration wizard can create one for you if you select <Create new profile>.

    Figure 5. Target profile selection panel
    Target profile selection panel
  6. If you have the Migration wizard create a profile, the panel shown in Figure 6 will display. The Migration wizard will populate the required fields with appropriate values; for example, if you are migrating a deployment manager, then the wizard will determine the cell name from your source WebSphere Application Server, and so on.

    Figure 6. Profile creation panel
    Profile creation panel
  7. The migration tools use a backup directory to migrate your previous version of WebSphere Application Server to V7. Specify where the backup directory is located, or, if it does not already exist, where it should be created (Figure 7).

    Figure 7. Migration backup directory panel
    Migration backup directory panel
  8. Figures 8 and 9 show the panels for application migration settings. These panels enable the V7 Migration wizard to use new parameters in the WASPostUpgrade command. On these panels, you can select whether you want to migrate and install the applications, or if you want to have scripts created so you can migrate the applications at a later time. You can also select the location where you want to have the applications installed.

    Figure 8. Application install migration settings panel
    Application install migration settings panel
  9. On the next panel (Figure 9), you can change the location where applications will be installed. By default, migrating will install applications into the config directory of WebSphere Application Server V7. If you have your applications installed outside of the WebSphere directory tree structure, you can select the option to Keep the same application directories as the previous version. Alternatively, you can also enter a new or different directory in which to install your applications. If the application installation directory location is not important to you, then accept the default.

    Figure 9. Application directory migration settings panel
    Application directory migration settings panel
  10. By default, the V5 or V6 deployment manager is disabled during the migration process, but if you have a critical need, you can opt to Do not disable the deployment manager of the previous version (Figure 10). This lets you use the deployment manager for your previous version while the migration is in progress. However, this is an unsupported configuration and so this option must be used with extreme caution. The previous deployment manager is stopped and disabled to prevent multiple deployment managers from working on the same managed nodes. Should you not disable the previous deployment manager, you are responsible for later disabling -- and not using -- the previous deployment manager before the new deployment manager is started.

    Figure 10. Deployment manager disablement panel
    Deployment manager disablement panel
  11. Specify the port values you wish to use on the Port value assignment panel (Figure 11). You can select to use the port values from the source installation (default), in which case the V7 WebContainer ports will be removed prior to migration, thus avoiding any conflicts with the WebContainer port being migrated forward. You can also select a block of ports to be used for all ports created during the migration process.

    Figure 11. Port value assignment panel
    Port value assignment panel
  12. The administrative console customized My Tasks was new in Version V6.1, and so the panel shown in Figure 12 only displays when you are migrating from V6.1 . You can opt to use either the default workspace user root location, which is wstemp under your Version V6.1 profile home, or a user specified workspace root location.

    Figure 12. Admin console customized My tasks panel
    Admin console customized My tasks panel
  13. You will need to provide User name and Password on the Administrative security panel (Figure 13). This panel only displays when global security is enabled in the previous version and the security.xml does not contain the corresponding User name and Password values. This typically occurs when migrating from Version 6.1.

    Figure 13. Administrative security panel
    Administrative security panel
  14. Indicate whether you want migration to support script compatibility on the panel shown in Figure 14. Check Migrate to support script compatibility if, for example, you have scripts or programs that are used to create or modify your configuration definitions. If you leave this option unchecked, the migration tooling will, for example, create V7 channels rather than transports. More information on the convertScriptCompatibility command is provided in the next section.

    Figure 14. Script compatibility panel
    Script compatibility panel
  15. The Migration summary panel (Figure 15) is the last panel that displays before you execute any commands. Confirm your selections here or go back and make any necessary changes.

    Figure 15. Migration summary panel
    Migration summary panel
  16. If you had selected to <Create new profile>, then you will see a panel similar to the one in Figure 16. As long as profile creation completes successfully, then the migration will continue. If there is a problem while creating a profile, then the wizard will end.

    Figure 16. Profile creation output panel
    Profile creation output panel
  17. Select Next on the Migration summary panel (or on the Profile creation output panel) to run the migration. The WASPreUpgrade command will run, followed by the WASPostUpgrade command. These commands essentially perform the migration, and will be discussed in the next section.

  18. After WASPreUpgrade and WASPostUpgrade have completed, the Migration status panel (Figure 17) displays, providing a summary status of the output from the migration commands.

    Figure 17. Migration status panel
    Migration status panel

3b. Run the command line tools

The WASPreUpgrade and WASPostUpgrade commands can be used to manually migrate your previous version of WebSphere Application Server to V7. The Migration wizard calls these tools as part of the automated migration process. These commands should always be called from the V7 profile directory, not the V5.1 or V6 directory, since the commands have changed with each release. The commands can also be found in the bin folder of the V7 profile, but if you choose to use the commands from this directory, you will need to specify which V7 profile the command should run against.

  1. WASPreUpgrade

    The WASPreUpgrade command creates a backup of all pertinent V5 and V6 WebSphere Application Server configuration information. The contents of the backup are specific to the version and configuration setup.

    The syntax of WASPreUpgrade command is:

    WASPreUpgrade backupDirectory 
    	currentWebSphereDirectory
    	[-traceString trace_spec]
    	[-traceFile file_name]
    	[-machineChange true | false]
    	[-oldProfile old_profile_name]
    	[-workspaceRoot user_workspace_folder]

    Only the first two parameters are required. An example of what you could run for V5.1 could be:

    C:\IBM\WebSphere\AppServer7\profiles\default\bin\WASPreUpgrade.bat
    C:\IBM\WebSphere\Backupv51Config 
    C:\IBM\WebSphere\AppServer51

    The final two lines of the WASPreUpgrade output, if successful, will be:

    MIGR0303I: The existing WebSphere Application Server environment is saved.
    MIGR0420I: The first step of migration completed successfully.

    Refer to the WebSphere Application Server V7 Information Center for details on using the WASPreUpgrade command, or run the WASPreUpgrade command without any parameters to display the command’s syntax. To diagnose a migration problem, see WASPreUpgrade logs.

  2. WASPostUpgrade

    The WASPostUpgrade command takes the backup created by WASPreUpgrade and uses it to move the previous configuration up to V7.

    The syntax for WASPostUpgrade is:

    WASPostUpgrade backupDirectory
    	[-profileName profile_name]
    	[-oldProfile profile_name]
    	[-backupConfig true | false]
    	[-username username ]
    	[-password password ]
    	[-traceString trace_spec 
    	[-traceFile file_name]]
    	[-portBlock port_starting_number]
    	[-replacePorts true | false]
    	[-includeApps true | false | script]
    	[-scriptCompatibility true | false]
    	[
    		[-appInstallDirectory user_specified_directory]
    	  |
    		[-keepAppDirectory true | false]
    	]
    	[-keepDmgrEnabled true | false]

    Only the first parameter is required. An example of what you could run might be:

    C:\IBM\WebSphere\AppServer7\profiles\default\bin\WASPostUpgrade.bat
    C:\IBM\WebSphere\Backupv51Config

    When there is more than one V7 profile, use the –profileName parameter to specify which profile should be updated. This is especially important when you run this command from the main WebSphere Application Server directory, as opposed to the profile directory. (That is, for example, from C:\IBM\WebSphere\AppServer7\bin versus C:\IBM\WebSphere\AppServer7\profiles\default\bin.) If the command is run from the main WebSphere Application Server directory and the –profileName parameter is not used, the command will use the default profile, which is not necessarily the profile whose name is "default."

    The WASPostUpgrade command can end with warnings and still be successful, so review the log files to see why there was a warning, and if any additional action is necessary. The final output from the WASPostUpgrade command should be either:

    MIGR0259I: The migration has successfully completed.

    or

    MIGR0271W: Migration completed successfully, with one or more warnings.

    The WASPostUpgrade tool creates a backup of the V7 environment prior to making any changes, and will attempt to rollback any changes if an error such as the following occurs:

    MIGR0272E: The migration function cannot complete the command.

    See the WebSphere Application Server V7 Information Center for details on using the WASPostUpgrade command, or run the WASPostUpgrade command without any parameters to display the command’s syntax. To diagnose a migration problem, see WASPostUpgrade logs.

  3. convertScriptCompatibility

    The convertScriptCompatibility command converts the V7 configuration from a mode in which script compatibility is supported to a mode in which script compatibility is not to be supported. Script compatibility mode occurs by either running WASPostUpgrade with -scriptCompatibility true, or by taking the default value.

    The syntax for convertScriptCompatibility is:

    convertScriptCompatibility [-help]
    	[-backupConfig true | false]
    	[-profileName profile_name]
    	[-nodeName node_name [-serverName server_name]]
    	[-traceString trace_spec
    	[-traceFile file_name]]

    There are no required parameters. An example of what you could run might be:

    C:\IBM\WebSphere\AppServer61\profiles\default\bin\convertScriptCompatibility.bat

    When there is more than one V7 profile, use the –profileName parameter to specify which profile should be updated. This is especially important when you run this command from the main WebSphere Application Server directory, as opposed to the profile directory. (That is, for example, from C:\IBM\WebSphere\AppServer7\bin verses C:\IBM\WebSphere\AppServer7\profiles\default\bin.) If the command is run from the main WebSphere Application Server directory and the –profileName parameter is not used, the command will use the default profile, which is not necessarily the profile whose name is "default."

    Special consideration should be noted when attempting to run this conversion against a federated node. The command should be run against the dmgr profile specifying the federated node you want to convert using the -nodeName parameter. After you have run convertScriptCompatibility, you will be required to manually sync with the federated node you just converted in order to download those changes to the node.

    If successful, convertScriptCompatibility will end with this message:

    MIGR0259I: The migration has successfully completed.

    The convertScriptCompatibility tool creates a backup of the V7 environment prior to making any changes, and will attempt to rollback any changes if an error such as the following occurs:

    MIGR0272E: The migration function cannot complete the command.

    Refer to the WebSphere Application Server V7 Information Center for details on using convertScriptCompatibility, or run the convertScriptCompatibility command specifying -help to display the command’s syntax. To diagnose a migration problem, see convertScriptCompatibility logs.

4. Review the log files

Whether you are performing a manual migration or migrating through the wizard, it’s always a good idea to review the log files for any errors or warnings that might require some kind of action. Trace files will be generated by default on all platforms except z/OS; however, these files are solely for use by IBM Support personnel, if required.

WASPreUpgrade logs

The following log files are created when the WASPreUpgrade command is run manually:

<backupDirectory>/logs/WASPreUpgrade.<Date-Time>.log<
<backupDirectory>/logs/WASPreUpgrade.trace

When migrating through the Migration wizard, these log and trace files are created:

<backupDirectory>/logs/preMigrationOutput.log
<backupDirectory>/logs/WASPreMigrationSummary.log

WASPostUpgrade logs

The following log files are created when the WASPostUpgrade command is run manually:

<backupDirectory>/logs/WASPostUpgrade.<profile>.<Date-Time>.log
<backupDirectory>/logs/WASPostUpgrade.<profile>.trace
<profileDirectory>/logs/<cloudscapeDBName><Log|Debug><Date-Time>.log

When migrating through the Migration wizard, these log and trace files are created:

<backupDirectory>/logs/WASPostMigrationSummary.log
<backupDirectory>/logs/<cloudscapeDBName><Log|Debug><Date-Time>.log

convertScriptCompatibility logs

The following log file is created when the convertScriptCompatibility command is run manually:

<profileDirectory>/logs/convertScriptCompatibility.<Date-Time>.log
<profileDirectory>/logs/ConvertScriptCompatibility

Differences and exceptions

Regardless of whether you perform your migration manually or with the wizard, you will find differences between your old and new configurations -- even more so when you specify the –scriptCompatibilty false option (non-default value) or run the convertScriptCompatibility tool. Here are some common things to be aware of:

  • New ports and port changes

    New releases of WebSphere Application Server usually come with new services, and therefore new service endpoints. These service endpoints might bind a network address; for example, the IPC_INBOUND_CONNECTOR. These new ports will be updated to ensure that they do not conflict with the migrated configuration, but they will not be updated to resolve port conflicts between multiple profiles in the same physical hardware. For this, you will need to manually resolve port conflicts either during profile creation or, if you created profiles using migration tools, after the migration.

    In addition, based on how you set up port resolution (–portBlock and –replacePorts in the WASPostUpgrade tool), some of your port values might change from the values in either the previous configuration or that were created as part of V7 profile creation. For every server that binds ports, the migration components log the port updates in the time-stamped WASPostUpgrade log file. See the previous section for information on how to locate this log. The summary view will be in a standard format as shown here:

    MIGR0446I: Port conflicts were resolved during migration as shown below for 
    document: C:/workarea/WebSphere/v7/profiles/profile/config/cells/cellName/
    nodes/nodeName/servers/dmgr/server.xml
          Port Identifier          Port Value
          ---------------          ----------
          dmgr@transport_9090      9090
          dmgr@transport_9043      9043
    
    MIGR0446I: Port conflicts were resolved during migration as shown below for
    document: C:/workarea/WebSphere/v7 /profiles/profile/config/cells/cellName/
    nodes/nodeName/serverindex.xml
          Port Identifier                                 Port Value
          ---------------                                 ----------
          dmgr@CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS      9402
          dmgr@SAS_SSL_SERVERAUTH_LISTENER_ADDRESS        9401
          dmgr@WC_adminhost_secure                        9044
          dmgr@DRS_CLIENT_ADDRESS                         7989
          dmgr@DCS_UNICAST_ADDRESS                        9352
          dmgr@WC_adminhost                               9060
          dmgr@IPC_CONNECTOR_ADDRESS                      9632
          dmgr@DataPowerMgr_inbound_secure                5555
          dmgr@CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS      9403
          dmgr@CELL_DISCOVERY_ADDRESS                     7277
          dmgr@ORB_LISTENER_ADDRESS                       9100
          dmgr@BOOTSTRAP_ADDRESS                          9809
          dmgr@SOAP_CONNECTOR_ADDRESS                     8879
  • Node and cell name changes

    If you have a mismatch between the node and cell name values when you migrate from a previous release, you should be aware of why this might happen: In the case of deployment manager migrations, the V7 deployment manager node name will replace the V5.1 or V6 node name. For standalone migrations, the V7 node and cell names will replace the V5.1 or V6 values. In the case of federated node migrations, the V7 cell name will be replaced with the cell name from the V7 deployment manager, which means that the node and cell names will always be the same as their values from the V5.1 or V6 configuration.

  • Cloudscape conversion to Derby

    Cloudscape support was replaced with Derby prior to WebSphere Application Server V7. The migration tools will automatically detect Cloudscape databases in the configuration and migrate the data into an analogous Derby database. Due to incompatibilities, some databases cannot be automatically upgraded. In those cases, the WASPostUpgrade log will display a warning that a database was not migrated, and you will have to manually resolve this situation by either removing the Derby database from your configuration, or manually converting the data from Cloudscape to Derby.

    Because Cloudscape databases are not supported in production environments, failure to migrate Cloudscape databases will not cause the migration tools to fail or terminate. The migration will continue to run and save the configuration, even when databases are not migrated.

  • Applications failing to install

    If an application fails to install during migration, it is possible that it might not be supported as is on WebSphere Application Server V7, or there may be non-WebSphere configuration information that needs to be manually updated or migrated. Failure of an application to install will not cause the migration to fail or terminate. A message is sent to the WASPostUpgrade summary logs and to the time-stamped logs detailing the error that was encountered. The migration tools also leave behind the migrated application file and the wsadmin installation script so that you can resolve the issue and invoke the script manually to install the application.

    Migrated applications are located in the V7 profile/installableApps directory, and the installation script is in the root of the migration backup directory.

For a complete set of WebSphere Application Server version-to-version migration information, see Knowledge Collection: Migration planning for WebSphere Application Server.

Conclusion

This overview should give you enough familiarity with the migration tools in WebSphere Application Server V7, and their usage and options, to help you begin the migration process. The process is largely automated and relatively straightforward, but this article also included some special considerations if you are migrating from a single server or from a managed cell. We hope you find this information useful, wish you well with your migration, and hope you enjoy using the new and improved WebSphere Application Server V7.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=359327
ArticleTitle=A quick guide for migrating to WebSphere Application Server V7
publish-date=12172008