Downloading the data collector

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

1. Create a workspace.
2. On the new workspace page, click the data collector button and follow the instructions to download.

Installing the data collector

To install the data collector, 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 data collector directory:

cd transformationadvisor*

Required resources

 System         | Memory (GB) | CPU (cores) | Disk space (GB)
 ---------------| ----------- | ----------- | ---------------
 Data Collector | 2           | 2           | 0.5

Running the data collector

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

WARNING: The data collector 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 data collector, use the --help option.

Viewing your data

Depending on the number, size, and complexity of your applications, the data collector 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 data collector 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 data collector 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 data collector and Java

The data collector requires version 1.7+ to run. In the first instance, the data collector 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 data collector will attempt to use the Java specified in the -–java-home data collector 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 data collector will use the Java that is packaged with the data collector.

Replacing version of Java in the data collector

In some circumstances, a compatible version of Java may not pre-exist on the system that you want to run the data collector on, and the Java that is packaged with the data collector is also not compatible with the system on which it is being run. For example, this can arise with the Solaris data collector 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 data collector, with an appropriate Java version.

Take the following steps:

• Download a version of that data collector via the Transformation Advisor UI
• Unpack the compressed data collector
• Locate the “jre” folder in the unpacked data collector and replace it with a jre from a desired Java version
• OPTIONAL: There is a file in the unpacked data collector 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 data collector 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 data collector that can be readily copied between environments. In effect, it breaks the link between the data collector and a specific workspace in Transformation Advisor.
• Compress the data collector

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

Migrating From SunOS and Solaris architectures

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

Known Issues:

• Before running the data collector 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 data collector.

Migrating from old versions of WebSphere

The Transformation Advisor data collector 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 data collector using the “-o” option to point to that location and perform an analysis on the applications. When you run the data collector 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 data collector 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 data collector, 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.

data collector command line tool options

app1.ear,app2.ear
app3.ear

app1.ear,app2.ear
app3.ear