IBM Support

WebSphere Migration Knowledge Collection: Migrating to Liberty

Product Documentation


Liberty is the WebSphere container-ready runtime available to run everything from your Java™ EE monoliths to your Microprofile microservices to your Spring Boot deployable JAR files. Moving to Liberty is recommended for modernizing both your runtime and operational environment. This page gives more information on moving applications from traditional WebSphere® Application Server to Liberty.


Why Liberty

Liberty is a container-ready Java™ EE application server that is perfect for containerized environments.

When you adopt a container strategy, Liberty images are available for both Open Liberty and WebSphere Liberty on Docker Hub and Red Hat certified images.

Liberty has one of the fastest startup times of any Java EE application servers, and it keeps getting better.  It has high server throughput to handle your most important workloads.

So what is the difference between Open Liberty and WebSphere Liberty?

Open Liberty is the open source Liberty application server that is developed fully in the open at It supports the Java EE 7 and 8 and Jakarta EE 9.1 full profile programming models. If you want a fast, composable, production-ready, open source Java EE application server, look no further than Open Liberty.

WebSphere Liberty is built from Open Liberty and contains more features for Java EE 6 web profile to ease some migration scenarios where we had different underlying implementations for Java EE technologies like JPA, JAX-RS, and CDI.

Zero Migration

After the initial move to Liberty, the Liberty zero-migration architecture means that you can update the product runtime files and continue to use you existing unmodified applications and configuration with no unwanted or unexpected behavior changes. With zero migration, you can create new images or install new Liberty binary files with no surprises.

If you choose to update your application to a later Java EE level, you can do so to get the latest capability. It is a choice, not a requirement, and the WebSphere migration tools help you with that move as well.

Application Modernization Assessment and Detailed Analysis

There are two parts to application modernization: runtime and operations. Runtime modernization refers to moving applications from traditional WebSphere Application Server to Liberty or perhaps rewriting the front end to use Node.js. Operational modernization refers to updating your deployment operations to use container orchestration and with new DevOps and GitOps best practices. Using IBM WebSphere Hybrid Edition and Red Hat OpenShift, all your runtimes can be managed with consistency.

The tools described here evaluate your applications to move to Liberty for runtime modernization. There are some differences between traditional WebSphere Application Server and Liberty that takes some migration effort if your application uses older, deprecated technologies or proprietary APIs. For example, WebSphere Liberty supports Java EE 6 web profile (not Java EE 6 full profile). Liberty has Java EE 7 and 8 full profile support, but it does not include optional Java EE technologies such as JAX-RPC and Entity EJB beans. Some of the WebSphere proprietary APIs that were superseded by Java EE APIs were also removed from Liberty. When you have a Java EE application running on Liberty, the zero migration architecture gives you confidence that it is easy to keep it running there.

As described in the Getting Started guide, developing a strategy and plan are an important part of any modernization project. The modernization and migration tools show you the differences and make it easy to understand which applications are affected so that you can plan.

To start your modernization process, there are a number of tools that can help.

Transformation Advisor

To get the large picture of the migration effort for your application estate, start with IBM Cloud Transformation Advisor.  The Transformation Advisor data collector scans your entire cell and uploads the results to the Transformation Advisor UI where you can compare application migration complexities, estimate development costs, and produce migration artifacts for containerized environments. Transformation Advisor reports on runtime modernization for moving from traditional WebSphere to Liberty and assists with operational modernization by producing migration artifacts to deploy your workloads in OpenShift. 

When you cannot move an application to Liberty, Transformation Advisor also gives guidance on moving applications to traditional WebSphere containers to at least modernize your operations. Keep in mind that Liberty is the preferred container-ready runtime.


There are several ways to create your Transformation Advisor data collection.
  • You can download a data collector from Transformation Advisor.
  • You can use the binary scanner to create a Transformation Advisor data collection by using the --ta parameter. You can get started by downloading the binary scanner before you install Transformation Advisor. 
  • Starting with WebSphere Application Server, you can use wsadmin to run the data collection that uses the tools that are delivered with WebSphere. 

WebSphere Admin Console

You can analyze applications for their Liberty readiness directly from the WebSphere administrative console when you are running WebSphere Application Server or or higher.  Using the Analyze > Run scanner option, you can start the binary scanner to produce a consolidated migration report that can be exported. To learn more, click through this online demo.

image 4070

Binary Scanner

Transformation Advisor and the WebSphere Admin console use the same binary scanner tool that you can also download and run easily from the command line, so all of these tools produce migration reports that include:
  • Application Technology Evaluation Report
  • Application Inventory Report
  • Detailed Migration Analysis Report
  • Liberty or traditional WebSphere configuration
You can run the binary scanner to produce all 4 reports by default:
  java -jar binaryAppScanner.jar MyApplication.ear
