Migrating your traditional WebSphere environment can require extensive planning and coordination. Among the things to consider are your hardware and software needs, not only for your production environment, but also for your development, testing, and pre-production environments. And scheduling time to migrate each of these environment is not always easy. Now there is a tool to help get you started earlier as you plan your move to WebSphere V9.0. The WebSphere Configuration Migration Tool for IBM Cloud provides an easy to use wizard for cloning your WebSphere V7, V8 or V855 environment to the IBM Cloud. If you have an IBM Cloud account with access to the WebSphere Application Server services, then give this tool a try today. Simply download the tool, install it, and within a short time you can have a ‘clone’ of your existing cell running in the IBM Cloud on WebSphere V9.0.

Follow this link for more information on GDPR readiness for this migration tool.

Traditional WebSphere migration basics

The goal of a traditional WebSphere migration is to provide a pathway forward to the new release while maintaining a stable environment. The old configuration data is captured by the WASPreUpgrade command and then merged into a target profile in the new release using the WASPostUpgrade command. Migrations are done on a per-profile basis.

Prior to version 9.0, nodes in a Network Deployment configuration are disabled when their profiles are migrated. In version 9.0, the WASPostUpgrade clone migration option was introduced. This option allows the old Network Deployment cell to remain intact and completely functional both during and after the migration. In fact, when the migration completes, both cells are completely independent and can run concurrently. Here are a few other benefits of using the clone migration option:

  • Practice and throw away: use `clone` to iterate through and work out migration issues.
  • Use to test and verify new environment (both administrative and development).
  • Clone the same cell multiple times for use by different teams.
  • No scheduling of weekend or weeknight outages.
  • No downtime.

An additional migration option that should be mentioned here is the ability to migrate from one machine to another. The WASPreUpgrade command provides a machineChange option which is used to capture additional configuration data when the profile is migrated to the new release on a new machine. Combining this option with the clone option achieves even further isolation of the two environments.

Going to the Cloud?

Whether you stay on-premises with your WebSphere environment or go to the IBM Cloud, the WebSphere Configuration Migration Tool for IBM Cloud means you can start analyzing WebSphere V9.0 today. Using the machineChange and clone options, this tool migrates your WebSphere environment to the IBM Cloud. No waiting for hardware setup or software installations. Keep the IBM Cloud virtual machines for as long as you need. When you are done, simply turn the service instance back in. The remainder of this article provides an overview of the on-premises-to-IBM Cloud migration wizard.

Getting, installing, and running the tool

Download the WebSphere Configuration Migration Tool for IBM Cloud and install it by unzipping it to a directory of your choice. Set the JAVA_HOME environment variable to a version of Java 7 or higher. Also pre-pend the $JAVA_HOME/bin directory to your system path. To run the tool, use the following command: java -jar CloudMigration.jar When you run the tool for the first time you will be prompted to set the language and then to accept the license agreement.

Preparing your WebSphere cell for the IBM Cloud migration

Before performing any migration to the IBM Cloud, complete a few minor tasks—especially if you are migrating a Network Deployment cell. Be sure that all nodes are synchronized with the Deployment Manager. Be sure that certificates are valid and up-to-date. Clean up any errant variables, unused data sources, and any other general housekeeping items that are specific to your WebSphere environment.

Welcome page

The Welcome page gives a brief overview of the two phases involved in migrating your WebSphere cell to the IBM Cloud. Each phase is associated with a graphical user interfaces which you will use to complete the process. The first phase uses this wizard and the second phase uses the IBM Cloud user interface for the WebSphere Application Server services. Phase one is responsible for obtaining a WebSphere service instance from the IBM Cloud to which you will assign a cell that is to be migrated. It also handles the collecting and uploading of the encrypted configuration data for each node in the cell. Applying these phases to the basic migration process explained earlier we get the following picture:

The green oval on the left represents phase one or the work done by this wizard. The purple oval on the right represents phase two or the work done by the IBM Cloud WebSphere service after pushing the provision button from its user interface. The dotted blue box in the middle is where the configuration migration data is encrypted and temporarily stored.

Some notes regarding the wizard:

  • The left-side of the window always displays a checklist of the main steps for phase one and indicates which step you are on.
  • In the bottom-left is a help and a preference button. If you press the help button, a separate window pops up giving you information about your current window. This help page remains synchronized with the page currently being displayed by the wizard. The preference button allows you to change the language setting, which requires a restart of the tool.

