Introduction

The WebSphere Commerce automated data collectors have been created within the WebSphere Commerce plug-in for the IBM Support Assistant (ISA). The tool collects relevant information for a problem scenario to help understand the root cause of the problem faced by a client. These collectors will benefit clients by reducing the time and effort required to gather the data required by the IBM Support team when working on a problem management record (PMR), as often described by a WebSphere Commerce MustGather technical document.

The tool automatically collects data for a particular problem type within WebSphere Commerce. It automatically enables runtime tracing with the required trace strings and extracts data from the database and files from the file system. This data is automatically uploaded to the IBM FTP system, which ties it to an existing PMR.

These actions taken by the collector are determined using ActionXML and the XML configuration file with a sequenced list of tasks to be invoked. The WebSphere Commerce automated data collectors are also referred to as the “ActionXML Collectors”.

The tool also performs some initial analysis of the problem based on symptoms found in the server traces and logs, trying to correlate known issues previously encountered by other clients or IBM Support. The tool also helps clients by reducing the time and effort, while improving accuracy and completeness in gathering data and reproducing a problem.

This article will describe how to use the collector and how to configure for special scenarios.

Back to top

Installing the collectors

The automated data collectors for WebSphere Commerce are implemented as a plug-in within the IBM Support Assistant framework.

Installation of the plug-in is handled via the ISA Eclipse framework. An update site is used to download the WebSphere Commerce plug-in that contains the collectors. With respect to the ISA Lite version of the collector, you can download this from the web. It requires that the JAVA_HOME parameter be set into the environment variables.

To enable the automated data collectors, you need to install the WebSphere Commerce plug-in within the IBM Support Assistant workbench. The following steps achieve this:

1. Download and install the IBM Support Assistant workbench.
2. When the ISA workbench is launched, add the WebSphere Commerce plug-in by selecting Update > Find New > Product Add-ons.
3. Expand the WebSphere checkbox and scroll down to select WebSphere Commerce v7.0.
4. Click Finish and restart the ISA workbench.

Complete instructions for installing the IBM Support Assistant and downloading the WebSphere Commerce plug-in are found in Installing and starting the IBM Support Assistant.

Back to top

Starting the collection

There are several ways to begin a collection using the ActionXML collector. The main framework for invoking a collection is the IBM Support Assistant Workbench, or the ISA Lite utility. These will be explained in the following sections.

ISA Workbench (interactive mode)

The standard way to invoke the WebSphere Commerce automated data collectors is to use the IBM Support Assistant Workbench.

1. Once the ISA Workbench is launched, click the Home tab, then Collect and Send Data, or Launch Activity, then select Collector and Send Data.
2. Under the Collector Selection, expand WebSphere Commerce 7.0 to see the list of collectors available for WebSphere Commerce. Expand the subcategory (component) and select the desired collector, click Add>> to add to the Collector Queue. Finally, select Collect All to begin the collection.

This collection walks you through a series of prompts that include the following:

• WebSphere Commerce install directory
• WebSphere Commerce instance name (if it detects it is a runtime)
• WebSphere Application Server install directory
• WebSphere Application Server profile (if more than one is detected)
• WebSphere Application Server server (if more than one is detected)
• Consent for any component requiring it (for example, GatherTrace, GatherSQL)
• File name for the archive to create
• FTP options

ISA Lite (UI interactive mode)

ISA Lite is a self-contained package that you can export from the ISA Workbench, and then extract on any WebSphere Commerce environment to run a collection.

1. To export the WebSphere Commerce collectors to ISA Lite package, select the link from the diagram as shown in Figure 1 in the left panel of the ISA Workbench.
   
   Figure 1. ISA Lite export
   
   
   
2. On the panel that appears on the right, select WebSphere Commerce 7.0 from the Select a collector dropdown menu. Enter the target directory for the collector and the name of the zip. You can reuse this on any WebSphere Commerce install on Windows®, Linux, AIX®, or Solaris®.
   
   Figure 2. ISA Lite export detail
   
   
   
3. Unzip the exported IBM Support Assistant Lite collector, set up JAVA_HOME, and execute the runISALite.bat (Windows) or runISALite.sh(UNIX/LINUX) script from the tool's ISA Lite directory on the remote system. Provide responses to any collection prompts.