This command creates an Application Migration Report in HTML format. Use the --help option to learn the other options including the JSON format option. From here, we go through each of the reports.

Application Technology Evaluation Report

The Technology Evaluation Report shows the editions of WebSphere Application Server that are best suited to run the application. The report provides a list of Java EE programming models that are used by the application, and it indicates whether the application can be supported by traditional WebSphere or Liberty.


Application Inventory Report

The Inventory Report helps you understand your application contents including the number of modules and the Java EE technologies used by those modules. It also gives you a view of all the utility JAR files in the application that tend to accumulate over time. Potential deployment problems and performance considerations are also included.


As of version, the Inventory Report includes new insights on how to migrate WebSphere Application Server Network Deployment qualities of service to a Kubernetes environment.

image 4173

Detailed Migration Analysis Report

The Migration Analysis Report gives insights to dive in deeper to understand the details of the migration effort. Based on your source and target application server, Java EE levels, and Java SE levels, a set of analysis rules are run against your application binary files. The detailed analysis results give you insight to application issues such as:

  • Java EE differences going back as far as Java EE 6
  • Changes to the Java Runtime Environment (JRE) encountered in going back as far as Java SE 5
  • Removal of previously deprecated features
  • Behavior changes in product APIs
  • Changes resulting from Java EE specification clarifications
  • Deprecated features
  • WebSphere APIs not available on Liberty
  • Optional Java EE technologies not available on Liberty
  • Differences in technology implementations
  • Cloud connectivity considerations
  • Deployment descriptor differences for third-party application servers.

Every issue flagged has a detailed help with useful links to help you mitigate migration issues.



When the application is scanned from a deployed environment or from backup configuration, the tools also produce configuration for deploying to Liberty or traditional WebSphere containerized environments. At a minimum for Liberty, a feature list is created which provides you the set of features needed to run the application. By adding only the features you need, you create a server that is right-sized for the application needs. 


Transformation Advisor Data Collection

The binary scanner can be used to create a Transformation Advisor data collection archive. You can manually upload the data collection into your running Transformation Advisor installation. Using the binary scanner gives you a jump on data collection when you do not have Transformation Advisor already installed. Use the java -jar binaryAppScanner.jar --help --ta command to get started with Transformation Advisor data collection.

Developing with the Source Scanner

After you complete the initial analysis by using Transformation Advisor, the admin console, or the binary scanner, the WebSphere Application Server Migration Toolkit Eclipse plug-in helps developers make the source code changes easier.  You run the same set of rules based on your source and target application server, Java EE levels, and Java SE levels against your application source files including Java, JSP, XML, XMI, and properties files. Where possible, the Eclipse-based tool has quick fixes that you can optionally use to make changes to your code. When a quick fix is provided, you can use a side-by-side compare tool to see and understand the changes being recommended before you apply the fix.

Configure the analysis tool by selecting the Run > Analysis menu. Create a Software Analyzer configuration. Choose the scope of the analysis and select the rules to run. Select the WebSphere Application Server Version Migration Rule Set and click Set to configure the migration rules for your scenario.

The Software Analyzer Results view show the issues found in your code. From the result, you can double-click to open the source code in the editor and view the rule help in the Eclipse Help view.

image 4078
When you want to do more than get your monolith application running on the most modern runtime, IBM Mono2Micro helps you analyze your application gain insights on how to break your monolith into microservices. IBM Mono2Micro uses machine learning to analyze your Java application at the class level based on runtime calls and detected data dependencies (specifically, containment and inheritance relationships). The analysis produces application refactoring options that can be explored and modified through graphs and reports. Mono2Micro has code generation capability to help the initial steps of breaking the monolith apart.
Since Liberty does not support JAX-RPC services or clients, the WebSphere Liberty JAX-RPC Conversion Tool is available to convert JAX-RPC applications to JAX-WS applications that can run on Liberty. This tool runs in Maven or Gradle as part of your build process. There is a validation task and a conversion task. As part of the binary scanner and Transformation Advisor data collection, applications are validated to see whether they are candidates to use this tool. See your analysis reports or Transformation Advisor output to understand whether your applications can take advantage of this tool.
The Eclipse Transformer helps you modernize applications to use the Jakarta EE programming model. Before Jakarta 9, the Java EE programming model uses javax in their package naming. Starting with Jakarta 9, the Jakarta programming model moved to jakarta package naming. The Eclipse Transformer helps you modify either your application source code or your binary archives to use the new package naming. It takes the guess work out of the package rename since some Java SE classes still use javax.
Take advantage of these tools to step through the modernization process with ease.

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"ARM Category":[{"code":"a8m50000000CdIIAA0","label":"Install Update or Migration-\u003ELiberty-\u003ELiberty Migration"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
01 December 2022