Login page

You need an IBM Cloud account with access to the WebSphere Application Server services to run this wizard. On the login page, you must select your region. The drop-down list displays the four main IBM Cloud regions. However, the field also allows you to enter the URL for specially configured regions. Once the region is selected, provide your username and password. If you cannot log in using this method the wizard also supports signing in with a one-time pass code.

Select Migration Service page

After logging in, a list of organizations for your account is displayed. If you only have one organization, the wizard automatically proceeds forward to show your list of associated spaces, otherwise you must select an organization from the list. The same goes for the space list, if only one space exists the wizard proceeds forward to list all valid service instances. Only service instances that have not been completed or which have not started the provisioning process are displayed. A service instance is created by the WebSphere Application Server service on the IBM Cloud to handle the provisioning of virtual machines which have the WebSphere Application Server product installed. If you select an existing service instance and it has been assigned a WebSphere cell to migrate, clicking Next takes you to the “Upload to IBM Cloud” page. For unassigned or new service instances the wizard advances you to the “Select a WebSphere Cell” page. When creating a new instance, the wizard adds it to the list with a Will be created ID:

New service instances are not created until a WebSphere cell has been selected. At any time, you can see a list of all your service instances using the IBM Cloud UI and going to the dashboard. From there you can see the status of each instance. You may also delete instances from the dashboard.

Select a WebSphere Cell page (for new instances only)

The wizard interrogates the system for all WebSphere Application Server installations. They are displayed in the top table and identified by the installation path and version. Versions older than 7.0 are not displayed as they cannot be migrated to version 9.0. If an installation is not listed, use the Locate button to browse to the folder and it will be added to the list. The Locate dialog not only allows you to find installation on the current system, but it can be used to process a profile location on a different machine. See the Processing data from a different machine section below for more details.

When you select an installation from the top table, the bottom table is populated with a list of valid server profiles created under that installation. The IBM Cloud migration process is a cell-based migration, therefore only those profiles which manage a cell are listed in the bottom table. These profiles will have a type of StandAlone Application Server or Deployment Manager. Each profile’s name and type are displayed along with the name of the cell it manages. Federated nodes belonging to the Network Deployment cell are not displayed but will be process later as part of the uploading process.

Once you have selected the managing profile of the cell to be migrated, click Next. A confirmation popup asks if you want to proceed. Answering Yes causes a service instance to be created, which includes storing the selected WebSphere cell’s metadata. You can reset after this point by going to the IBM Cloud UI and deleting this service instance. You must restart the IBM Cloud migration wizard if you reset the service instance. Answering Yes also moves you forward to the “Upload to IBM Cloud” page.

Upload to IBM Cloud page

You can arrive at this page either by creating a new instance and assigning it a WebSphere cell or by selecting an existing service instance which has not begun its provisioning process. This page lists all nodes in the WebSphere cell, whether on the current machine (local) or on a different machine (remote). Each node’s configuration data must be gathered, archived, and uploaded to IBM Cloud’s object store. The data is encrypted and temporarily stored here, until the provisioning process completes, after which time it is deleted.

The WebSphere cell’s metadata is stored with the service instance. This is important as it allows the migration process to be suspended or exited on one machine and then be continued and completed on another machine. This allows you to process the nodes on remote machines more efficiently.
Each node in the list indicates its type, name, and whether it is local or remote. It also indicates the machine name or IP address where the node is located. A green check appears if the node’s configuration data has already been uploaded. The Migrate button on the right acts differently depending on whether the node is local or remote. If it is local then the node’s configuration data is gathered, archived and uploaded. If remote, you are presented with a dialog with two options.

The first option tells you to install the wizard on the other machine and select the correct service instance. This takes you to the “Upload to IBM Cloud” page where you can then process what was the remote node on the other machine. It now shows up as local. If you want to process a remote node locally, see the Processing data from a different machine section below.

Because the IBM Cloud virtual machines are isolated from the internet, this migration process turns off global security to perform the migration. For example, if your security configuration involves an LDAP server, the provisioning process cannot connect to it during the WASPostUpgrade process on the virtual hosts. Therefore, if the wizard detects that security is enabled, it prompts you for the username and password and lets you know that security will be disabled. After migration completes this can be configured and re-enabled. Providing the username and password and hitting OK validates that you accept this condition.