The IBM Support Assistant Lite Collector collects the appropriate information and files into a collection archive file. You can transfer the file back to the IBM Support Assistant Workbench and import it into a case for analysis with various tooling, or send it to the third party, such as IBM Support, for analysis.

The interactions with ISA Lite are the same as those as the ISA Workbench in an interactive mode described earlier. Figure 2 shows ISA Lite running on Windows.

ISA Lite (command-line console using interactive mode)

1. Export the collector to ISA Lite as before.
2. The ISA Lite Console mode provides interactive prompts from the command line, rather than from the Java UI mode.
3. Unzip the exported IBM Support Assistant Lite collector, set up JAVA_HOME, and run the runISALiteConsole.bat (Windows) or runISALiteConsole.sh(UNIX/LINUX) script from the tool's ISA Lite directory on the remote system. Provide responses to any collection prompts, as shown in Figure 4.
   
   Figure 4. ISA Lite console
   
   
   

ISA Lite (command-line console with a response file)

One additional usage is available when using ISA Lite compared to the ISA Workbench: script input mode (silent mode). You can use it to automate collections without any user interaction. This avoids additional prompts that appear in the ISA Lite console mode with the Quick Collect mode.

You can run the ISA Lite tool in script input mode, in which the tool receives input from a response file rather than from a user interaction. To run in this mode, you first need to execute the following command, using the –record option, which stores the user's answers in wc_inputs.txt:

runISALiteConsole.bat –record wc_inputs.txt

This starts the ISA Lite collector in console mode and records the answers given exactly as typed. This creates a file similar to the screen shown in Figure 5.

You can then use this file as input, running the following command from now on, runISALiteConsole.bat wc_inputs.txt.

Note that if the component changes (such as access control for the first collection, and now Struts for a second collection), you then need to re-record the response file, or edit the response file to change the answer. Also, the number of questions depends on what components are enabled, such as tracing. We recommend that you run with tracing disabled in this mode, as this typically requires the user to reproduce the problem, which is difficult if it is not in interactive mode.

Back to top

Collection instructions

To collect data for a WebSphere Commerce access control issue:

1. First, you are prompted with a Welcome screen indicating that the collector has been selected, as shown in Figure 6.
   
   Figure 6. ISA Lite Welcome screen
   
   
   
2. The dialog asks if you like the collector to enable trace on your server for you (Figure 7). You have the option of skipping this task. If you select "Skip", the trace that needs to be enabled for this collector is displayed.
   
   Figure 7. ISA Lite requesting consent for enabling trace
   
   
   
3. If “Skip” is selected, the following dialog shown in Figure 8 is presented.
   
   Figure 8. ISA Lite skip trace
   
   
   
4. A prompt is displayed requesting that the WebSphere Commerce installation path be provided. The collector logic uses this path to determine the type of installation (server or developer), as shown in Figure 9.
   
   Figure 9. ISA Lite WebSphere Commerce install root dialog
   
   
   
5. If this is a server environment, a prompt asks to select the WebSphere Commerce instance (Figure 10). This prompt is not displayed in the developer flow since there is no concept of instances with the Developer edition.
   
   Figure 10. ISA Lite select instance
   
   
   
6. It is possible that the current WebSphere Application Server environment has multiple servers on it. The collector detects what servers are present and provides a selection list, as shown in Figure 11.
   
   Figure 11. Server selection dialog
   
   
   
7. If the selected server has security enabled, a prompt requests that the administrator credentials be entered, as shown in Figure 12.
   
   Figure 12. Security credentials dialog
   
   
   
8. Some problems require that the trace be enabled for a server startup. A prompt is displayed requesting whether a server restart is needed or not, as shown in Figure 13.
   
   Figure 13. WebSphere Application Server not running dialog
   
   
   
9. The collector has preset trace strings associated with the type of collection being performed. It is possible that additional strings are needed. The collector asks if you need to enable additional trace (Figure 14).
   
   Figure 14. Dialog prompting for different strings
   
   
   
10. The actions being reproduced may cause the trace logs to overflow. The collector gives the options to increase the log size and number of history log files, as shown in Figure 15.
    
    Figure 15. Dialog prompting about updating trace configurations
    
    
    
