Downloading the discovery tool

To get started, complete the following steps from the Transformation Advisor UI:

1. Create a workspace.
2. On the new workspace page, click the Open discovery tool button and follow the instructions to download.

Installing the discovery tool

To install the discovery tool, log on to your application server with the application owner’s user credentials and complete the following steps:

1. Copy the downloaded file to your application system in a directory where it has read-write-execute access.
2. Decompress the downloaded file by issuing the command for your operating system:

Linux: tar xvfz transformationadvisor-Linux_<WORKSPACE_NAME>.tgz

AIX: gunzip -c transformationadvisor-AIX_<WORKSPACE_NAME>.tgz | tar xf -

Solaris: tar xvfz transformationadvisor-Solaris_<WORKSPACE_NAME>.tgz

z/OS: gunzip -c transformationadvisor-zOS_<WORKSPACE_NAME>.tgz | tar xf -

Windows: unzip transformationadvisor-Windows_<WORKSPACE_NAME>.zip

3. Go to the discovery tool directory:

cd transformationadvisor*

Required resources

 System         | Memory (GB) | CPU (cores) | Disk space (GB)
 ---------------| ----------- | ----------- | ---------------
 Discovery tool | 2           | 2           | 0.5

Running the discovery tool

When you run the discovery tool for the first time, the license will be displayed. Accept the terms to continue.

WARNING: The discovery tool should not be run on production servers.

To analyze both your applications and their configuration, run the command for your domain:

IBM WebSphere: ./bin/transformationadvisor -w <WEBSPHERE_HOME_DIR> -p <PROFILE_NAME> [ --ignore-missing-binary --ignore-missing-shared-library --applications --applications-file --skip-applications --skip-applications-file --no-upload] ([] denotes optional arguments)

Oracle WebLogic: ./bin/transformationadvisor --web-logic-config-file <Path to the WebLogic domain config.xml file> [--applications --applications-file --skip-applications --skip-applications-file --no-upload] ([] denotes optional arguments)

JBoss: ./bin/transformationadvisor --jboss-config-dir <Path to the JBoss server configuration directory> [--applications --applications-file --skip-applications --skip-applications-file --no-upload] ([] denotes optional arguments)

Apache Tomcat: ./bin/transformationadvisor --tomcat-home-dir <TOMCAT_HOME_DIR> --tomcat-config-dir <TOMCAT_CONFIG_DIR> [--applications --applications-file --skip-applications --skip-applications-file --no-upload] ([] denotes optional arguments)

To view command line options that are available for the discovery tool, use the --help option.

Viewing your data

Depending on the number, size, and complexity of your applications, the discovery tool may take some time to execute and upload the results. During this process, you can keep track of its progress by checking your command line.

If there is a connection between your system and your new collection, the discovery tool automatically uploads the results to Transformation Advisor. A detailed analysis that includes several reports is provided to help you understand issues and where code changes might be required.

If there is no connection, the discovery tool will return a .zip file containing your application data. You will need to manually upload the zip file using the Upload data button on the Workspace page.

Transformation Advisor discovery tool and Java

The discovery tool requires version 1.7+ to run. In the first instance, the discovery tool will look for a compatible version of Java that is used by WebSphere (if this is a WebSphere collection). If it cannot find the WebSphere Java version, or if the WebSphere version is not compatible (i.e. < 1.7), or this is not a WebSphere collection, then the discovery tool will attempt to use the Java specified in the -–java-home discovery tool argument. If the –java-home argument is not provided, it will use the Java specified with the JAVA_HOME environment variable. If none of those options result in finding a compatible version of Java, the discovery tool will use the Java that is packaged with the discovery tool.

Replacing version of Java in the discovery tool

In some circumstances, a compatible version of Java may not pre-exist on the system that you want to run the discovery tool on, and the Java that is packaged with the discovery tool is also not compatible with the system on which it is being run. For example, this can arise with the Solaris discovery tool which contains Java for AMD64 architecture. If your Solaris is running on SPARC, then the packaged Java will not work. In these cases, you can build your own version of the discovery tool, with an appropriate Java version.

Take the following steps:

