IBM Support Assistant Lite for Rational ClearQuest v7.1

This package contains the following data collection options:

Rational ClearQuest
General

• Installation Manager Collector

• General Change Management Server Collector
• Server Configuration Collector
• Server Processes Trace Collector

• ClearQuest Client Trace Collector

Details of what is collected as well as collector walk through are described below.

Prerequisites

Downloading and Launching ISA Lite

Using ISA Lite

General Collectors

Server Collectors

Client Collectors

Details: ClearQuest Client Trace Collector

Data Collector Completion Options & Uploads

Prerequisites

• You need an IBM ID and password to download ISA Lite. Register here if you do not already have one.
• You need Java JRE 1.4.2 or greater on your machine to run ISA Lite

1. Download ISA Lite for Rational ClearQuest V7.1 from: https://www.ibm.com/services/forms/preLogin.do?source=swg-isalite&S_PKG=isal131rcq
2. Extract the .zip file in a folder.
   • If your platform does not have unzip utility, you can use jar to unzip file: jar xf ISALiteforRationalClearQuest_7.1_20091016.zip
3. In the same folder, cd ISALite

Windows:
1. If Java is available in your path , simply run: runISALite.bat
2. If Java is not available on your path, you'll need to set JAVA_HOME first:
   • set JAVA_HOME=<your full path to Java> This path should point to the bin directory in your Java installation, containing java.exe. No quotes.
   • Example: set JAVA_HOME=C:\Program Files\IBM\RationalSDLC\common\JAVA5.0\jre
   • Once this is completed, run: runISALite.bat

Linux / Unix
1. If Java is not available on your path, you'll need to set JAVA_HOME first:
   • (in ksh) export JAVA_HOME=<your full path to Java> This path should point to the bin directory in your Java installation, containing java
   • Example: export JAVA_HOME=/opt/rational/common/java/jre
2. You may need to execute : chmod a+x *.sh to ensure .sh files in ISALite folder can be executed.
3. If you are running in a desktop environment: run: ./runISALite.sh
4. If you are running in a console / terminal environment, run: ./runISALiteConsole.sh

Back to top

1. Select a data collector to run.
2. Fill in the Output Filename field.
3. Click the Collect Data button to start data collection.
4. When finished, simply close the window.

Back to top

General Collectors

These are the set of collectors that deals with general ClearQuest issues.

Installation Manager Collector
Use this collector for general IBM Installation Manager issues. This can be used to collect information when running into install issues on products that leverages IBM Installation Manager as an install platform.
• Detailed description : Installation Manager Collector

Back to top

These are the set of collectors that is use with the Change Management Server.

General Change Management Server Collector
Use this data collector to gather information for general issues relating to change management server . This includes change management server configuration, IBM Installation Manager as well as information related to embedded WAS. Its recommended that you run this with administrator privileges.
• Detailed description: General Change Management Server Collector

Server Configuration Collector
Use this data collector to gather only change management server configuration information.

• Detailed description: Server Configuration Collector

Server Processes Trace Collector
Use this data collector to enable process trace on the Change Management Server. User will be prompted to recreate the server issue found, and when completed, to continue with the data collection tool to disable trace settings and gather information. Its recommended that you run this with administrator privileges. This data collector WILL restart your Change Management Server to enable and disable trace settings.
• Detailed description: Server Processes Trace Collector

Back to top

This is the collector that is to be used with issues with ClearQuest web client.

ClearQuest Client Trace Collector
This data collector is used for gathering Change Management API trace data relating to ClearQuest client issues. The collector will first determine the location of the ClearQuest Client from Installation Manager (clearquest.exe or clearquest), and determine the JDK used. The collector will enable trace settings and prompt the user to recreate problems encountered. When user completed error reproduction, continue with the data collection so that collector will reset appropriate trace settings and collect data.
• Details below: ClearQuest Client Trace Collector

Back to top