11. The collector displays a prompt asking that the problem be reproduced (Figure 16). This records the start and end time of the reproduction.
    
    Figure 16. Dialog prompting for problem recreation
    
    
    
12. If the server was started by the collector, it asks the user to stop the server again, or to leave it running (Figure 17).
    
    Figure 17. Start or restart server prompt
    
    
    
13. Since some problems require that the database data be collected, the collector can run some preset SQL queries, or provide the location of the queries that need to be run (Figure 18).
    
    Figure 18. Consent for running database queries
    
    
    
14. If the user decides to not have the collector automatically run the SQL queries, a dialog is displayed asking for a location to copy the queries that need to be run (Figure 19).
    
    Figure 19. Prompt for location to save SQL queries
    
    
    
15. If the user selected to have the collector run the queries, the user is prompted for the database connection information (Figure 20). By default, this information is pulled from the wc-server.xml file for the initial collection. For any subsequent collection, the answers are retrieved from the previous session. The database user password must always be re-entered for security purposes, as this is not persisted.
    
    Figure 20. Prompt for database connection information
    
    
    
16. If one of the SQL queries requires a user-specified input, the user is prompted with a question asking about the value to be entered. In this example, the prompt is asking for a specific STORE_ID (Figure 21).
    
    Figure 21. Prompt for database parameter
    
    
    
17. The user may be prompted to take a specific screenshot. Once the user clicks the OK button, the screenshot will be taken after 3 seconds (Figure 22).
    
    Figure 22. Prompt for capturing screenshot
    
    
    
18. The user can provide some additional information, as shown in Figure 23.
    
    Figure 23. Prompt for additional information
    
    
    
19. The user can select additional files to be uploaded to the PMR, as shown in Figure 24.
    
    Figure 24. Prompt for additional files
    
    
    
20. Once all the data has been collected, the collector can upload the data to a PMR (Figure 25).
    
    Figure 25. Prompt to upload files
    
    
    
21. If the user selects to send the files to IBM, they are prompted for information associated with the PMR, as shown in Figure 26.
    
    Figure 26. Prompt for additional PMR information
    
    
    
22. Once the files have been transferred over, an email is sent to the user confirming that IBM has received the files, as shown in Figure 27.
    
    Figure 27. Confirmation prompt
    
    
    

Back to top

Collector output

This section describes items that are created as part of running the automated collection.

• Zip archive
• MustGather data
• Analysis report
• Collector logs

Zip archive

The collector creates a zip archive containing the entire contents of the temporary directory that is created during the collection. Each action is responsible for placing the required files into the directory represented by the ${autopdtmp} property in ANT. This corresponds to:

<ISA_UserData_install>\.metadata\.plugins\com.ibm.esupport.autopd.core\
 tmp\<tmp_timestamp>

MustGather data

The most important item within the archive is the data mirroring the information requested in the corresponding MustGather document. This data is found in the WC_MustGather directory. This directory preserves the original file path structure for which the file was found on the client’s file system. It includes WebSphere Commerce application server logs, database extracts, static files from the EAR (deployed instance within WebSphere Application Server) and from the WebSphere Commerce installation directory (product files), as well as the WebSphere Application Server installation directory.

The <zip_archive>/WC_MustGather contains the following assets:

• File system assets, including logs and traces, configuration files, property files (under /WC_MustGather/<filesystem_directory_structure>/)
• CSV files containing SQL outputs, and .SQL scripts used to extract any database data (under /WC_MustGather/sql/)
• Screenshots (under /WC_MustGather/screenshots/)
• File attachments provided by the user (under /WC_MustGather/user_attachments/)

For a complete listing of what files should have been collected, refer to the corresponding MustGather under the “Collect Data” section.

Analysis report

The collector also creates an analysis report that is located in the /WC_Reports directory of the archive. The report contains several pieces of information about the environment and the collection itself. The report first lists the version of ISA that was used for the collection, as shown in Figure 28.

Next, it highlights errors that are detected in the SystemOut.log, as shown in Figure 29.

Each section provides links to do Google® searches on some key terms, or to any known problems documented by IBM that may relate to the error message.

