WCMT4IC now supports migrating to IBM Cloud Private!

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 environments 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 (WCMT4IC) provides an easy to use wizard for cloning your WebSphere V7, V8, V855 or V9 environment to the IBM Cloud or to your IBM Cloud Private installation.

If you have an IBM Cloud account with access to the WebSphere Application Server services or if you have access to your own IBM Cloud Private installation, give the tool a try today. Simply download the wizard, unzip it, and within a short time you can have a clone of your existing cell running in the IBM Cloud on WebSphere V9.0.

Find out more about the GDPR readiness for the WCMT4IC migration wizard.

Migration basics for Traditional WebSphere

The goal of a traditional WebSphere migration is to provide a pathway forward to the features and functions of the new release while maintaining a stable environment. A two-step process is use in migrating WebSphere. First, the old configuration data is captured using the WASPreUpgrade command. Next, it is then merged with a target profile created under the new release using the WASPostUpgrade command. Migrations are done on a per-profile basis, therefore each node in the cell has its own profile and is migrated using the following process:

In a standard migration process, each node in the cell is disabled when it is migrated. However, in version v9.0 the clone option was introduced allowing the old cell to remain intact and completely functional both during and after the migration. In fact, when the migration completes both the old and new 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 your migration issues.
  • Use it to test and verify your new environment (whether administrative or development).
  • Clone the same cell multiple times for use by different teams.
  • No scheduling of weekend or weeknight outages for migrations.
  • Minimal or no downtime.

An additional migration option is the ability to migrate from one machine to another. The machineChange option causes the WASPreUpgrade command to capture additional configuration data (e.g. shared libraries) when migrating to a new machine. Combining this option with the clone option achieves even further isolation between the old and new environments.

Going to the Cloud?

Whether you migrate your WebSphere environment to your own IBM Cloud Private installation or to IBM’s public cloud, the WebSphere Configuration Migration Tool for IBM Cloud allows you to start evaluating WebSphere V9.0 today. Combining the machineChange and clone options, this wizard simplifies migrating your WebSphere environment to the IBM Cloud. No waiting for hardware setup or software installations. Once the WebSphere cell has been provisioned in the cloud, keep the virtual machines for as long as you need. Even for your new production environment. When you are done with a service instance, simply delete it. The remainder of this article provides an overview of the on-premises-to-IBM Cloud migration wizard.

Getting, installing, and running the wizard

Download the WebSphere Configuration Migration Tool for IBM Cloud and install it by unzipping it to a directory of your choice. Ensure that you pre-pend your Java installation’s bin directory to the system path. Java version 7 or higher is required to run the wizard itself. However, processing of a local node requires the wizard to invoke the WASPreUpgrde command and therefore is limited to Java version 7 or version 8. Once the system path is set, change directory to where the wizard was unzipped and use the following command: java -jar CloudMigration.jar. When running the wizard for the first time you will be prompted to set the language and to accept the license agreement.

Preparing your WebSphere cell for migrating to the IBM Cloud

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, up-to-date and exchanged with the Federated Nodes. Clean up any errant or unused variables, unused data sources, and any other general housekeeping items that are specific to your WebSphere environment. As the on-premises-to-IBM Cloud migration process is highly automated, these steps help reduce the possibility for errors during the provisioning process.

Welcome page

The Welcome page gives a brief overview of the two phases involved in migrating your WebSphere cell to IBM Cloud or IBM Cloud Private. Each phase is associated with a graphical user interface which you will use to complete cloning of your WebSphere cell to the IBM Cloud. The first phase uses the WCMT4IC wizard to:

  1. Obtain a WebSphere service instance from the IBM Cloud installation.
  2. Select the WebSphere cell you want to migrate and assigns it to the service instance.
  3. Find, collect, encrypt and upload each node’s configuration data to a secure temporary staging area accessible only by the assigned migration service.
  4. Provide additional steps on how to provision your virtual machines and complete the final steps of your migration.

The second phase uses the IBM Cloud user interface to provision the WebSphere Application Server virtual machines.

Applying these phases to the basic migration model shown earlier we get the following diagram:

The green oval on the left represents phase one or the work done by the WCMT4IC wizard. The purple oval on the right represents phase two or the work done by the IBM Cloud WebSphere provisioning service. The dotted blue box in the middle is the secured temporary storage area for the cell’s configuration data needed during phase 2.

Other 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 are help and preference buttons. If you press the help button, a separate window pops up giving you information about your current window. This help page remains synchronized as the wizard advances. The preference button allows you to change the language setting, which requires a restart of the wizard.

Login page

