Transformation Advisor Data Collection

The Migration Toolkit for Application Binaries can generate a data collection to be uploaded to IBM Cloud Transformation Advisor, where you can gain application modernization insights including common code discovery, application migration complexities, and estimate development costs as well as produce migration artifacts for containerized environments. Using the --ta action directs the Migration Toolkit for Application Binaries to generate Transformation Advisor compatible files which allow Transformation Advisor to report on runtime modernization for moving from traditional WebSphere to Liberty and to assist with operational modernization by producing migration artifacts to deploy your workloads in OpenShift and other Kubernetes environments. Using the Migration Toolkit for Application Binaries allows you to start gathering data before you have Transformation Advisor installed. For more information on Transformation Advisor, see IBM Cloud Transformation Advisor.

Avoid trouble: While uploading a Transformation Advisor data collection use Transformation Advisor 3.2 or a later version.

A Transformation Advisor data collection consists of one or more zip archives containing all the data needed for Transformation Advisor to provide insights on applications and related shared libraries. These archives include the analysis, inventory, and evaluation reports in both HTML and JSON formats as well as the relevant configuration files. The reports are produced for WebSphere Liberty, Open Liberty, and WebSphere traditional base in containers migration targets.

When using the --ta action, the only required parameter is the binaryInputPath, which is an absolute or relative path to a WebSphere traditional installation directory, an application binary file, or a directory that contains application binary files outside of a WebSphere installation environment. If the binaryInputPath points to a WebSphere traditional installation, server configuration is generated which is included in the Transformation Advisor set of migration artifacts.

When a WebSphere traditional installation is specified, use the --profile option to specify a comma-separated list of the profiles to scan. If no profile is specified, the default profile is scanned.

When scanning a single application or folder of applications outside of a WebSphere traditional installation, the --sourceAppServer and --sourceJava options are required.

It is recommended to identify your custom application class packages with the --includePackages option. By doing so, you avoid scanning Java EE and third-party packages which should not affect your migration effort. If no --includePackages or --excludePackages options are specified, the tool excludes Java EE and some third-party packages by default. These packages are identified as scan options near the beginning of the generated reports.

Tip: The --ta action is only applicable to generating Transformation Advisor data collections for traditional WebSphere Application Server applications. Continue to use the data collector downloadable from Transformation Advisor for Tomcat, JBoss, and WebLogic application analysis.
Run commands from the wamt directory in your Migration Toolkit for Application Binaries installation. For a complete list of supported options for evaluating your application, run the following command:
java -jar binaryAppScanner.jar --help --ta

The following examples demonstrate different ways to generate Transformation Advisor data collections using the command options.

  • Run the following command to generate the Transformation Advisor data collection for the default WebSphere profile installed at /opt/ibm/WebSphere/AppServer.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta
  • To explicitly specify which profiles to scan, use the --profile parameter to specify one or more comma-separated profile names where /opt/ibm/WebSphere/AppServer is the traditonal WebSphere installation path. Without the --profile parameter, only the default WebSphere profile is scanned.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=Dmgr01
  • To control which applications are included in or excluded from a data collection, you can use one of the four options --includeApplications, --includeApplicationsFile, --excludeApplications, or --excludeApplicationsFile.
    The --includeApplications option accepts a comma-separated list of applications to include in the scan. All other applications are skipped. For example, only App1.ear and App2.ear are scanned with this command.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=Dmgr01 --includeApplications=App1.ear,App2.ear
    Similarly, the --excludeApplications option accepts a comma-separated list of applications to omit from the scan. All other applications are included. For example, App1.ear and App2.ear are excluded from the scan using this command.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=Dmgr01 --excludeApplications=App1.ear,App2.ear
    The --includeApplicationsFile and --excludeApplicationsFile options provide similar functionality as --includeApplications and --excludeApplications. Add the applications to include or exclude to a text file and provide the path to the file on the command. The contents of the text file can have lines with comma-separated application names, or they can be entered one application per line. For example, includeApps.txt contains the following lines to include App1.ear and App2.ear.
    The applications are included with the following command.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=Dmgr01 --includeApplicationsFile=includeApps.txt
  • To save the data collection files to a specific location, specify the --output parameter with a directory.
    For example, the following command scans two profiles and saves the results to the /MyScanResultsDir directory.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=AppSrv01,AppSrv02 --output=/MyScanResultsDir
  • Applications can be scanned outside of a traditonal WebSphere installation. However, in this mode, only a Liberty feature list is created in the server.xml file, and no additional server configuration is generated. In this example, the single application /MyAppDir/MyApp.war is scanned. The required --sourceAppServer and --sourceJava parameters should reflect the environment where this application is running.
    java -jar binaryAppScanner.jar /MyAppDir/MyApp.war --ta --sourceAppServer=was855 --sourceJava=ibm8
  • To specify user-defined rules, specify the --userRuleLocation parameter with the directory containing your rule definitions and lists. For more information on creating user-defined rules, see User-Defined Rules.
    For example, the following command runs the user-defined rules along with the rules for migrating from WebSphere traditional to Liberty.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=Dmgr01 --userRuleLocation=/path/to/rules
  • By default, the binary scanner will continue and analyze the application binaries available. To stop processing the data collection if an application binary is missing or cannot be created from its expanded application, specify the --stopOnMissingBinary option.
    For example, the following command will stop if an application binary is not found
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=Dmgr01 --stopOnMissingBinary
  • By default, the binary scanner will analyze the shared libraries available and continue to run if shared libraries cannot be found. To stop processing the data collection if shared library files are missing from the deployment manager being scanned, specify the --stopOnMissingSharedLibrary option. If you deploy custom application code in shared libraries, it is important to analyze shared libraries to get the full understanding of your application estate. If shared libraries are only available on the server node rather than the deployment manager, you can scan the server profile instead.
    For example, the following command will stop if a shared library is not found or points to an empty folder.
    java -jar binaryAppScanner.jar /opt/ibm/WebSphere/AppServer --ta --profile=Dmgr01 --stopOnMissingSharedLibrary