Automate data collection for problem determination, Part 2: The Automated Problem Determination Tool

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Introductory

Bob Moore (remoore@us.ibm.com), Advisory Software Engineer, IBM
Brad Topol (btopol@us.ibm.com), Senior Software Engineer, IBM
Jie Xing (jiexing@us.ibm.com), Advisory Software Engineer, IBM

24 May 2005
Updated 07 Mar 2006

Discover how you can extend the Automated Problem Determination (AutoPD) tool to address additional products and problem scenarios simply by creating additional Ant scripts based on the ones included with the tool or by editing the XML documents shipped with the tool. You also review the tool's internationalization capabilities and learn how to use them.

Introduction

This article continues the series about the Automated Problem Determination Tool (AutoPD). (See Part 1 for an introduction to the tool.) In this article you extend the tool to address additional products and problem scenarios. You do this by creating additional Ant scripts (based on the ones included with the tool) or by editing the XML documents shipped with the AutoPD tool. You'll also explore the tool's internationalization capabilities and learn how to use them. Two customization topics are broken down into two articles: extending the tool's symptom analysis capabilities and extending the symptom analysis for XML-formatted log records (including Common Base Events).

Although the AutoPD tool includes Java™ implementations of almost fifty custom Ant tasks, its behavior is actually controlled by XML documents. These XML documents fall into two categories: a collection of Ant scripts that direct the tool through a predefined series of tasks and additional XML documents that specify locations, options, execution parameters, and the like. In most cases, developers who want to apply the tool to new products or new problem types do not need to write new Java code; modifications can be achieved entirely by modifying the XML documents included with the tool or by creating new XML documents for the tool to use in their place.

Back to top

Modify the tool's menu of problem types

Figure 1 shows the tool's main GUI when it first opens. The only aspect of this interface you need to modify is the tree of problem types made available to the user. These problem types are the user's means of invoking the collection scripts included with the tool, so if you create new collection scripts, you'll need to give the user a way to invoke them.

To modify the Problem Type tree, look at the interface after the user has expanded some of the folders shown in Figure 1. In Figure 2, notice the second-level folders (Installation and Configuration, Security and Administration, etc.) under the top-level folder IBM WebSphere® Portal. Similar second-level folders also exist under the top-level folder WebSphere Application Server. These second-level folders are used to group the problem types for a particular product into subcategories that make sense to the user and thus simplify the user's task of locating a particular problem type. The tool actually supports an additional level of categorization, using third-level folders. But so far, it's not been necessary to use this third level with either WebSphere Application Server or WebSphere Portal.

The entries in the Problem Type tree are specified in an XML document that conforms to the AutoPDMenu.xsd schema. This schema is available in the tool's properties directory, so you can import it into your XML tooling and use it to validate your AutoPDMenu document. Listing 1 shows several lines from the AutoPDMenu-full.xml document that specifies the menu entries for version 1.2 of the AutoPD tool. By comparing Listing 1 with Figure 2, you can see how the XML attributes topLevel and secondLevel control the placement of the individual entries within their folders. The attribute thirdLevel works in exactly the same way. If you are defining your own product subtree, you should choose a topLevel value that identifies your product. Beyond that, you are free to use the secondLevel and thirdLevel attributes in any way that makes sense to your users.

<autoPDMenuItem title="Portal_Config_Problem" 
   link="scripts/wps/portalconfig.xml" 
   bundle="autopdtoolstrings" 
   topLevel="WebSphere_Portal" 
   secondLevel="Portal_Installation_And_Configuration"/>
<autoPDMenuItem title="Portal_Upgrade_Problem" 
   link="scripts/wps/portalupgrade.xml" 
   bundle="autopdtoolstrings" 
   topLevel="WebSphere_Portal" 
   secondLevel="Portal_Installation_And_Configuration"/>
<autoPDMenuItem title="Portal_XML_Config_Interface_Problem" 
   link="scripts/wps/portalaccesscontrol.xml" 
   bundle="autopdtoolstrings" 
   topLevel="WebSphere_Portal" 
   secondLevel="Portal_Installation_And_Configuration"/>
<autoPDMenuItem title="Portal_Access_Control_Problem" 
   link="scripts/wps/portalaccesscontrol.xml" 
   bundle="autopdtoolstrings" 
   topLevel="WebSphere_Portal" 
   secondLevel="Portal_Security_And_Admin"/>
<autoPDMenuItem title="Portal_Login_Problem" 
   link="scripts/wps/portallogin.xml" 
   bundle="autopdtoolstrings" 
   topLevel="WebSphere_Portal" 
   secondLevel="Portal_Security_And_Admin"/>