Clicking the ActionXML Collector Summary link on the main report displays a document that explains what actions were performed (Figure 30). For those which were not, it explains why (such as not required, consent refused by client, and so on). It also provides a summary of the collection itself, including such information as:

• Whether the collection was done using ISA or ISA Lite
• Whether or not QuickCollect mode was used
• The operating system of the machine invoking the collection

Back on the main report, a summary of the questions asked to the client, as well as the answers received, are displayed, as shown in Figure 31.

Finally, a summary of the client’s environment is presented (Figure 32). This states what fix pack the client is on, whether it is a runtime or a Developer Toolkit environment, and what APARs they have installed. If it is a runtime server, the data will be presented for both the product level and the instance level.

Collector logs and properties

Within the archive, the following directories hold the automated data collectors outputs, logs, configuration, and properties:

• <archive_root>/autopdzip/autopd_logs/
• <archive_root>/autopdzip/autopd/
• <archive_root>/autopd/

Generally, you do not need to review them when using the archive to troubleshoot a problem, but they are useful when debugging the automated collector behavior itself.

Logs and temporary files

During the runtime of the collectors, when using the ISA workbench, the temporary directory is created in this directory:

<ISA_UserData_install>\.metadata\.plugins\com.ibm.esupport.autopd.core\
tmp\<tmp_timestamp>

The created collection archives are placed in this directory:

<ISA_UserData_install>\.metadata\.plugins\com.ibm.esupport.autopd.core\
collections\

The ISA collector logs are placed in this directory:

<ISA_UserData_install>\

Note that the ISA logs are included in the collection zip archive and mentioned in the previous section.

During the runtime of the collectors, when using ISA Lite, the temporary directory is created in this directory:

<ISA_Lite_install>\tmp\<tmp_timestamp>

For ISA Lite, the collector logs are placed in this directory:

<ISA_Lite_install>\log

Back to top

Advanced configurations

There are many ways to change the default behavior of the collectors. Several components make use of the collector configuration file, which allow the following to be configured:

• Logging level
• Database configuration
• Quick Collect mode
• Enabling or disabling actions

The configuration file for the ISA workbench is located at:

<ISA_UserData_install>\<user_id>\applications\eclipse\plugins\
 com.ibm.esupport.client.product.SSZLC270_<version>\config\
 wc-autopd-config.properties

For ISA Lite, the configuration file is located at:

<ISA_Lite_install>\config\wc-autopd-config.properties

Logging level

The logger class, which is used to log the customize WebSphere Commerce Java tasks, can be configured using the wc.logLevel.debug property. The default value is “false”, which is for standard logging. Setting it to “true” adds more verbose logging for debugging purposes.

#logLevel, set to true to enable verbose logging wc.logLevel.debug=false

Database configuration

The method which the database data is extracted can be configured using the property file as well. There are multiple ways to automatically determine the database connection information. By default, dbPropertySource is set to a value of “wcServerXML", which means that the majority of the values for the database configuration are pulled from the instance configuration file. The user is prompted for the remaining values.

If the dbPropertySource value is set to “promptUser”, then all the relevant questions are prompted to the user, and nothing is retrieved from the instance configuration file.

Finally, if the dbPropertySource value is set to “wc-autopd-config”, then all the values are retrieved from the wc-autopd-config.properties file, except the database user password. The database user password is always prompted to the user as a required input because the password is never persisted for security reasons.

When using the wc-autopd-config configuration, there are three options. You need to set the values in Listing 1, which, by default, are configured for a DB2® database, using the Universal Type 4 driver for JDBC connection (for both DB2 and Oracle®). You can change the wc.dbDriver, wc.dbUrl, and wc.dbDriverPath values to support Legacy Driver (Type 2) for DB2 or Universal Driver for Oracle Support.

#method of pulling the values for DB
#options: wcServerXML, promptUser, wc-autopd-config
dbPropertySource=wcServerXML

# Universal - Type 4 (DB2)
wc.dbType=DB2
wc.dbDriver=com.ibm.db2.jcc.DB2Driver
wc.dbUrl=jdbc:db2://localhost:50000/mall
wc.dbDriver.path=C:\SQLLIB\java\db2jcc.jar
wc.dbName=mall
wc.dbUserName=db2inst1

