In each column, The Support Authority discusses resources, tools, and other elements of IBM Technical Support that are available for WebSphere products, plus techniques and new ideas that can further enhance your IBM support experience.
This just in...
As always, we begin with some new items of interest for the WebSphere® community at large:
IBM Support Assistant Version 3.1 has just been released. This new version provides several enhancements over the previous 3.0 release mentioned in earlier columns. For the occasion, this month's column provides a more indepth description of IBM Support Assistant in general, including the latest features.
If you have noticed the new look of ibm.com and many of the various WebSphere support pages within it, then you have seen part of an ongoing effort by the IBM Web team and Knowledge Engineers to make all Web-based resources easier to use and navigate, and to help you get the most from them. In particular, you can access key support-related pages more directly from the Support & downloads menu on the main title bar, plus each redesigned page now has a set of tools and links at the bottom for quick access to common functions. More enhancements will follow in the coming months, and all changes will be progressively rolled out to the various country-specific websites that IBM maintains.
The IBM Dump Analyzer for Java™ is a new problem determination tool that reads a system dump from a JVM (such as WebSphere Application Server) and can perform a variety of analyses on the dump to diagnose common problems, such as deadlocks, memory issues, and crashes. This is actually the first release of what we hope will grow into a tool with extensive features, as we continue to increase its analysis capabilities to diagnose more and more types of problems, both at the JVM level and at the WebSphere level. This tool is available (you guessed it!) inside IBM Support Assistant.
The Diagnostic Data Collection facilities inside IBM Support Assistant continue to expand both in coverage and sophistication. Over 100 different collection scripts across more than 40 different products (each script for a different type of problem) are now offered. In addition, the main collector for WebSphere Application Server now automatically generates a summary report that provides general information about the configuration and attempts to flag common problems.
Remember to keep an eye on the schedule for upcoming WebSphere Technical Exchange webcasts. Several interesting sessions are coming up, including topics such as problem determination techniques for various product components, and WebSphere Application Server software maintenance in a complex IT environment.
Continue to monitor the various support-related Web sites, as well as this column, for news about other tools as we encounter them.
And now, on to our main topic...
What is the IBM Support Assistant?
Have you ever been frustrated with an error message and unable to quickly find the right solution? Perhaps you want to utilize a feature within an IBM product, but don't know where to find information or how-to documentation regarding this feature. Do you wish for advanced, easy-to-use tools to diagnose errors, or to automate the many manual tasks involved with resolving an issue with your software?
The IBM Support Assistant is a free desktop application that aims to simplify troubleshooting (both self-help and assisted support) for IBM software. IBM Support Assistant has many features and tools that are designed to help you research and discover solutions to problems, help diagnose problematic symptoms, and expedite the process of getting help from IBM.
IBM Support Assistant is for all consumers of IBM software, no matter how simple or complex the troubleshooting needs might be. Once installed, it can be customized to provide help specific to the IBM product set you are interested in, and provide the tools and processes that you need to help with the analysis of the problem. IBM Support Assistant is intended to be the nucleus for all your troubleshooting needs; any time a problem occurs with IBM software with which you need either vital product information or to initiate a support request with IBM, the IBM Support Assistant is the serviceability workbench you can turn to.
IBM Support Assistant components
The IBM Support Assistant has four main features for self-help troubleshooting or to expedite the IBM support process:
Search: IBM support information is contained within multiple locations in the vast IBM knowledge universe. Sometimes information about a problem or an answer to a how-to question is already available, but not readily accessible. The IBM Support Assistant search component gives you an easy-to-use interface to many different knowledge repositories so you have an easier time finding what you're looking for.
Product information: This component provides you with quick access to support resources that are pertinent to the IBM product in which you are interested. The support resources listed are hand-selected by IBM support teams and act as informational vehicles for skills enhancement, as well as troubleshooting.
Tools: The IBM Support Assistant also provides a framework for you to access several free troubleshooting and diagnostic tools. These tools not only help you with IBM products but can help you with your own applications as well.
Service: This component helps you expedite the support process when interacting with IBM support. There are two main pieces to the Service component in IBM Support Assistant. The first, data collection, provides automated scripts that can be used to quickly gather problem data from a system. You can then use the second part of the service component, problem submission, to easily send the gathered information to IBM support so that less time is spent exchanging information and directions on symptoms. The service component also enables to view your Electronic Service Requests (ESRs), attach collector output to an existing ESR, or open a new ESR with the attachment.
IBM Support Assistant Version 3.1 comes with a combined installer that also contains the Electronic Service Agent (ESA). ESA enables you to quickly gather information about software installed on your system to help with faster support. (These ESA functions are not available in IBM Support Assistant Version 3.0.)
How to get IBM Support Assistant
IBM Support Assistant is a free application that you can download. IBM Support Assistant is available for several platforms, including Microsoft® Windows®, Linux® (Red Hat Enterprise, SuSE), AIX®, Sun Solaris™, and HP-UX.
Once on the IBM Support Assistant Web site, click on the Downloads link and get the appropriate package for the platform on which you wish to install IBM Support Assistant. The install package can be extracted to show the installer binary, along with a Readme file and an Installation and Troubleshooting Guide. Read the Installation and Troubleshooting Guide and Readme files included with the download for detailed information on the installation process.
Navigating the user interface
When you start the IBM Support Assistant application, you will see a main screen with a row of tabs with labels such as Welcome, Search, Product Information, Tools, Service, Updater, and so on. Each tab corresponds to a main function of the tool; these functions are described in the next sections. Simply select a tab to jump to that function.
Configuring IBM Support Assistant with product plug-ins
The IBM Support Assistant platform can be customized to your needs, thereby providing you with focused help. This is achieved by adding product plug-ins to IBM Support Assistant via an administrative Updater component. IBM Support Assistant product plug-ins contribute to the IBM Support Assistant user experience by adding common problem determination attributes to the tool. IBM Support Assistant currently supports over 160 product plug-ins. For example, the WebSphere Application Server V6 plug-in adds these functions to the four main IBM Support Assistant components:
- Search: A new search target, the WebSphere Application Server V6 Information Center, plus product and version filters to the IBM Software Support Documents search target.
- Product information: Relevant links for WebSphere Application Server V6.
- Tools: Visibility to already-installed tools that pertain to WebSphere Application Server V6 (applies to tools already installed via the Updater).
- Service: Data collection scripts for WebSphere Application Server V6.
The first time you start IBM Support Assistant, the welcome screen will present a warning box indicating no product plug-ins were found. Click on the Updater tab and select New Plug-ins to view the complete list of product plug-ins and tools that can be added to the tool; expand the software brand category that you are interested in to view a list of product plug-ins available for that brand. Select the check-box, click on Install, and accept the license. IBM Support Assistant will prompt you with a successful installation message.
Figure 1 shows an example of the Updater screen, ready to install the product plug-in for the IBM WebSphere Adapter for Email.
Figure 1. IBM Support Assistant Updater panel
Finding useful information, from how-to tutorials to descriptions of cryptic error messages, is the key to resolving problems quickly. However, digging for information across many different Web sites and search engines makes the task of finding that one solution seem confusing and daunting.
The IBM Support Assistant Search component enables you to quickly and efficiently search multiple repositories from one place. It even includes Google as an optional search target (engine).
By default, IBM Support Assistant Search comes pre-configured with the four most relevant search targets for IBM software users: IBM Software Support Documents, IBM developerWorks, IBM developerWorks Newsgroups and Forums, and Google.
The IBM Software Support Documents search target enables filtering of results by document type. The supported types are: IBM downloads, IBM APARs, IBM books and articles, and IBM Technotes. The two developerWorks search targets enables filtering by product brand: Information Management, Lotus®, Rational®, Tivoli®, and WebSphere.
Similar to other IBM Support Assistant components, search is extensible through installing IBM Support Assistant product plug-ins. Certain product plug-ins will contribute to Search in one or more of the following ways:
Enable searching of a product's Information Center, which contains resources for a specific product. If the IBM Support Assistant product plug-in contributes an Information Center search target, you can then also query the product's Information Center directly from the IBM Support Assistant Search user interface and browse results, just like the other default search targets.
Enable filtering of the IBM Software Support Documents search results by a specific product and version. The product specific filtering will be categorized in the results as a child of the document type branch.
Figure 2 shows an example of the screen used to select and fine tune search targets, highlighting some special targets and options associated with some product plug-ins.
Figure 2. Select and fine tune search targets
Search queries to all search targets are issued in parallel and results are returned asynchronously, enabling you to navigate through the results as they are returned in real time. Results are categorized by search target, then by category filter (such as product or document type), to make browsing results as easy as possible.
Figure 3. Example of search results
The IBM Support Assistant Search component can save you a tremendous amount of time by eliminating the need to perform search after search on different sites, and the need to remember all the Web sites there are to search.
The Product Information Links component is a list of the most relevant links for an IBM software product. When you first download IBM Support Assistant, the Product Information Links will be empty. This is a dynamic page and its contents is contributed by product plug-ins. Therefore, you must install one or more product plug-ins (via the Updater) for any product links to appear. After that, you should see, at a minimum, links to the product's main ibm.com home page and its main support page. Optionally, there might also be product-related links for:
- Newsgroups and forums (public forums and discussions)
- Skills enhancement (tutorials and how-tos)
- Troubleshooting (common troubleshooting guides, wizards, and so on)
- News (RSS feeds and other news items; new for IBM Support Assistant Version 3.1).
Each category supports up to five links; this restriction helps ensure that only the most relevant links are included. These links are also reviewed by each brand's Knowledge Engineers to ensure quality and validity.
Figure 4 shows an example of the Product Information Links associated with the Rational Software Architect 7.0 product.
Figure 4. Product Information links
From the IBM Guided Activity Assistant (IGAA) to the Thread Analyzer, IBM has many problem determination tools that empower you to troubleshoot and solve problems. The IBM Support Assistant Tools component is the centralized interface to help you discover, manage, and launch all these tools. The IBM Support Assistant team is constantly seeking out new IBM tools to incorporate into IBM Support Assistant, making the task of organizing IBM tools as easy as possible.
You need to install the tools that you intend to use. In the Updater, select the New Plug-ins tab. Scroll down to the Common Component Tools folder to see available tools that apply to multiple products, or expand the folders associated with individual products to see tools that apply only to a specific product. Select the desired tools and click Install, just as you would to install product plug-ins as described earlier.
These are the tools that are available as of this writing:
- Extensible Verbose Tool Kit for Java (Windows version)
- Extensible Verbose Tool Kit for Java (Linux version)
- IBM Dump Analyzer for Java (Tech Preview)
- IBM Guided Activity Assistant (Tech Preview)
- IBM Guided Activity Assistant content for WebSphere Application Server
- IBM Pattern Modeling and Analysis Tool for Java Garbage Collector
- Memory Dump Diagnostic for Java 0.9.2 (Tech Preview)
- Memory Dump Diagnostic for Java 1.0 (Official supported version)
- Memory Dump Diagnostic for Java 2.0 (Beta version)
- Thread Analyzer
Figure 5 shows an example of the Updater screen, about to install the IBM Dump Analyzer for Java tool.
Figure 5. IBM Support Assistant Update panel
Selecting and using tools
After you have installed the desired tools, return to the Tools screen in IBM Support Assistant, which now shows all the tools that are applicable to each product for which an IBM Support Assistant product plug-in has been installed. You must select a product in the list on the left of the screen to see the tools that are applicable to that product. If you do not select any product, you will not see any tools!
The "common" tools are mapped to specific products based on a list of matching attributes. This is to determine which products "use" certain tools. Therefore, to use a one of these common tools, you will also need to install product plug-ins that use that tool. For example, the WebSphere Application Server V6.1 product plug-in "uses" all the common tools listed above, so they are all available when you click on the WebSphere Application Server V6.1 product link.
Figure 6 shows an example of the Tools screen, with the tools currently available (and installed) for WebSphere Application Server V6.1.
Figure 6. IBM Support Assistant Tools panel
Once you see the desired tool, simply click on it to launch it. Some tools will launch within an IBM Support Assistant window, while others will be displayed in their own window.
Figure 7 shows an example of the IBM Guided Activity Assistant tool -- which was the subject of the previous Support Authority column -- being invoked from IBM Support Assistant.
Figure 7. IBM Guided Activity Assistant
Service: Data collection
Data Collection is a major part of the IBM Support Assistant Service interface. Its purpose is to collect data for a problem that you are encountering. The collected data can be sent to IBM Support for debugging. The availability and number of data collection problem types vary with each IBM Support Assistant product plug-in. Products may provide no collectors, a general collector, or several problem-specific collectors (for example, install problem, configuration problem, security problem, and so on). In many cases, these collectors will correspond to the MustGather documents used by WebSphere Support Web sites, and to the diagnostic information documented by IBM Support Engineers for each specific type of problem. The collectors simply attempt to automate a process that used to be manual.
Some of these data collectors might require you to answer questions, such as What is the product's installation directory? Or, did you start the application with tracing turned on? Other questions might ask how you encountered the problem, or even prompt you for interaction throughout the collection (for example, ask you to restart a server, or to actively re-create the problem). In general, though, IBM Support tries to minimize the number of questions and manual interactions required. How much can be minimized, of course, depends on the product and type of problem.
There are two methods of running the data collectors within IBM Support Assistant:
The graphical method involves executing the collector from within the IBM Support Assistant user interface via the Collect Data menu option on the Service tab.
The portable collector method involves exporting the collector and running it in a text-only, console mode. Use the portable collection option if you do not want to install the entire IBM Support Assistant application on the machine from which you need to collect the problem data.
Collection using the workbench
To initiate data collection from within the IBM Support Assistant graphical user interface, select Service => Collect Data. One or more data collectors will be listed on the right side of the screen; how many depends on which product plug-ins you have installed. If no product plug-ins are installed, then only the default system collector will be available.
There is a checkbox next to each product plug-in data collector. When you select this checkbox, a drop-down list of available problem types for that collector is displayed. For some product data collectors, there might also be input fields for some basic information, such as the product's installation directory. As more complex collectors are built, these input fields will be moved into the collectors themselves.
After you select the problem type for the data collector(s), press the Collect button at the bottom of the list to start the collection. (You can also use the Save Preferences button to save the current collector selections to avoid re-entering them the next time you use the Collect Data panel.) A pop-up confirmation box will display to verify you are aware that data is going to be collected from the system.
After you confirm the pop-up dialog, actual data collection will begin. The data collected by each collector for each problem type will vary by product, as will the number and type of additional information items you will be asked to enter. In general, a collector will display some information or questions in the top-right area of the panel. Questions might ask you to select from a list of values or type in an answer.
Beneath the displayed information, a status box shows text output from the running collector. You can use another part of the IBM Support Assistant (such as the Search interface) as the collector runs in the background. When you return to the Collect Data panel, you will see either a message indicating that the data collection is currently in progress, or, if the collection has finished, the original list of available data collectors. To return to the running collector or to the results of the finished collection, select the Status link in the left navigation bar.
In all cases, the collection results will be a single file containing all the diagnostic information that was gathered by the collector. Some collectors will prompt you for a name for this file before starting, while others use a hardcoded file name. Either way, make note of the name and location of this file, since this is the file you might need to either send to IBM Support later for analysis, or extract information for your own analysis using the other IBM Support Assistant tools.
Collection using a portable collector
If you are unable to install IBM Support Assistant on a particular machine from which you need to collect data, use the Create Portable Collector option from the IBM Support Assistant Service panel. A portable collector is a JAR file that contains all the necessary files to execute a particular collector script. Portable collectors run in text mode only, making them ideal for running remotely on a system that can only be accessed through a telnet session or by a low-speed network connection.
Copy the successfully exported collector to the machine on which it is to be run. Extract it either using the command
jar -xvf filename.jar or with an unzip utility. A common mistake is attempting to execute the JAR file directly with the
java -jar filename.jar command; this will not work, as the collector must be extracted. The files contained within the collector archive include a readme, shell scripts or batch file to start the collector, plus other files that are needed for that specific collector to run:
The readme explains how to properly set up the environment. This involves setting the JAVA_HOME environment variable and making the shell scripts executable if the platform is not Windows.
Once this setup is done, the batch file or shell script is run to start the collection.
Since the portable collector runs in a text mode, there are no selection lists or entry fields for user input. Instead, available choices are presented as numbered lists and you enter the number of your selection followed by the Enter key. Input fields are transformed into prompts, at which you enter your response and press Enter.
When the data collection is complete, the output is another JAR file that can be manually transferred back to the machine on which IBM Support Assistant is installed. From there, the output JAR file can be sent to IBM Support or examined locally, the same as with other collections performed in the IBM Support Assistant workbench.
Service: Submitting and managing PMRs
Sometimes, even after searching for information and troubleshooting, you might still need to contact IBM Support. You do this typically by opening a Problem Management Record (PMR) against a product. PMRs require a description of the problem, the level of severity of the problem, and often also the relevant log files to help IBM Support understand your environment and debug the problem. Using the Electronic Service Request's (ESR) APIs, IBM Support Assistant makes the process of updating and opening PMRs easy. To use IBM Support Assistant ESR, select Service => Log into ESR.
Opening a PMR
You must also have an IBM Support contract to open PMRs.
Log in is required. To register, follow the Register link on the login page. After logging in, you will see a list of your previously opened PMRs, if any. From the left navigation bar, click on Submit Problem Report to open a new PMR.
Search for the product that you wish to open the PMR against by entering a keyword.
Figure 8. Submitting an Electronic Service Request
Select a product from the returned selection list, then select a component from the next selection list that appears. Finally, make a contract selection and click Continue. (Optionally, you can check Save the product, component and contract for future problem reports. This feature will enable you to skip searching and go directly to the PMR submission form.)
Figure 9. Submitting an Electronic Service Request
The PMR submission form is where you enter your contact information (it will be populated by default to the main contact of your contract), the severity and description of the problem, and any additional optional information (operating system, comments, and so on). You can even attach files that might be relevant to the PMR (such as log files). Interestingly, the output file from the last data collection run will be shown as an attachment to the PMR. This means that you can run the data collection, and then immediately open a PMR and append the output file to it. After all information is completed, you can save this as a draft PMR, or submit it.
Figure 10. Submitting an Electronic Service Request
Viewing and updating an existing PMR
Click on List Problem Reports to see a list of previously opened PMRs. This is also the first panel you see when you log into IBM Support Assistant ESR. Choose which PMR you wish to update, and click on the View/Update button. The resulting screen will show all the information entered at submission time, plus a history of updates to the PMR. You can further append text to the PMR description of the PMR, and also give a reason for this update.
You can also attach additional files to an existing PMR; this might be necessary if IBM Support requests more log files or data collection outputs. To do so, return to the list of PMRs and click the Attach File button. From there, you can browse to the appropriate file you wish to attach.
IBM Support Assistant ESR integrates nicely with data collection and simplifies the PMR submission process. Rather than calling IBM Support for every problem you encounter, you are empowered to now open, manage, and update PMRs as easily as opening IBM Support Assistant ESR.
Accessing remote systems
The information in this section applies to IBM Support Assistant Version 3.1 only.
Electronic Service Agents
The Electronic Service Agent (ESA) is an agent that runs in the background on the server, and detects and reports on equipment and software installed on the computer. It can also detect and report problems with the equipment. The Administration tab in IBM Support Assistant 3.1 provides an interface that enables you to connect to these ESA agents. (At the time of this writing, not all ESA services are available on all computer platforms.)
The My Systems link on the Administration tab launches a separate browser window that takes you to the My Systems Web site, which is a part of IBM Electronic Services. There, you can view the hardware and software inventory information that has been collected by the Electronic Service Agents.
IBM Support Assistant has a few preferences that you can adjust to change how it operates, accessible either from the Preferences tab (in IBM Support Assistant 3.0) or the Administration tab in (IBM Support Assistant 3.1):
Search Results: Raising or lowering this value results in more or fewer search results that are returned when an IBM Support Assistant search is executed. The value is not a number of resulting entries, but more of an indicator of how big the cache size for the results should be. The default value (32) will be large enough for most users, because they will probably refine their search term before running out of results.
Logging Level: This parameter controls how much information is written to the IBM Support Assistant logs. This value is typically changed only if there is a need to debug the IBM Support Assistant application itself. The Logging Level is located in the General preference section.
Default page: This preference controls which page is first displayed when IBM Support Assistant starts up, and is also located in the General section.
Proxy Settings: If you access the Internet via a proxy server, you will need to specify your proxy address and proxy port number. The proxy address is either an IP address (such as 127.0.0.1) or a hostname (such as localhost or proxy.company.com). The proxy port number is a valid TCP/IP port number. There is also a checkbox to select if the proxy is a SOCKS proxy. However, there is no place to enter a proxy user ID or password. This is intentional: if an authenticating proxy is being used, IBM Support Assistant will intercept the HTTP 407 response and display a pop-up dialog box so you can enter your user ID and password. Authenticating proxies are only supported when IBM Support Assistant is running on the Microsoft Windows platform. Auto-configured proxies that have a proxy address like http://proxy.company.com/proxy.pac are not supported within IBM Support Assistant at this time.
Notifications: (IBM Support Assistant 3.1 only) This parameter lets you specify whether or not you want IBM Support Assistant to check for upgrades each time it is started. There is also a preference setting to specify whether or not you want to be notified just prior to the check being performed.
IBM Support Assistant provides a one-stop experience on your desktop any time you need information on a problem or are trying to gain skills on a certain feature of IBM software. The search feature prevents you from having to go to many different locations to look for answers; the product information component enables you to quickly gain access to resources that might be very difficult to locate, and tools empower you to develop your own troubleshooting capabilities. If all else fails, IBM Support Assistant enables you to contact IBM Support via the ESR process, and expedites this process by automating complex data collection scripts.
IBM Support Assistant is tailored for ease-of-use, and the IBM Support Assistant project is constantly implementing new features to improve the value of IBM software to our customers. Contact the IBM Support Assistant team at firstname.lastname@example.org.
To discuss any issues you might have with IBM Support Assistant or to ask any questions to the IBM Support Assistant community, please visit the IBM Support Assistant forum.
- The Support Authority: If you need help with WebSphere products, there are many ways to get it
- IBM Software Support Web site
- IBM Software Support Handbook
- Product documentation
- IBM developerWorks
- IBM Redbooks