Frequently Asked Questions when using IBM Transformation Advisor

Discovery tool

How do you exclude large files to improve the discovery tool execution time?

  1. Find the customCmd.properties in the ./transformationadvisor-{version}/conf directory.

  2. Update the customCmd.properties file with the files you wish to exclude. For example: --excludeFiles='.*/largeFile.xml'

  3. Run the discovery tool.
    Note: The log files will show the files that are being excluded.

How do you enable verbose logging for the binary scanner?

You can enable verbose logging for the binary scanner tool that the discovery tool runs. Verbose logging is available in trace files which are generated in the directory where you run the discovery tool. To enable verbose logging, use the --verbose option on the command line.

For example:

./bin/transformationadvisor     
-w /opt/IBM/WebSphere/AppServer/    
-p AppSrv01 admin    
--verbose

When I have multiple versions of the same .EAR deployed, why do I only see one in the analysis table?

If there are multiple versions of the same application on your WebSphere server the discovery tool will only scan and provide analysis results on one of those versions.

How do I define a customer SOAP Timeout for an execution?

  1. Copy the soap.client.props file from <PROFILE_ROOT>/properties into the discovery tool configuration directory.
  2. IMPORTANT: Update the name of the soap.client.props file to: tasoap.client.props
  3. Edit tasoap.client.props and update the value of com.ibm.SOAP.requestTimeout as required.
  4. Rerun the discovery tool.

How do I increase the system default for SOAP timeout?

  1. Find the <PROFILE_ROOT>/properties/soap.client.props file.
  2. Increase the value for the property com.ibm.SOAP.requestTimeout
    Note: If you set the value to 0 there will be no time limit.
  3. Rerun the discovery tool.

How can I set the heap size in the discovery tool when there is an Out of Memory issue?

You can use the -J-Xmx option in the command line to customize the maximum heap size used by discovery tool. For example, to set the maximum heap size to 2 GB:

./bin/transformationadvisor -J-Xmx2G -w /opt/IBM/WebSphere/AppServer/ -p AppSrv01 admin

How do I scan a Custom Profile?

Transformation Advisor will automatically find your custom profiles if you supply the correct profile name. If for some reason this is not working, you can create a symbolic link from the profiles directory in WAS_HOME to the location of the custom directory using this command:

ln -s <CUSTOM_PROFILE_LOCATON>/<CUSTOM_PROFILE_NAME> <WAS_HOME>/profiles/<CUSTOM_PROFILE_NAME>

For example:
A custom profile called appProfile has been created outside of WAS_HOME:

ln -s /was7/appProfile/ /ibm/was/profiles/appProfile

Can you run the discovery tool with a specific JRE?

By default, the discovery tool automatically determines which version of Java to use based on the following rules:

  1. If collecting from a WebSphere Application Server, the version of Java that is installed with the WebSphere Application Server will be used.

If you are not collecting from a WebSphere Application Server:

  1. The version of Java that is on the path will be used.
  2. If there is no version on the path, then the version of Java that is shipped with the discovery tool will be used.

If you want to use a specific JRE for the discovery tool, you can include a --java-home option in the command. This option will override the defaults outlined previously. For example:

./bin/transformationadvisor --java-home /opt/ibm/java-x86_64-80
-w /opt/IBM/WebSphere/AppServer/
-p AppSrv01 admin

Does Transformation Advisor use the version of Java provided by the WebSphere Application Server installation?

The discovery tool will attempt to use the Java version that is provided by the WebSphere Application Server. If for some reason it is unable to do so then it will use the version that is packaged with it. In any situation where that will not work, you can copy in your local JRE by replacing the JRE directory under transformationadvisor-2.1 with the JRE directory that the WebSphere Application Server is currently using, which is found in the WebSphere Application Server machine.

What exactly are ‘Collections’ and how should I name them?

You can name collections anything that you find helpful to organize work under your workspace.

For example, a WebSphere Application Server can have many profiles. Each of these profiles may have many applications. So when you run the discovery tool against a WebSphere Application Server, you will potentially get multiple applications for each profile, from just one server.

You may also have more than one server in total. So you could name the collection the same name as the WebSphere Application Server that you are scanning and under that collection you will then have the multiple profiles and applications for the server on which you ran the discovery tool.

How can I scan my profile if it is not in WAS_Home?

If for example the profile name is AppSrv010 and it is under /root/was_profile, you can create a symbolic link to the profile as follows:

ln -s /root/was_profile /opt/IBM/WebSphere/AppServer/profiles/AppSrv010

What can I do if the server restarts while data is uploading on Transformation Advisor LOCAL?

If the server restarts while data is uploading it could indicate the zip file is large and the server needs more memory:

Increase the memory resource in Docker Desktop from 8GB to 12GB

How do I use customized commands for the binary scanner?

Customized commands for the binary scanner can be issued by using the customCmd.properties file in the conf directory. There is a different command for each report.

The value of java_opt is used to customize the JRE runtime for every binary scanner command. By default, all the commands are commented out. You can uncomment the commands which you want to customize.

The discovery tool uses the complete command when generating that specific report. If any of the custom command options are incorrect, the discovery tool will stop executing and throw an error.

Guidelines for writing the custom commmand options

  1. Don't specify the --format option. The Transformation Advisor server expects both html and json formats for each report. Generating only one report format may introduce errors while uploading and presenting the results.

  2. Don't specify the --output option. The Transformation Advisor server expects file names in a certain order. Also, specifying this option may change the location of reports storage which may cause problems while zipping up and uploading the results.

  3. If an option needs a path as its value then always surround the paths with double quotes: path="c:\\docs\\doc1"

  4. The backslash character must be escaped as a double backslash: path="c:\\docs\\doc1"

How do I collect data for a large set of applications on WAS?

If there are more than 100 applications deployed on multiple WebSphere Application Server profiles, you can invoke multiple discovery tool processes, one for each profile.

If there are more than 100 applications deployed on the same WAS profile, you can use the --applications option which will take a list of application names or the --applicationsFile option which will read the application names from a file.

Can I upload data collected using the Migration Toolkit for Application Binaries?

Yes, an alternative to using the Transformation Advisor Discovery tool is to us the the Migration Toolkit for Application Binaries to generate a data collection that can be uploaded to IBM Transformation Advisor. Details of how to do this are outlined here.

Where can I find out more about the binary scanner and the server configuration files generated?

You can find out more about the binary scanner at https://www.ibm.com/docs/wamt. For more information on the binary scanner generated configuration files see https://www.ibm.com/docs/wamt?topic=binaries-configuration-migration

General

What versions of WebSphere Application Server can Transformation Advisor support?

Version 7+. On version 6.1, the discovery tool can scan the binaries and provide an analysis, but cannot get the configuration and create a migration bundle for you.

Should I use Nodeports to expose my endpoints in a production configuration?

Nodeports are a simple way of exposing external access to a workload for initial development and testing but they expose additional security concerns and are hard to manage from both an application and networking infrastructure perspective. We would recommend you use Routes when deploying on Red Hat OpenShift Container Platform and Ingress on IBM Cloud Private.

What does support for JBoss and WebLogic mean?

The Transformation Advisor discovery tool scans for known issues in applications that are migrated from WebLogic Servers and JBoss Application Servers to WebSphere Application Servers. Where possible, a quick fix is suggested to change your code to a more portable solution.

You can use the quick fix to help you decide if you want to accept the suggested code change. Also, view the help information provided with the complexity rules to decide if you want to run the quick fix. Always make a backup copy of your source code before you start a migration.

For some rules, the scan detects code that requires design changes and code rewrites. The tools highlight these problem areas but do not provide a quick fix.

What versions of WebLogic can Transformation Advisor support?

Transformation Advisor supports runtime migrations from these Java EE servers:

  • WebLogic Server 6.x – 11.x to Liberty or Full profile
  • WebSphere Application Server V7.0 (and later) to Liberty or Full profile