# Universal - Type 4 (Oracle)
#Oracle
#wc.dbType=oracle
#wc.dbDriver=oracle.jdbc.driver.OracleDriver
#wc.dbUrl=jdbc:oracle:thin:@localhost:1521:O10G
#wc.dbDriver.path=C:\oracle\product\10.2.0\db_1\jdbc\lib\
 classes12.jar                 
#wc.dbName=O10G
#wc.dbUserName=wcsuser

Quick collect mode

An alternative when running in the ISA Workbench or ISA Lite is to use QuickCollect mode. To avoid having the collector ask common questions each time, if the answers are the same, enable the QuickCollect mode in wc-autopd-config.properties, as shown in Listing 2.

wc.quickCollect=true
wc.quickCollectActions=GatherFiles,GatherSQL
wc.root=D:/WebSphere/WCToolkit70
wc.instanceName=demo
was.root=D:/WebSphere/SDP/runtimes/base_v7
was.profile.path=D:/WebSphere/WCToolkit70/wasprofile
was.profile.name=wasprofile 
was.cell=WC_demo_cell
was.node=WC_demo_node
was.server.name=server1
wc.ear.install.path=D:/WebSphere/WCToolkit70/workspace/WC
updi.root=D:/WebSphere/UpdateInstaller

Change wc.quickCollector to “true”. Then set the rest of the properties shown above in Listing 2 to the correct locations on the file system.

When running in QuickCollect mode, the collector reduces the number of prompts to the user. Note that this does not ask for consent for each action. Thus, to give a pre-consent, toggle the set of actions listed in the the wc.quickCollectActions property. The default configuration collects all files and database extracts, as denoted by the GatherFiles,GatherSQL value. However, if wc.quickCollectActions contains GatherTrace, you are still prompted to reproduce the problem and set the trace string, as this is a required interaction.

Enabling and disabling actions globally

It is possible to globally disable certain actions that the user will never want to grant consent to (for example, if the DBA always needs to gather the SQL data from the database). Whichever actions are set to true will be run (and consent assumed). Those set to “false” in wc-autopd-config.properties will never be run (nor will consent be asked), as shown in Listing 3.

#Enabled Actions, default = true 
GatherFiles=true
AskQuestion=true
wc_gatherTrace=true
GatherSQL=true
InvokeShellCommand=false
ModifyFile=false
GatherScreenShot=true

Back to top

Conclusion

The WebSphere Commerce automated data collectors are designed to improve and ease the gathering of data when troubleshooting a problem yourself, or working with IBM Support. The collectors run through the IBM Support Assistant or ISA Lite framework and leave the user in control of whatever actions are to take place in their environment. The automated collectors gather all necessary traces, files, database extracts, screenshots, and custom attachments needed by IBM Support to help determine the root cause of a problem, mirroring a manual MustGather document. An HTML analysis report is generated with each collection that outlines the data collected, as well as a summary of the client environment.

Resources

Learn

• WebSphere Commerce Information Center: Installing and starting the IBM Support Assistant
  
  
• IBM Support Assistant
  
  
• Submit feedback and suggestions for the WebSphere Commerce automated data collectors
  
  

Get products and technologies

• IBM Support Assistant
  
  

Discuss

• WebSphere Commerce discussion forum
  
  

About the authors

Mike Callaghan is a Software Developer at the IBM Toronto Lab, Canada. He has been part of the WebSphere Commerce Support team since 2005, specializing in runtime components. He was also part of the DB2 Development Infrastructure team, specializing in UNIX scripting and automation. He graduated with Honors from McMaster University, Canada, with a Bachelor's degree in Software Engineering

David La Gamba is a Software Developer at the IBM Toronto Lab, Canada. He has been part of the WebSphere Commerce Support team since 2007. Prior to that, he was a part of the WebSphere Application Server development team for WebSphere Application Server profiles. He graduated from York University with a Specialized Honors Bachelor's degree in Computer Science.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Installing the collectors
• Starting the collection
• Collection instructions
• Collector output
• Advanced configurations
• Conclusion
• Resources
• About the authors
• Comments

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers