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 Java EE 8 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 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, here is a comparison of the capability available in our tools:

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.


WebSphere Admin Console

You can analyze applications for their Liberty readiness directly from the WebSphere administrative console when you are running WebSphere Application Server version 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. 


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.
Take advantage of these tools to step through the modernization process with ease.

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"ARM Category":[{"code":"a8m50000000CdIIAA0","label":"Install Update or Migration->Liberty->Liberty 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:
14 October 2021