Is it possible to upload the Transformation Advisor results zip file using a REST call?

Yes, you can use the curl command:

curl -X 'POST' -H 'accept: /' -H 'archiveName: <zip file>' -H 'locale: en' -H 'Content-Type: application/octet-stream'     
'http://<host>:<port>/lands_advisor/advisor/v2/workspaces/{workspaceId}/collectionArchives?overwrite=true'     
--data-binary "@/<path-to-file>/<zip file>"

Does Transformation Advisor provide anti-virus scan?

No. Please ensure all the uploading files are trusted, or pre-scanned by an anti-virus software.

Does Transformation Advisor send any data to external sites?

No. Transformation Advisor does not automatically send any data to external sites. However, when you access the Transformation Advisor landing page, the system checks for the latest available version. This check does not transmit any user data. It only retrieves the latest version number and displays a notification if an update is available.

Why Transformation Advisor UI's logout does not work after I upgrade to OpenShift Container Platform 4.6?

It is a known issue introduced by OpenShift Container Platform 4.6. More info at Secure OAuth token storage format.

Transformation Advisor users on OpenShift Container Platform can revoke the access tokens manually by following steps in the terminal:

  1. Assumed you have permissions to access OCP via terminal with oc login command and the following commands,

  2. Get Transformation Advisor's oauthclient name:

     > oc get oauthclient -l=app.kubernetes.io/name=ta-oauth

 NAME                                       SECRET                                     WWW-CHALLENGE   TOKEN-MAX-AGE   REDIRECT URIS
 ca5282946fac07867fbc937548cb35d3ebbace7e   94b6cbce793d0606c0df9e8d656a159f0c06631b   false           default         https://ta.apps.example.ibm.com/auth/callback

    ta-oauth is in the format of { .Release.Name }-oauth. Please update the release name accordingly, if necessary.

    The output name ca5282946fac07867fbc937548cb35d3ebbace7e is the Transformation Advisor oauthclient name, which will be used in the next command.

  3. Get a list of access tokens under the oauthclient name:

     # change the name ca5282946fac07867fbc937548cb35d3ebbace7e accordingly

 > oc get oauthaccesstokens | grep ca5282946fac07867fbc937548cb35d3ebbace7e | awk '{print $1}'

 # sample outputs
 sha256~-g-vg5YGGyYPp_TMKvcuGTatbwq6wklkrxY7ai49DYU
 sha256~037FDmgjT5eTNVNSAeGzMAWqzsEvNeLItFAR_FLiEFQ
 sha256~0vTcCQFaJDEZbVCBD_RpvOMA-ZO5yRIHAJH6DGEq3QY
 ...

  4. Delete each of the token:

     > oc delete oauthaccesstokens sha256~-g-vg5YGGyYPp_TMKvcuGTatbwq6wklkrxY7ai49DYU

 oauthaccesstoken.oauth.openshift.io "sha256~-g-vg5YGGyYPp_TMKvcuGTatbwq6wklkrxY7ai49DYU" deleted

 > oc delete oauthaccesstokens sha256~037FDmgjT5eTNVNSAeGzMAWqzsEvNeLItFAR_FLiEFQ

 oauthaccesstoken.oauth.openshift.io "sha256~037FDmgjT5eTNVNSAeGzMAWqzsEvNeLItFAR_FLiEFQ" deleted

 > oc delete oauthaccesstokens sha256~0vTcCQFaJDEZbVCBD_RpvOMA-ZO5yRIHAJH6DGEq3QY

 oauthaccesstoken.oauth.openshift.io "sha256~0vTcCQFaJDEZbVCBD_RpvOMA-ZO5yRIHAJH6DGEq3QY" deleted

    This step will revoke all the access tokens under the oauthclient name. In other words, it will also log out other users. This is due to there is no publicly known way to which token a certain user belong to in OpenShift Container Platform 4.6