CM API Trace settings:
• File modified: <JDK found>/lib/logging.properties
• Settings to enable trace:
  com.ibm.rational.stp.common.internal.util.CMLogger.level = INFO
  com.ibm.rational.stp.common.internal.util.LogHandler.pattern = %h/CMLogger%g.log
  com.ibm.rational.stp.common.internal.util.LogHandler.limit = 20000000
  com.ibm.rational.stp.common.internal.util.LogHandler.count = 20
  com.ibm.rational.stp.common.internal.util.LogHandler.append = true
  com.ibm.rational.stp.common.internal.util.LogHandler.formatter = java.util.logging.SimpleFormatter
  com.ibm.rational.stp.common.internal.util.CMTracer.level = FINER
  com.ibm.rational.stp.common.internal.util.TraceHandler.pattern = %h/CMTracer%g.log
  com.ibm.rational.stp.common.internal.util.TraceHandler.limit = 20000000
  com.ibm.rational.stp.common.internal.util.TraceHandler.count = 20
  com.ibm.rational.stp.common.internal.util.TraceHandler.append = true
  com.ibm.rational.stp.common.internal.util.TraceHandler.formatter = java.util.logging.SimpleFormatter
• Settings to disable trace:
  com.ibm.rational.stp.common.internal.util.CMTracer.level = OFF

IMPORTANT: The tool updates logging.properties of the JDK used for the web client to enable / disable trace.
• JDK is searched in following order: -vm from product.ini file , <product_install>/jdk/jre. If these does not result in a valid JDK, user will be prompted.
• You'll need to run this collector with appropriate access as it modifies the logging.properties file which may have access restrictions.

This data collector only executes if ClearQuest Client is found via information stored with Installation Manager.



Folder	File	Description
/enable_settings
	cmapi_enableLogging.properties	(Only if valid VM is found) Attributes used to to enable trace in logging.properties file.
	logging.properties.<timestamp>	(Only if valid VM is found) Backup file of the existing logging.properties file
	logging.properties	(Only if valid VM is found) New logging.properties file. This should have logging.properties with trace enabled.
/disable_settings
	cmapi_disableLogging.properties	(Only if valid VM is found) Attributes used to disable tracing from logging.properties file
	logging.properties	(Only if valid VM is found) New logging.properties file. This should have logging.properties with trace disabled.
/USER_HOME
	CMTrace*.log, CMLogger*.log	Trace and logging data that's found in ${user.home}.

Detailed Walk Thru for "ClearQuest Client Trace Collector"

Introduction

The collector will first inform you what it is going to collect. Click OK, to proceed

Select JDK you are using

If the collector cannot determine this information from the ClearQuest Client information on the system, you'll need to specify the JDK you are using manually.
Please specify the full path that contains a bin and a lib directory.

Here all the setup are completed, and the tool prompts you to recreate the problem. Please re-start the ClearQuest Client to ensure the log and trace settings are picked up by the JVM.

When you've completed re-creating the problem, please exist ClearQuest Client.

Click OK to continue. This will disable trace settings and collect trace and workspace data.


The collector will run to completion and request feedback and ftp options.

Please continue to Data Collector Completion Options & Uploads for additional information.

Back to top

Data Collector Completion Options & Uploads

When the collector is completed, it will request feedback about ISA. Select Yes, to provide feedback. Select No to continue.

You'll also be provided with data upload options. This will allow you to send the collected data to IBM or another location via FTP or HTTPS.

IMPORTANT: To upload information to IBM, you'll need to have a PMR number. This is obtained when you work with our support team. If you do not have a PMR number, but do have support contract, you can leverage the Software Support page to open a service request and included the collected data with the service request.
IBM Service Request Page: https://www.ibm.com/support/servicerequest/

The upload options are:

• Send the Logs to IBM using secure transfer (HTTPS). You'll need an PMR number to transfer the data to IBM. This sends the collected data to IBM Support team through the HTTPS protocol.
• FTP the Logs to IBM Support (unencrypted). You'll need an PMR number to transfer the data to IBM. This sends the collected data to IBM Support team through the FTP protocol. This is a less secure option.
• FTP the Logs to a Different Location (unencrypted) This allows you to send the collected data to another location via FTP. You'll need to provide the target FTP location and appropriate authentication to access it.
• Do Not FTP the Logs. Do nothing.

When the collector completes, the .zip file is created at the location specified in Output File name. You can use any unzip tool to extract the files to examine the content of collected data.