• Download a version of that discovery tool via the Transformation Advisor UI
• Unpack the compressed discovery tool
• Locate the “jre” folder in the unpacked discovery tool and replace it with a jre from a desired Java version
• OPTIONAL: There is a file in the unpacked discovery tool called uploadEndpoint.json. This contains the location of the Transformation Advisor server, and a unique key for uploading to a specific workspace. You can remove the uploadEndpoint.json file. This means that the discovery tool will not be able to automatically upload the collection to Transformation Advisor, but rather will produce a zip that you can manually upload using the Transformation Advisor UI. Removing the uploadEndpoint.json has the advantage of allowing you to create a custom discovery tool that can be readily copied between environments. In effect, it breaks the link between the discovery tool and a specific workspace in Transformation Advisor.
• Compress the discovery tool

The compressed discovery tool can now be copied to whatever environment you wish to perform the collection on.

Migrating From SunOS and Solaris architectures

Transformation Advisor provides a discovery tool for SunOS/Solaris environments. It has been tested on SunOS 5.10, 5.11 (Solaris 10, 11), but may work on older versions. The discovery tool provided for SunOS/Solaris packages a JRE for use on SunOS/Solaris on AMD64 architecture. If you want to run the discovery tool on SunOS/Solaris SPARC architecture, then you need to have a compatible version of Java available on the System where you are running the discovery tool.

Known Issues:

• Before running the discovery tool on SunOS/Solaris, please check the version of bash on the environment. If the version is < 4.x, please upgrade to 4.x to ensure correct functioning of the discovery tool.

Migrating from old versions of WebSphere

The Transformation Advisor discovery tool supports collecting from WebSphere v6.1+. For WebSphere migrations from versions older than 6.1, you need to manually find all of the application binaries deployed on the system and put them into some single location. You can then run the discovery tool using the “-o” option to point to that location and perform an analysis on the applications. When you run the discovery tool with the -o options, it will ask you to choose the source WebSphere and Java version. If it does not show your exact versions, select the values that are closest to your actual versions to get the most accurate results. In this situation, the analysis may not catch all issues, issues from version of WebSphere and Java older than the supported rules will not be flagged.

Migrating from supported application servers

Transformation Advisor supports collection from the following application servers:

• WebSphere
• Red Hat JBoss
• Weblogic
• Tomcat.

Migrating from application servers that are not supported

If you want to run an analysis on applications from application servers that are not supported (e.g. Glassfish), you can do the following:

• Manually collect the application binaries from the system, and place in a directory.
• Run the discovery tool and point it at the applications location using the “-c” option. This runs a base set of Java rules plus some Tomcat specific rules. The Tomcat specific rules may or may not apply to the application server that you are analyzing, and need further investigation. In future versions of the discovery tool, there will be the option to just run the generally applicable Java rules. The Tomcat rules that need further investigation are as follows:

Set the sharing scope on resource references
Spring applications might fail to run from a non-expanded WAR file
Stub classes must be included when using remote Enterprise JavaBeans (EJB) 2.x
The getRealPath method previously returned null for files that do not exist
The OSGI remote bundle repository service API is unavailable
The OSGI Remote Service Admin API is unavailable
Transaction propagation is not supported for Enterprise JavaBeans (EJB) remote interfaces
Use correct case for tag attribute names
Use Java EE deployment descriptors and WebSphere bindings to define resource link references
Use Java EE deployment descriptors and WebSphere bindings to define resource references
Use Java EE deployment descriptors to define context lifecycle listeners
Use Java EE deployment descriptors to define context parameters
Use Java EE deployment descriptors to define environment references
Use Java EE deployment descriptors to define missing security roles
Validate the result of concatenation with getRealPath("")
Validate the result of concatenation with getRealPath("/")
Web Services Notification (WS-Notification) is unavailable

Customize the scan options used to generate report files

The customCmd.properties file under the /conf directory is used to config the scan options used to generate the report file during scanning the application. User can edit this file to customize the scan options.

Defining your own rules

Since the release of Transformation Advisor v2.5 you can define your own custom analysis rules to detect scenarios specific to your application migration. The user-defined rules can be easily created as described in detail here. The results will display in Transformation Advisor UI in the same manner as the pre-written rules that come out of the box.

discovery tool command line tool options

app1.ear,app2.ear
app3.ear

app1.ear,app2.ear
app3.ear