During the upload process, the wizard also performs application scanning. Applications are installed ‘as-is’ during the WASPostUpgrade process. Although WebSphere supports applications that ran on previous versions of WebSphere, there are always differences that must be checked out. As a convenience, the wizard produces an application migration report for applications moving from the older release to version 9.0. This gives a preliminary look at what application migration issues may need to be investigated.

When all nodes are uploaded click Next to proceed to the final page.

Final page

If you have not uploaded all nodes, the final page lets you know which nodes have not been uploaded and the machine they are on. Click the Back button to continue uploading any local nodes or click Finish to exit. For any remote nodes you can install this wizard on those machines to complete the uploads. No need to return to the original machine, you can complete the migration from where the final upload occurs.

If all nodes are uploaded, the final page presents a checklist of required and optional steps. The only required step is to provision your service instance using the IBM Cloud UI. A link is provided to the provisioning page of the service instance. See Provisioning the IBM Cloud Host Machine section below for more information.

The optional steps include:

  • Re-enabling security
  • Migrating applications, including a link to the binary scanner report
  • Setting up a Secure Gateway Service
  • Setting up a Web Server

Each optional step provides you with resources to get your cloned IBM Cloud WebSphere cell working as it did on-premises. Please note that it is a clone and therefore will access the same databases, queues, topics, and so on. Therefore, before starting any application analyze any other configuration changes you may need to make. Be aware that a limited number of ports have been opened for sending and receiving data on these IBM Cloud host machines. Open any additional ports as needed.

Processing data from a different machine

It is not necessary to process a WebSphere installation or upload a node on its local machine. All processing can be done remotely on a machine that does not have WebSphere installed. This is ideal for situations where this wizard cannot be run on those machines. Remote processing is always done at a profile level, even for the scenario where you are processing installed for the “Select a WebSphere Cell” page.

To view the remote processing dialog from that page, click the Locate button, then select the Install from an installation on another system radio button. This brings up a similar dialog to the one that pops up when clicking the Migrate button for a remote node on the “Upload to IBM Cloud” page. The first and the easiest option is to install this tool on the other system. The second option requires a series of steps, but is not too difficult:

  1. On the system running the wizard create a `WASPreUpgrade` utility.
  2. Send the utility to the remote system and unzip it to a directory of your choice.
  3. Copy the suggested command to collect the profile data. For the install dialog, the profile location is unknown, whereas for the node migration it is supplied.
  4. Zip up the config backup directory
  5. Send it back to the system running the wizard.
  6. Browse to the location of the zip file and choose it. The wizard will then add it to the install list for the “Select a WebSphere Cell” page. For the “Upload to IBM Cloud” page it will begin the upload processing.

Note: Unzipping the WASPreUpgrade utility on Unix systems requires a chmod +x -R on the WASPre/bin directory.

Provisioning the IBM Cloud host machine

The provisioning link provided on the final page requires a bit of attention. Although the wizard has upload the cells information to the service instance, this link still requires you to select the appropriate settings. Be sure to follow these steps:

  1. Depending on your migration, select Single Server or Traditional Cell in the WebSphere Traditional pane.
  2. The service knows it is associated with a migration, therefore the migration check box should be checked, and the Migration section expanded. Ignore the information in the box and scroll down.
  3. Here you must decide on the sizes for your host machines. For Network Deployment migrations, all Federated Nodes are the same size. On the Application Server tab, do not modify the number of nodes.
  4. Last, click the Provision button. This button is only enabled if the exact number of nodes have been uploaded.

The provisioning process takes some time depending on the number of nodes and the number of applications. Although the status indicator may be at 99%, the migration process may still be underway. When the provisioning process is complete you are taken to a consumer portal page. This page gives you instructions on how to access you WebSphere cell in the IBM Cloud. Be sure to follow the OpenVPN installation and configuration. The migration process starts the Deployment Manager server and the node agents on the federated nodes. It does not start the application servers. The server is started for standalone migrations. You should be able to access the Admin Console from the Consumer Portal page once your OpenVPN is configured.


The WebSphere Configuration Migration Tool for IBM Cloud provides a variety of options in helping your organization prepare to migrate to WebSphere V9.0. The ability to clone multiple times, to easily reset and start fresh, to avoid the hassles of hardware setup and software installations reduces the complexity of your migration planning. Combining the WebSphere V9.0 migration enhancements with the convenience of the IBM Cloud can give you an edge up in your next migration efforts.

Join The Discussion

Your email address will not be published. Required fields are marked *