IBM Support

WebSphere Migration Knowledge Collection: Migrating WebSphere Traditional Versions

Product Documentation


Moving your applications to a lightweight application server is the recommended strategy for a cloud environment or if you want to take advantage of newer Java SE, Java EE, or Jakarta EE capabilities. However, if there is a need to perform WebSphere Application Server traditional release to release migrations, this page provides a wealth of information to help you plan and carry out a WebSphere migration.


WebSphere Application Server Product Service Announcements

Before you proceed with the migration, review the following traditional WebSphere support announcements.

Migration Overview

There are many options available when you perform a traditional WebSphere release to release migration. You can migrate your entire Network Deployment (ND) cell into a later release of the WebSphere Application Server product. You can migrate a single application from your Network Deployment cell into its own containerized WebSphere Application Server Base environment, which can then be deployed to the cloud. This article briefly introduces the processes and tools necessary to carry out either a full cell migration, an application-centric cloud migration, or a z/OS migration.

                      image 3951

Although different tools are used to perform a distributed WebSphere cell versus z/OS versus app-centric migration, the process is similar. The migration process can be divided into three steps:

  1. Capture the applications and the associated config.
  2. Create a target profile in the new WebSphere release.
  3. Apply the captured config to the target profile and deploy the applications.
This process allows the new environment to function as close as possible to the old release. At the same time, it gives you the ability to upgrade the configuration to use the new features and functions delivered by the new release.

Full-Cell Distributed Migration

Each WebSphere release is shipped with an updated set of migration tools that must be used to upgrade to the new release. These tools work on a profile by profile basis by using the following process repeated for each profile in the cell starting with the deployment manager:
  1. WASPreUpgrade - captures the old configuration data and applications.
  2. manageprofiles - creates a target profile in the new release.
  3. WASPostUpgrade - merges in the old configuration data into the target profile and installs the applications.

                              image 4049

The full cell migration process supports various other options including:
  • Migrating to new host machines.
  • Cloning your active cell to v9.0 while your current cell stays functional.
  • Selecting only those applications you want moved forward.
Using the machine change, clone and selective application options together provides you with the ability to split the cell into multiple cells, where you can then deploy a specific set of applications into each clone. You can leave nonstrategic applications running in their current environment while you move your mission-critical applications forward to the new release with this process.

App-Centric Migration for Cloud Deployments

Liberty is our preferred containerized runtime as discussed in Migrating to Liberty. Sometimes there are valid reasons for not modernizing applications to Liberty. For applications that you plan to decommission soon or do not easily migrate to Liberty, you can containerize your application in a WebSphere Application Server base server so that all applications are managed with the same operational model.
Today, you might host many applications on a single traditional WebSphere Application Server. When you deploy containerized applications to a cloud environment, it is considered best practice to limit the deployment to a single application or as few applications as possible. This practice makes container image maintenance, updates, and scaling easier.
IBM Cloud Transformation Advisor supports migrating a single application from a WebSphere Application Server environment by generating a configuration script that can be used to configure the server. In addition to providing configuration, Transformation Advisor creates other deployment artifacts such as a Dockerfile and configuration yaml files used for deploying traditional WebSphere images to Kubernetes. Transformation Advisor is included with IBM WebSphere Hybrid Edition and has a free local trial version.
You can also use the WebSphere Migration Toolkit for Application Binaries (binary scanner) to generate an application-specific traditional WebSphere configuration script. Use the binary scanner's --generateConfig and --targetServer=was90 or was855 options to produce a wsadmin script that can configure your new target profile to support the specified application you are installing.
You can learn more about the WebSphere Application Server traditional container images that IBM publishes and the best practices for their use.

                                                image 4119

z/OS Migration

The tools and process for a WebSphere z/OS migration are different from the ones used on distributed systems, but the underlying concepts are the same. Although z/OS does not support remote migrations, it does support the cloning process. Review the following z/OS V9.0 IBM Documentation migration links to get started:

Migration Planning

You are encouraged to always migrate to the latest fix pack of your migration target so that you have the latest migration tools. Start your planning by reviewing and becoming familiar with the information provided in the following documents:

Migration Tool Reference and Links

The following list of the WebSphere migration tools provides a brief description of the tool and a reference link for more information as you plan your WebSphere migration.

Tools included in WebSphere Application Server:

  • createRemoteMigrJar- Facilitates cross machine migrations by eliminating the need to install the new release of WebSphere on your old machine just to run the WASPreUpgrade command.
  • WASPreUpgrade- Captures a snapshot of a WebSphere profile's configuration data and installed applications and saves it to a migration backup directory.
  • WASPostUpgrade- Merges the configuration data captured by the WASPreUpgrade command into the target profile created in the new WebSphere Application Server release.
  • WASMigrationAppInstaller (v9 only) - Installs the applications captured by the WASPreUpgrade command into the target profile created in the new WebSphere Application Server release. Use this command when "-includeApp script" option was used with the WASPostUpgrade command. Select the applications you want to move forward with this command.


  • WebSphere Migration Wizard - Guides you through the migration process on the distributed platforms. Runs the WASPreUpgrade, profile creation, and WASPostUpgrade commands. This tool can also be used to generate the commands needed to run the migration from the command line.
  • WebSphere Customization Toolbox (WCT) - Suite of tools used for creating profiles and migrating them on the z/OS platform.

Other Migration Tools:

  • IBM WebSphere Migration Toolkit for Application Binaries (binary scanner) - Used to analyze an application in its current WebSphere environment. Produces reports to help assess compatibility with your target environment. Can be used to perform app-centric migrations.
  • WebSphere Application Migration Toolkit (source scanner) - An Eclipse IDE developers' tool that helps pinpoint and flag changes to the application source files so they can run in the new server environment. The flagged changes include WebSphere APIs, Java SE, and Java EE level differences.
  • IBM Cloud Transformation Advisor - Provides a detail analysis of your application suite deployed in your WebSphere Application Server environment. Provides recommendations, guidance, and associated artifacts needed to migrate your applications to their new server environment.

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"ARM Category":[{"code":"a8m50000000CdQVAA0","label":"Install Update or Migration-\u003ETraditional WAS-\u003EMigration-\u003EMigration"}],"ARM Case Number":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.5.5;9.0.0;9.0.5","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
01 December 2022