How to collect data

Using the Discovery Tool

The Discovery Tool is a tool that gathers information about middleware deployments in your environment to help IBM Application Modernization Accelerator provide you with a migration analysis of Java™ EE applications running on IBM WebSphere Application Server, Apache Tomcat, Red Hat JBoss, or Oracle WebLogic application servers. The tool generates one .zip folder per profile/domain and places analysis results within that directory.

For Java applications, the tool leverages the Migration Toolkit for Application Binaries. You may use the Migration Toolkit for Application Binaries (AKA the "binary scanner") directly. This may be particularly useful in some troubleshooting scenarios. For information on how to download and use the Migration Toolkit for Application Binaries please click here. If these tools are already in use, then the same security requirements which are required to run them are also required to run the Discovery Tool.

The Discovery Tool will collect configuration information on WebSphere Application Server installations at Version 6.1 or later. The exact configuration information that is collected can be found here.

To analyze your applications, the Discovery Tool requires the following access:

• Read access to the application server installation directory and all subdirectories
• Read access to profile directories
• File and directory creation and write access to the current directory

The Discovery Tool does not gather any data related to the following:

• Message content or data processed by workload
• Logs or log data
• Password information

Downloading the Discovery Tool

To get started, complete the following steps from the Application Modernization Accelerator 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 with read, write, and execute access.
2. Decompress the downloaded file by issuing the command for your operating system:

   Linux: tar xvfz DiscoveryTool-Linux_<WORKSPACE_NAME>.tgz
    AIX: gunzip -c DiscoveryTool-AIX_<WORKSPACE_NAME>.tgz | tar xf -
    Solaris: tar xvfz DiscoveryTool-Solaris_<WORKSPACE_NAME>.tgz
    z/OS: gunzip -c DiscoveryTool-zOS_<WORKSPACE_NAME>.tgz | tar xf -
    Windows: unzip DiscoveryTool-Windows_<WORKSPACE_NAME>.zip

3. Go to the Discovery Tool directory:

   cd ama-discovery*

4. (z/OS only)
   Go to the Discovery Tool bin directory and run the z/OS prerequisite script:

   cd ama-discovery*/bin
   . zOSPrereq
    

Required resources

Running the Discovery Tool

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

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

IBM WebSphere: ./bin/ama-discovery -w <WEBSPHERE_HOME_DIR> -p <PROFILE_NAME> [ --ignore-missing-binary --ignore-missing-shared-library --applications --applications-file --skip-applications --skip-applications-file --no-upload]
 Oracle WebLogic: ./bin/ama-discovery --web-logic-config-file <Path to the WebLogic domain config.xml file> [--applications --applications-file --skip-applications --skip-applications-file --no-upload]
 JBoss: ./bin/ama-discovery --jboss-config-dir <Path to the JBoss server configuration directory> [--applications --applications-file --skip-applications --skip-applications-file --no-upload]
 Apache Tomcat: ./bin/ama-discovery --tomcat-home-dir <TOMCAT_HOME_DIR> --tomcat-config-dir <TOMCAT_CONFIG_DIR> [--applications --applications-file --skip-applications --skip-applications-file --no-upload]

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 Application Modernization Accelerator. 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.

Application Modernization Accelerator 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 Application Modernization Accelerator 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 Application Modernization Accelerator 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 Application Modernization Accelerator, but rather will produce a zip that you can manually upload using the Application Modernization Accelerator 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 Application Modernization Accelerator.
• 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

Application Modernization Accelerator 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 Application Modernization Accelerator Discovery Tool supports collecting from WebSphere Version 6.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

Application Modernization Accelerator 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 Application Modernization Accelerator 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 Application Modernization Accelerator UI in the same manner as the pre-written rules that come out of the box.

Discovery Tool command line tool options

General options

--version

Displays the version of the Discovery Tool.

--help

Displays all options for the Discovery Tool.

--java-home

Specifies the version of Java used for the Discovery Tool.

-J-X

JVM options that are passed to the Discovery Tool. “-J” will be stripped and “-X” and remaining options will be passed to the Java runtime. For example, “-J-Xmx4G” will set the max heap size to 4 GB for the Discovery Tool runtime.

--no-upload

Flag to indicate that no upload to Application Modernization Accelerator server will take place once the collection completes.

Using the built-in WSADMIN command for WebSphere Application Server

The wsadmin command available with WebSphere has a built-in option for scanning your installed applications and generating a set of zip files that can be uploaded directly into Application Modernization Accelerator.

The availability of this command depends on the WebSphere version and Fix Pack you are running:

• WebSphere 8: Version 8.5.5.23 or later
• WebSphere 9: Version 9.0.5.14 or later

For more information and instructions, see Create and manage a Transformation Advisor data collection.

Using the Migration Toolkit for Application Binaries

An alternative to using the Application Modernization Accelerator Discovery Tool is to use the Migration Toolkit for Application Binaries to generate a data collection that can be uploaded to IBM Application Modernization Accelerator.

For more information on how to do this, see Transformation Advisor Data Collection.