Notice that the values of the title, topLevel, and secondLevel attributes in Listing 1 are translation keys, not displayable strings themselves. Corresponding entries must exist in a language bundle that's made accessible to the AutoPD engine as it builds the tool's main GUI. In Internationalizing the Ant scripts you'll see how to package a language bundle for the AutoPD engine. What's important here is how an AutoPD menu entry points to its language bundle. This can be done in two ways: explicitly, as shown in Listing 1, or implicitly. If an autoPDMenuItem element has no bundle attribute, then that element's language bundle becomes the default for the AutoPD tool. This default language bundle is specified in the properties/autopd.properties file, as the value of the nlsbundle property.

The properties/autopd.properties file is also where the AutoPD engine learns which AutoPDMenu document to use for populating the Problem Type tree. The autopd.properties file included with Version 1.2 of the AutoPD tool includes the following entry: autopdmenu=properties/autoPDMenu-full.xml. There are two approaches to adding autoPDMenuItem elements to launch your own collection scripts.

• If you want your users to be able to launch your collection scripts, but not those included in Version 1.2 of the AutoPD tool, you should create your own AutoPDMenu file from scratch and update the autopdmenu property in autopd.properties to point to it.
• If you want your users to be able to launch the collection scripts included in Version 1.2 of the AutoPD tool as well as your own collection scripts, you should extend the tool's autoPDMenu-full.xml document by adding autoPDMenuItem elements for your scripts. You'll still probably want to save the updated document under a different file name and adjust the value of the autopdmenu property to point to it. If you use the same file name to store your updated document, you run the risk of having your changes overwritten if the user updates the AutoPD tool.

For completeness, Listing 2 shows the portion of the AutoPDMenu.xsd schema that defines the autoPDMenuItem element.

<xsd:element name="autoPDMenuItem">
    <xsd:complexType>
        <xsd:attribute name="bundle" type="xsd:string" use="optional"/>
        <xsd:attribute name="link" type="xsd:string" use="required"/>
        <xsd:attribute name="title" type="xsd:string" use="required"/>
        <xsd:attribute name="topLevel" type="xsd:string" use="optional"/>
        <xsd:attribute name="secondLevel" type="xsd:string" use="optional"/>
        <xsd:attribute name="thirdLevel" type="xsd:string" use="optional"/>
     </xsd:complexType>
</xsd:element>

Back to top

Write your own Ant scripts for the AutoPD Tool

Ant has such rich capabilities that it is possible to do just about anything in an Ant script. As a result, it's often hard to get started when you need to create a script to do something specific. This is one reason why the tool is distributed as a fully enabled problem determination aid complete with its own collection scripts, as opposed to simply an engine component available to support your custom-written scripts. By including a set of actual scripts, you have a starting point for developing your own scripts.

These scripts don't limit what you can do in a custom script; all of the standard Ant tasks are available in the AutoPD tool and can be used in any way you choose. But, the scripts are instructive in at least three ways because they illustrate:

• An overall approach to writing scripts that accomplish what the AutoPD tool accomplishes with its own scripts: collecting problem information and performing symptom analysis
• Certain conventions that the AutoPD tool implementation assumes are to be followed in all Ant scripts written for the tool
• When, how, and why to use the custom Ant tasks provided with the tool (Because these custom tasks are not described in any standard Ant reference, many of them are covered in detail in this article. Some, however, are so straightforward that you can learn all you need to know about them by simply observing how they are used in the tool's own scripts.

Back to top

Overall structure of an AutoPD script

Let's begin by looking at the overall structure of the same Ant script from Part 1, the one for a Portal Login problem. The following discussion assumes some familiarity with Ant basics. (See Resources for a link to the Apache Ant manual.)

The autopdmain target

Here is the primary target (shown in Listing 3) in the Portal Login script:

<!-- This target is the main entry point into the script.  It is the target
that is called by the AutoPD tool after this collection type has been selected, 
and collection is started. 
-->

<target name="autopdmain" description="This is AutoPD main to control running steps" 
     depends="set_problem_type,
	 setup_autopd, 
	 validate_os, 
	 ask_for_roots, 
	 verify_roots, 
	 was_version, 
	 was_version_level, 
	 wps_common_setup, 
	 cell_type, 
	 input_cell_name, 
	 wps_config_setting_for_cluster, 
	 deployment_manager_root, 
	 was_log_redirect, 
	 security_type, 
	 was_admin_info, 
	 detect_was_status, 
	 warnuser, 
	 stop_wps, 
	 backup_log_properties, 
	 recovery_needed, 
	 set_log_properties, 
	 set_wmm_properties, 
	 start_wps, 
	 pause, 
	 stop_wps1, 
	 collect_wps_information_common, 
	 collect_wps_information_security_admin, 
	 restorewps, 
	 recovery_completed, 
	 autopd_feedbacks,
	 ftp_message, 
	 ftp_collected_information,
	 restart_wps,
	 script_completed">
</target>
 

Whenever a collection is invoked from the main GUI, the tool begins executing the associated script at the target named autopdmain. Therefore, you need to include a target with this name in each of your scripts. In the scripts included with the AutoPD tool, this target is simply a way of kicking off, in order, the remaining targets in the script, using the Ant depends attribute. Ant supports more complicated usage patterns for the depends attribute (target A depends on target B, which depends on target C, which depends on target D, and so on), and you're free to use these more complicated patterns in the scripts you write for the tool. But we did not find it necessary to use these more complicated dependency patterns in the tool's own scripts. Only two targets in each WebSphere Portal scripts express dependencies on other targets: the main entry point autopdmain and, optionally, the alternate entry point autopdmainrecovery, which is discussed in The autopdmainrecovery target section.

Notice that among the dependencies listed for the autopdmain target is the pair of targets stop_wps1 and stop_wps2. These two target are, in fact, identical to each other except for their names. A pair of targets is needed because of how Ant handles dependencies: after a target is executed, all dependencies on it are satisfied. Therefore, the target will not be executed again. Because this script needs to stop WebSphere Portal twice, it needs two distinct targets to issue the two stop commands.

When the AutoPD tool migrated recently from Ant 1.5 to Ant 1.6, another option became available to script writers needing to execute a function multiple times in a script: Ant macros. Ant macros are fully supported now in the AutoPD tool, and we will undoubtedly use them in the future as we develop new collection scripts. The original approach still works in Ant 1.6, however, so we haven't seen the need to update any of the existing scripts that use it.

The autopdmainrecovery target

The autopdmainrecovery target, shown in Listing 4 is the second target in the Portal Login script that can serve as an entry point into the script:

<!-- This target provides an alternate entry point into the script.  The 
AutoPD tool calls this target when it detects that a problem has occurred so
that the script has an opportunity to restore the system to the correct state
before terminating. 
-->

<target name="autopdmainrecovery" description="Recover Portal Server state from AutoPD's failure" 
     depends="stop_wps2, 
	collect_wps_information_for_recovery_common, 
	collect_wps_information_security_admin_for_recovery, 
	reset, 
	recovery_completed,
	recovery_script_completed"> 
</target>
 

Note the first target in the dependency list: stop_wps2. This is a third target that stops WebSphere Portal, and it is identical to the two shown earlier in the autopdmain dependency list. Those targets can't be reused for recovery because they may have been executed from the autopdmain dependency list before recovery became necessary. In this case, they would not execute again when they were needed for recovery.

The target name autopdmainrecovery is also given special treatment by the tool. Whenever the tool detects that a script has terminated abnormally, it checks to see whether the script failed at a point where recovery is needed by:

1. Determining which script it was executing when the failure occurred
2. Examining two particular Ant properties that might have been set during the unsuccessful execution of the script (It is looking for a specific combination: the property autopdNeedRecovery with the value true and the property autopdRecoveryPerformed either undefined or with the value false. In other words, did the previous execution of the script stop at a point where recovery was needed, but had not yet been performed?)
3. Detecting this combination, it invokes the same script again, but this time starts at the target autopdmainrecovery rather than at the usual target autopdmain.

To make proper use of this logic in the tool, you must handle the autopdNeedRecovery and autopdRecoveryPerformed properties in the same way that Portal Login and the other scripts included with the AutoPD tool handle them. Listing 5 and Listing 6 summarize what you need to do in your script. The term "execution path" here refers to the sequence of tasks that are invoked by the script, irrespective of which target they reside in.

...
// break stuff
<property name="autopdNeedRecovery" value="true" />
// break stuff
...
// break stuff
...
// fix stuff
...
// fix stuff
...
// fix stuff
<property name="autopdRecoveryPerformed" value="true" />
...

Listing 6. The autopdmainrecovery execution path

...
// fix stuff
...
// fix stuff
...
// fix stuff
<property name="autopdRecoveryPerformed" value="true" />
...

In your main execution path, you set the property autopdNeedRecovery to true as soon you "break" anything; that is, as soon as you make any change that you're planning to undo ("fix") later in your script. The Portal Login script, for example, copies several of the portal server logs to a backup location and then deletes them from their original location while it proceeds with re-creating the login problem. As the script nears completion, it will copy the logs back to their original locations, so that WebSphere Portal is left with the historical log data it had before the script began executing. The autopdmainrecovery execution path assures that this restoration of the logs will take place even if the script's autopdmain execution path is interrupted before it reaches that point.

Not all scripts require a recovery path. If your script doesn't "break" anything, then there's nothing that needs to be fixed. If you do need to perform recovery, you will have to determine exactly what recovery steps are required. You'll also need to make sure that these steps are performed by targets that will be executed when the script is invoked at the autopdmainrecovery entry point (as well as by targets near the end of the autopdmain execution path, if the script proceeds to completion normally). If you require recovery, here's a summary of what you need to do with the two properties:

• In your autopdmain execution path, set autopdNeedRecovery to true as soon as you "break" anything. It's fine to continue "breaking" additional things after you've set this property to true.
• In your autopdmain execution path, set autopdRecoveryPerformed to true as soon as you've "fixed" everything that you broke earlier.
• In your autopdmainrecovery execution path, set autopdRecoveryPerformed to true as soon as you've "fixed" everything that you might have broken earlier in the autopdmain execution path.
• While it's possible to insert the two <property> tasks shown in Listings 4 and 5 directly into your targets, it's recommended that you instead take advantage of the shared targets recovery_needed and recovery_completed included with the tool. These shared targets include the <property> tasks to set the recovery properties, along with some <wsnlsecho> tasks to tell the user what's going on. Their real benefit, however, lies in making it very easy to tell where a script's "recovery zone" starts and ends, simply by examining the dependency list for the autopdmain execution path. The recovery_completed target can also be used in the autopdmainrecovery execution path, since if this path is invoked at all, we know that the point where this target would have been invoked on the autopdmain execution path was not reached.

If your script fails during the autopdmain execution path after it has done something you'll need to recover from ("// break stuff"), but before it has had a chance to perform the recovery ("// fix stuff"), then the tool will encounter the combination of property values that causes it to launch the script at autopdmainrecovery. The same thing will happen if the recovery itself fails before it completes. It is fine for the script to continue along either execution path after you've set autopdRecoveryPerformed to true. If it fails here, however, recovery will not be invoked, so you must be careful not to "break" anything at this point.

Import XML documents containing shared targets

Because the various WebSphere Portal scripts perform many of the same steps (for example, issuing the FTP commands to send the collection zip file to IBM support), they often share identical targets. To simplify maintenance for the scripts included with the tool, these common targets are collected into separate XML documents, which are pulled into each script document by the custom Ant tasks shown in Listing 7. Each import is a separate operation, so a script can import from as many shared targets documents as necessary. All scripts, however, will need to import from the document sharedtargets.xml, since this document contains the shared targets that all scripts need to invoke (as well as other shared targets that are generally useful, but not required for every script).

<!-- Targets shared among multiple scripts are in the XML documents *-sharedtargets.xml.
	 The following imports pull these shared targets into this script.
-->
<autopdimport file="${autopdimportdir}/scripts/sharedtargets.xml" 
     osgiBundle="com.ibm.autopd"/>
<autopdimport file="${autopdimportdir}/scripts/portal-was-sharedtargets.xml" 
     osgiBundle="com.ibm.autopd"/>
<autopdimport file="${autopdimportdir}/scripts/wps/portal-sharedtargets.xml" 
     osgiBundle="com.ibm.esupport.client.product.SSYJJC"/>

The custom task <autopdimport> was created to adapt the AutoPD engine to the componentized environment characteristic of OSGi. (For further information on OSGi, you should consult the OSGi Alliance Web site, see Resources.) A future article will focus on this topic, and will include a full discussion of how to choose a value for the osgiBundle attribute. For importing the three shared targets mentioned in Listing 7, you can use the values shown there.

Depending on the degree of repetition in your scripts, you might choose to follow the shared targets approach, by defining your own XML shared targets documents, and including autopdimport tasks pointing to them in each of your scripts. This only works, of course, for targets that are identical in all the scripts that use them.

Back to top

Internationalize the Ant scripts

A number of standard Ant tasks can cause text strings to be displayed in one manner or another; for example, the <echo> and <input> tasks. However, these standard tasks do not support internationalization of the text strings that are displayed; what gets displayed is the exact text string that appears in the script. The tool includes several custom Ant tasks that implement extended versions of these standard Ant tasks, versions that do support internationalization of display strings.

Consider first the <wsnlsecho> custom task, which extends the standard <echo> task. The <wsnlsecho> task was actually developed first for WebSphere Application Server and then extended by the AutoPD Tool. Listing 8 shows an example of this task from a shared target imported by the Portal Login script:

<wsnlsecho key="Zip_all_log_and_related_information_to_a_zip_file_pmrfilename" 
           bundle="autopdtoolstrings"
           message="Zipping all log and related information to a zip file: {0}" 
           replace="${pmrfilename}"
           id="2225"
           level="info"
           component="\scripts\wps\portal-sharedtargets.xml"/>

The key attribute here contains a key value that indexes a text string in the bundle identified by the bundle attribute. (The actual key value Zip_all_log_and_related_information_to_a_zip_file_pmrfilename could have been anything; the long, ugly values used by the tool are holdovers from an initial approach to internationalization that was discarded in favor of the current approach based on the <wsnlsecho> custom task.) The normal Java bundle processing applies here, so a locale-specific file such as autopdtoolstrings_en will override the default file autopdtoolstrings. All of the bundle files are assumed to be located in the tool's properties directory or in one of its subdirectories. If a bundle is in a subdirectory of the properties directory, then it is referred to in the following way:

bundle="properties/SSEQTP/autopdtoolstrings_was".

The message attribute contains the message text to be used if a bundle file with the specified name cannot be located. The replace attribute contains a list of substitution variables (separated by double semicolons (;;) if there are more than one) that are plugged into the numbered substitution points {0}, and so on in the message text. Finally, the id, level, and component attributes provide information for the AutoPD log entries that are created when this task is executed.

Back to top

Typical activities performed in a script

In the following sections, we'll look briefly at a few of the activities that the AutoPD tool's own scripts perform. You can learn more by carefully examining the scripts themselves.

Provide progress reports

The tool's Ant scripts use a combination of one standard Ant task and three custom tasks to provide a sequence of time-stamped progress reports as the script progresses through its sequence of tasks. These progress reports serve two purposes:

• They provide the tool user with immediate feedback regarding what the tool is doing.
• Because they are saved in the AutoPD log files, they provide IBM support with information about exactly when the tool performed such steps as stopping and restarting WebSphere Portal. IBM support can compare these time stamps with those in the analysis report, and with those in the underlying logs, to better understand the contexts in which the log entries were written.

Listing 9 shows an example with the four custom tasks from the Portal Login script.

<echo message=" "/>
<stepcount />
<autopdtimestamp property="autopdts" pattern="yyyy.MM.dd-HH.mm.ss.SSSz" />
<wsnlsecho key="Step_stop_Portal_Server" 
           bundle="autopdtoolstrings"
           message="[{0}] Step {1}: Stopping Portal Server" 
           replace="${autopdts};;${step.count}" 
           id="2243"
           level="info"
           component="\scripts\wps\portal-sharedtargets.xml" />

You simply repeat this pattern (with the appropriate message key) whenever you want your script to print a progress report. Here is an example of the progress report that results from the combination of tasks shown here:

[2005.05.15-08.24.51.717EDT] Step 4: Stopping Portal Server

The only setup required for the progress reports is to initialize the step counter to 0 in an Ant target that executes prior to your first progress report:

<stepcount count="0" />

It's best to handle this setup in the way the WebSphere Portal script handles it: by including the shared target autopd_setup on the autopdmain execution path.

Get information from the user

One of the primary design goals for the AutoPD tool is to automate as much of the collection process as possible so that it can proceed without user intervention. There are, however, a variety of situations in which the tool must involve the user, to answer questions where only the user is in a position to know the answer. Among these questions are:

• Which instance of a product should collection be performed against? (Even if the tool can detect all the instances of a product present on the system, it has no way of knowing which instance the user wants to collect problem data for.)
• Is it all right to stop and restart the server at this time? (Only the user can weigh the relative cost of stopping this server at this time compared against the benefit of getting the current problem resolved.)
• Should the tool FTP the problem data it has collected to IBM support? (While the tool can automate the mechanics of how to FTP the problem data to IBM support, it can't, by itself, decide whether to FTP the data. IBM support may direct the user to examine some particular information in the analysis report, and based on this information, possibly perform a second collection with different settings, and then FTP the results of that second collection to IBM support. Or the user's enterprise firewall setup may be such that the tool will not be able to FTP the problem data directly to IBM support.)

In all of these cases, the tool requires some input from the user after the Ant script has begun executing. Let's look at how this user input is solicited and received.

In the overview article, you saw the pop-up window with which the tool asked the user whether to FTP the problem data it had collected to IBM support. This pop-up window is reproduced in Figure 3.

This pop-up window was displayed as a result of the custom Ant task shown in Listing 10.

<autopdinput message="Would_you_like_the_AutoPD_Tool_to_FTP_the_logs_to_IBM_Support"
       validargs="FTP_the_logs_to_IBM_Support,No_Thanks" 
       addproperty="ftpresponse" />

As discussed in Internationalizing the Ant Scripts, the tool includes several custom Ant tasks that extend standard Ant tasks with support for internationalizing display strings. The <autopdinput> task is one of these tasks. As described earlier, the three strings with the underscores are the keys that index the translated display strings in the resource bundles. The attributes message and validargs place the translated strings in the locations shown in Figure 3. The attribute addproperty causes the untranslated string (that is, the key itself) associated with the button that the user presses to be assigned to the Ant property ftpresponse. As usual, you will need to include the bundle attribute if you want the tool to use your bundle for looking up the text strings for the key values in your <autopdinput> element rather than the tool's default bundle autopdtoolstrings.properties.

Next, the script uses the standard Ant <condition> task to create a second property do.FTP if, and only if, the user pressed the FTP the logs to IBM support button, shown in Listing 11.

<condition property="do.FTP">
	<equals arg1="FTP_the_logs_to_IBM_Support" arg2="${ftpresponse}" />
</condition>

The second property is needed because of the way in which Ant conditional processing works; it is always based on the existence of a property rather than on the value of the property. Regardless of which button the user pressed, the property ftpresponse always exists when the <autopdinput> task completes. The do.FTP property, however, exists if, and only if, the user pressed the button requesting that the FTP operation be performed.

Finally, the script executes the target that performs the FTP operation only if the do.FTP property exists, shown in Listing 12.

<target name="ftp_collected_information" 
        description="FTP info to IBM Support" if="do.FTP">
...
</target>

This is the pattern to use whenever a script's behavior needs to vary based on input from the user:

• Use the <autopdinput> task to solicit the input from the user, storing the result in a first property.
• Use the <condition> task to map the value of the first property to the existence of a second property.
• Use the existence of the second property to control the conditional execution of subsequent Ant targets.

The custom Ant task <if>

While standard Ant's conditional target execution can always be used to control a script's run-time execution path, it can often become very cumbersome. Consequently, the AutoPD Tool has implemented a custom Ant task, <if>, to provide for conditional execution of individual targets. Listing 13 shows an example in which the Portal Login script checks within a shared target verify_roots to ensure that the user has entered a valid WebSphere Portal root directory value in the input field you saw in Figure 1:

<wsnlsecho key="Verify_Portal_root_directory" 
      bundle="autopdtoolstrings"
      message="Verifying WebSphere Portal root directory."
      id="2202"
      level="info"
      component="\scripts\wps\portal-sharedtargets.xml" />

<available file="${portal.root}/config/wpconfig.properties" 
      type="file" 
      property="portal.root.existing" />

<if isNotTrue="${portal.root.existing}" >
      <autopdinput message="Portal_Root_value_is_not_valid" 
           validargs="OK" 
           addproperty="portalroot.wrong" />

      <wsnlsecho key="Portal_Root_Directory_Inputed_Doesn't_Exist" 
           bundle="autopdtoolstrings"
           message="The WebSphere Portal root directory input by the user does not exist."
           id="2203"
           level="error"
           component="\scripts\wps\portal-sharedtargets.xml" />
</if>

<condition property="do.abort.portalroot.wrong">
      <equals arg1="OK" arg2="${portalroot.wrong}" />
</condition>

<fail if="do.abort.portalroot.wrong"> WebSphere Portal root directory input by user doesn't exist. 
Automated Problem Determination Tool terminated.</fail>				

<!-- Now that Portal root is available and verified, save it for next time in
	autopdcurrentstate.properties. -->
<persistproperty property="portal.root"/> 

There are six top-level tasks here, with the beginning and end of the <if> task highlighted in bold:

• The custom Ant task <wsnlsecho> provides the message for the progress window and AutoPD log files stating that the tool is verifying the WebSphere Portal root directory.
• The standard Ant task <available> attempts to use the root directory value and set the property portal.root.existing to true if it succeeds. The test assumes that if WebSphere Portal is present at the indicated location, the file wpconfig.properties will also be present.
• The custom Ant task <if> checks the value of portal.root.existing and executes its child tasks if, and only if, the value of this property does not equal true. These child tasks tell the user to try again and record what's going on in the progress window and the AutoPD log files. An instance of the <if> task must have exactly one of the two attributes isTrue and isNotTrue specified.
• The standard Ant task <condition> performs the same trick you saw earlier, in the do.FTP example.
• The standard Ant task <fail> aborts the script if the WebSphere Portal root directory is invalid, because the subsequent collection steps can't be performed until the tool can locate a WebSphere Portal instance.
• If the script gets past the <fail> task, then the WebSphere Portal root directory value supplied by the user must be valid. The custom Ant task <persistproperty> saves this value to nonvolatile storage, so that it can be presented to the user as the default value the next time a script needs to ask the user for WebSphere Portal root.

As mentioned earlier, all of this could have been accomplished using Ant's standard conditional target execution. But the resulting scripts would be much larger, much harder to understand, and much harder to maintain. It isn't only the WebSphere Portal root directory that needs to be validated; a script must validate every "must be right" value it gets using the tool's GUI before it can proceed with its main activities. The verify_roots target, for example, validates and saves the WebSphere Application Server root directory in exactly the same way it validates and saves the WebSphere Portal root directory. By using the <if> task, it's possible to place both of these validation activities in the one target verify_roots, rather than cluttering the script with many targets that are peripheral to its main purpose.

Perform symptom analysis

Symptom analysis is controlled by a single Ant task: the <infocollect> custom task. Listing 14 contains an example of this task, from the Portal Login script:

<infocollect problem="${infocollectProblemType}"
	patternFile="${portal.shared.targets.bundle.basedir}/properties/wps/pattern_template.xml" 
	levelreport="${autopdtmp}/autopd/levelreport.html" 
	autopdreport="${autopdtmp}/autopd/autopd_analysis_report.html" 
	productname="${wps.product.name}" 
	productversion="${wps.product.version}" 
	autopdname="${autopd_name}" 
	autopdversion="${autopd_version}" 
	timeout="${infocollector.timeout}">
   <autopdfileset filesetName="wpslog" filesetDir="${portal.root}/log" />
   <autopdfileset filesetName="tracelog" filesetDir="${trace.log.file}" />
   <autopdfileset filesetName="systemoutlog" filesetDir="${systemout.log.file}" />
   <autopdfileset filesetName="systemerrlog" filesetDir="${systemerr.log.file}" />
   <autopdfileset filesetName="configtrace" filesetDir="${portal.root}/log" />
   <autopdfileset filesetName="eventhistory" filesetDir="${portal.root}/version/history" />
   <autopdfileset filesetName="eventhistory" filesetDir="${was.root}/properties/version/history" />
</infocollect>

What's going on here?

• The problem attribute identifies the type of problem for which symptom analysis is being performed.
• The patternFile attribute points to the file containing the symptoms to be used for the analysis, the information to be included in the analysis report, and the format to be used for this information in the report. (The details of how to write pattern files is covered in the next two articles in this series.)
• The next two attributes, levelreport and autopdreport, indicate where the tool should save the analysis report itself, as well as a separate copy of the level report that gets merged into it. In the case of the analysis report, this is where the subsequent <zip> task will look for the report when it needs to include it in the zip file.
• The productname and productversion attributes indicate the particular product and version for which the symptom analysis is to be performed. The tool will use these attribute values to index product/version-specific analysis instructions in the pattern file that was identified using the patternFile attribute.
• The autopd_name and autopd_version attributes pass values that will be included in the analysis report, to document exactly which version of the tool created the report.
• Finally, the timeout attribute provides a timeout value, in milliseconds, after which the analysis will be halted, and the collection script will be resumed.
• In addition to its own attributes, the <infocollect> task contains a list of one or more subordinate <autopdfileset> tasks to indicate which files should be analyzed. Each <autopdfileset> task contains two attributes:
  • A filesetDir attribute identifying one or more files to be analyzed.
  • A filesetName attribute containing a string value that the tool will match up with a corresponding value in the pattern file to index the exact set of symptoms and other detailed instructions to be used for analyzing this particular set of files. The details of how these filesetName values are used will be covered in the subsequent symptom analysis articles later in the series.

Note that in this example, all of the attribute values except for filesetName contain Ant properties that were initialized at some prior point in the script. Some of these property values are simply read in from properties files. Others, however, require entire Ant targets to resolve. You should review, for example, the logRedirect target in the Portal Login script, to see how some of the filesetDir values get resolved.

The value ${infocollectProblemType} for the problem attribute leads to a discussion of a means of passing parameters in the AutoPD tool's scripts: the script-level parameter. Because the <infocollect> task in Listing 14 occurs in a shared target, it must be usable by many different collection scripts, for many different types of problems. But the analysis itself is designed to be different for the different problem types, which is why the problem type was passed into the <infocollect> task in the first place. The solution is to store the problem type for a collection script in the Ant property infocollectProblemType, and then pass the value of this property to the <infocollect> task in the shared target. Because the shared target is invoked by different scripts, different values get passed to the <infocollect> task. Yet the content of the shared target itself remains constant. Other values that need to vary on a per-script basis, yet are used in shared targets invoked by multiple scripts, are handled in the same way.

For WebSphere Portal, a custom Ant task <wpsversiontask> handles assigning values to the product.name and product.version properties. This task examines a WebSphere Portal properties file and populates the Ant properties with values it finds there. You can also set these properties directly in your Ant script, in case <wpsversiontask> is not able to retrieve information from your product dynamically.

Back to top

New custom tasks

Because the AutoPD Tool is based on Ant scripts, all of the standard capabilities of Ant are available to you if you need them. Among these capabilities is the opportunity to implement your own custom tasks and add them to the list of custom tasks included with the tool. Here's what you need to do:

1. Implement your custom tasks in Java code.
2. Link the Java Archive (JAR) file you create to the tool.
3. Edit the tool's autopdtaskdef.properties file to add associations between your custom tasks and the Java classes that implement them.
4. Use your custom tasks in your scripts.

For more information about implementing custom tasks, you should consult the Apache Ant manual. (See Resources for a link.)

Back to top

Preserve your modifications across tool updates

Be careful not to lose modifications you have made to the tool's behavior when a new version of the tool is installed. While different approaches are possible, the one described here is recommended.

First, assume that when you download an updated version of the tool, you will delete the existing RasGUI directory tree entirely and then create a new one by unzipping the RasGUI.zip or RasGUI.tar file that you downloaded. It is, of course, possible to unzip the newly retrieved archive on top of the existing RasGUI directory, and, therefore, preserve some of your modifications. But we do not recommend this approach because "leftovers" from the previously installed version of the tool can cause the newly installed version to behave unpredictably.

There are two ways of modifying the behavior of the tool, which require different actions for their preservation:

• Those achieved by creating new Ant scripts or XML documents along with the ones distributed with the tool (In this case, you'll need to copy the files into the newly created RasGUI directory tree.)
• Those achieved by editing existing Ant scripts or other existing XML documents that come as a part of the tool (In this case, you'll need to merge your updates back into the new versions of the files that came with the updated tool.)

Wherever possible, you should use the option of creating new files to the option of merging your content into the existing files. Fortunately, there is only one case where you absolutely must do the merging operation. In order to get started, the tool must be able to find its main properties file autopd.properties at the fixed location properties/autopd.properties relative to the directory location where the tool is executing. You may also want to merge your new material into the tool's AutoPDMenu.xml document, depending on whether you're positioning your scripts as additions to those shipped with the tool itself, or as replacements for the tool's scripts. Finally, if you write any of your own custom tasks, you must merge their entries into the tool's autopdtaskdef.properties file.

To prepare for downloading an updated copy of the tool, you can create a directory structure such as the one shown in Listing 15.

	MyRasGUI
		mergeback
			autoPDMenu.xml
			autopd.properties
			autopdtaskdef.properties
		properties
			my_pattern_template.xml
			mylanguagebundle.properties
			mylanguagebundle_en.properties
			mylanguagebundle_de.properties	
		scripts
			my_script_1.xml
			my_script_2.xml
		lib
		   myTasks.jar

Make sure you have copied the current version of each of these files from the tool's RasGUI directory tree to this MyRasGUI directory tree, then go ahead and delete the existing RasGUI tree and create the new one by unzipping the updated tool.

All you have to do now is copy and merge your updates back into the RasGUI directory tree. The copy operation could easily be automated (although we haven't actually done this yet). The merge operation, however, must be done manually, because the details can vary:

• For autopd.properties, you presumably want to end up with a file containing everything contained in the latest version of the tool, but with any properties you previously overrode still overridden to your values.
• For autoPDMenu.xml, it really depends on how you want the GUI to appear. If, for example, you want the main Problem Type tree to include all of the problems supported by the tool together with your new problems, then you would merge your autoPDMenuItem elements in with the tool's. If, however, you want the main Problem Type tree to include your new problems instead of those supported by the tool, you would replace the tool's autoPDMenuItem elements with your own.

Back to top

Summary

In this article, you examined many, but not all, of the ways in which the AutoPD tool can be extended to address more than just the particular set of problem scenarios it handles when first downloaded. This article focused on two specific areas: adding new problem types to the tool's user interface and creating new Ant scripts that take advantage of the tool's capabilities. One of the tool's major capabilities, its pattern-based symptom analysis and how it can be extended or customized, is the subject of the next article.

• Download page for the most current version of the Automated Problem Determination Tool
  

Resources

• The developerWorks WebSphere Portal zone contains links to many sources of information related to WebSphere Portal.
  
  
• Information about Ant can be found in the Apache Ant User Manual.
  
  
• Appendix A. Understanding Common Base Events Specification V1.0.1 provides an overview of Common Base Events.
  
  
• The Autonomic Computing Toolkit offers a selection of additional autonomic computing tools to try.
  
  
• Software developers, see the developerWorks Autonomic computing zone for articles, tutorials, and downloads related to autonomic computing.
  
  
• For more information on OSGi, see the OSGi Alliance.
  

About the authors

		Bob Moore is an Advisory Software Engineer with the Software Group Advanced Design and Technology team at IBM in Research Triangle Park, North Carolina. He received his Ph.D. in Philosophy from Duke University in 1977. Since joining IBM in 1983, he has worked on numerous architectures and standards related to network and systems management, including SNA/Management Services, CMIP, SNMP, and DMTF CIM. You can contact Bob at remoore@us.ibm.com.

		Brad Topol is a Senior Software Engineer with the Software Group Advanced Design and Technology team at IBM in Research Triangle Park, North Carolina. He received a Ph.D. degree in Computer Science from the Georgia Institute of Technology in 1998. Currently, he is the development lead for the Automated Problem Determination Serviceability Tool. Over the years, Brad has been actively involved in advanced technology projects in the areas of autonomic computing, Web services, grid computing, Web content transformation, and aspect-oriented programming. You can contact Brad at btopol@us.ibm.com.

		Jie Xing is an Advisory Software Engineer with the Software Group Advanced Design and Technology team at IBM in Research Triangle Park, North Carolina. He is involved in advanced technology projects in the areas of Web services, grid computing, and autonomic computing. He received his Ph.D. in Operations Research in Computer Science from North Carolina State University in 2001, where his research areas were related to multiagent systems, distributed systems, and service composition. You can contact Jie at jiexing@us.ibm.com.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top