Use the Product: field to select whether you will be migrating to IBM Cloud (public) or to IBM Cloud Private. Both products are supported by the wizard, however, there are slight variations on the Login and on the Service Selection pages of the wizard.

  • IBM Cloud (public)
    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 a 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 or entered, 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, click the one-time passcode link and follow instruction to obtain your pass code. Click Next to proceed with your migration.
  • IBM Cloud Private
    Contact the administrator of your company’s IBM Cloud Private installation to set up proper access to your installation’s VM Quickstarter services. In the location field, enter in the proper URL for accessing the QuickStarter service. It may look something like the following example: Enter your userid and password and click Log in. You may need to temporarily accept a certificate for the duration of this connection. Click Next to proceed with your migration.

Select Migration Service page

After logging in, the wizard proceeds to the WebSphere migration Service Selection page. Obtaining a WebSphere service instance from IBM Cloud is slightly different depending on the product you selected earlier.

  • IBM Cloud (public)
    Select an organization from the dropdown list. If you only have one organization, the wizard automatically proceeds to display a list of all spaces associated with that organization. Next select a space under that organization. If there is only one space associated with that organization, the wizard automatically proceeds to display a list of all un-provisioned WebSphere service instances.
  • IBM Cloud Private
    Select a resource group from the dropdown list. If you only have one resource group, the wizard automatically proceeds to display a list of all un-provisioned WebSphere service instances.

If your service instance list is empty or you wish to begin a new migration, use the New button to create of a new WebSphere service instance. In the pop-up, provide a unique name for the instance and select the appropriate environment. Use the default selection if you are unsure of the environment name. New instances are added to the list and tagged with a Will be created ID. The new service instance is created when you select and confirm the WebSphere cell you are migrating. (Note: At any time, you can see a list of all your service instances from the dashboard of the IBM Cloud UI. The wizard only shows un-provisioned service instances. From the dashboard you can see the status of each WebSphere service instance and perform various operations on them, such as deleting the instance.)

If the list contains un-provisioned service instances, they may or may not be bound to a WebSphere cell. If you select a new (Will be created ID) or an un-bound service instance and click Next, the wizard proceeds to the Select a WebSphere Cell page. If you select a bound service instance and click Next, the wizard proceeds to the Upload to IBM Cloud page. The later sceanrio is used when nodes of a WebSphere cell span multiple machines. Starting the wizard on each machine and selecting the same service instance provides an easy path for collecting and uploading each node’s migration data when it is local to that machine.

Select a WebSphere Cell page (for new or un-bound instances only)

The wizard interrogates the machine on which it is running for all WebSphere Application Server installations. These are displayed in the top table and the installation is identified by its path and WebSphere 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 its folder, select it and then confirm that you want to add it to the list. The Locate dialog not only allows you to find a local installation, but also allows you to process a profile located on a different machine. See the Processing data from a different machine locally section for more details.

By selecting 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. These profiles have a type of either: StandAlone Application Server or Deployment Manager. The name of the WebSphere cell being managed is also displayed. Note that Federated Node profiles are not displayed, but are processed later during the upload process of a Network Deployment cell.

Once you have selected the managing profile of the cell to be migrated, click Next. In the confirmation popup window, click Continue. At this point the service instance is created and bound to the selected WebSphere cell. If you need to reset this migration, simply go to the IBM Cloud UI, delete the service instance, and restart the wizard. Once the service instance is bound to a WebSphere cell, the wizard advances to the Upload to IBM Cloud page.

Upload to IBM Cloud page

The last step, before you provision the IBM Cloud virtual machines for this service instance, is to upload the configuration data for each node in the WebSphere cell. This data is encrypted and uploaded to a secure temporary location. For a standAlone application server, the cell contains only one node. Whereas for a Network Deployment cell it contains a Deployment Manager and one or more federated nodes. Each node in the cell is listed on this page, including: its name, type, and the machine name or IP address where the node is located. Each node also has a local or remote indicator which tells you whether the node’s configuration data is local to the current machine. If the node has a green checkmark, this indicates that the node’s configuration data has already been uploaded.

AMigrate button is provided for each node. This button behaves differently depending on whether the node is local or remote. Clicking Migrate for a local node causes the wizard to automatically collect, archive and upload that node’s configuration data. Clicking Migrate for a remote node causes a dialog pop-up to present the two options on how to upload configuration data for a remote node. They are:

  1. The easy option: Install the wizard on the remote machine, start it, select the correct service instance, proceed to the upload page. The node that was remote, is now local to that machine. Click Migrate to finish automated procesing.
  2. The manual option: or processing a remote node locally. This process is somewhat involved and is covered by the Processing data from a different machine locally section below.

All configuration data is encrypted before it is uploaded to the temporary location. It is only accessible by the WebSphere service instance to which it is bound. The data is deleted when the provisioning process completes, or when the WebSphere service instance is deleted.

WebSphere security

If security is enabled, you will need to provide your WebSphere admin userid and password. The on-premises-to-IBM Cloud migration process disables WebSphere global security in your new cloned environment, except for when the security is only configured using a file-based WIM user registry. Security must be disabled during the migration process because the virtual machines are isolated from other machies when they are provisioned. For example, if your security configuration involves an LDAP server, the provisioning process cannot connect to the LDAP server during the WASPostUpgrade process. Therefore, global security is disabled so that the migration can complete. Once the virtual machines are provisioned security can be re-enabled, but it requires additional set up work to enable the new virtual machines to access your on-premises LDAP server.

Application Scanning

Applications are installed as-is during the WASPostUpgrade process. Although WebSphere supports applications that run on previous versions of WebSphere, there are always differences that must be understood and tested. As a convenience, the wizard produces an application migration report for applications moving from the older WebSphere releases to version 9.0. This report gives a preliminary look at what application migration issues need to be investigated and handled. A link to this report is provided on the Final page.

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

Final page

You will not be able to proceed to the Final page until all nodes have been uploaded. If any remote nodes have not been uploaded, exit from the wizard on the current machine, install and start the wizard on the remote machines. Once you have uploaded the last node’s configuration data, use the wizard on any machine to proceed to the Final page.

Once you arrive at the Final page, you will be presented with a checklist of a required and several optional steps. The required step is to provision your service instance using the IBM Cloud UI. A link to the provisioning page of this service instance is provided. See Provisioning the IBM Cloud Host Machine section below for more information on how to do this. Once the provisioning is done you can proceed with the optional steps, which might 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 resources to help you get your newly cloned WebSphere cell working like your on-premises WebSphere cell. Please note that it is a clone and therefore will access the same databases, queues, topics, etc, once all the proper communication channels have been enabled.

Processing data from a different machine locally

The wizard supports processing a remote node’s configuration data on any machine where Java 7 or higher is installed. This is ideal for situations where the wizard cannot be run on those machines or you do not wish to impact performance. Remote processing is always done at a profile level, whether for selecting a WebSphere cell or uploading a node’s configuration data. The process is similar in both cases and the wizard guides you through the steps using a dialog box. For the case of selecting a WebSphere cell, click the Locate button, then select the Install from an installation on another system radio button. For the case of uploading a remote node, simply click on the Migrate button. The first and easiest option presented by the dialog box is to install this wizard on the remote system. The second option requires a bit of transferring data back and forth between the two machines. Here is a brief overview:

  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 from the dialog box and run it on the remote machine to collect the profile’s data.
  4. Zip up the migration backup directory for the profile you collected.
  5. Send it back to the local machine.
  6. Browse to the location of the zip file and click Choose. 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 process.

Unzipping the WASPreUpgrade utility on Unix systems may require premissions to be set on the WASPre/bin directory. Use chmod +x -R.

Provisioning the IBM Cloud host machine

The provisioning link provided on the Final page requires a bit of attention. Although the wizard has uploaded the cell’s configuration data to the service instance, this link still requires you to select the appropriate settings before provisoning. Be sure to follow these steps:

  1. Depending on your migration, select Single Server or Traditional Cell in the WebSphere Traditional pane.
  2. The IBM Cloud WebSphere service already knows this instance is associated with a migration, therefore the migration check box should be checked. Do not uncheck it. Ignore the information in the expanded migration box.
  3. On the Deployment Manager and Application Server tabs you must decide on the size of your virtual machines. For Network Deployment migrations, all federated nodes will be the same size. On the Application Server tab do not modify the number of nodes. This was pre-set by the wizard.
  4. Last, click the Provision button. This button is enabled only if the configuration data for all nodes has been uploaded.

The provisioning process takes some time to complete, depending on the number of nodes and the number of applications being processed. Although the status indicator reaches 99%, the migration process may still be underway. When the provisioning process completes, the consumer portal page appears. 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 instructions. The provisioning process starts the Deployment Manager server and the node agents on the federated nodes. It does not start the application servers in a Network Deployment cell. However, the application server is started for standalone server migrations. You should be able to access the WebSphere Admin Console from the consumer portal page once your OpenVPN is configured and started.


The WebSphere Configuration Migration Tool for IBM Cloud provides a variety of options in helping you 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 WebSphere release to release migration efforts.

Join The Discussion

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