Defining tools

You can create tools that are executed from right-click menus in event lists or when users click a widget. The tool formats supported are CGI, SQL, Command-line, and Script.

1. Click Administration > Event Management Tool > Tool Configuration. Then, click Create Tool and select the tool type from the Type list.
   Tip: To modify a tool, select a tool from the list. To copy an existing tool, select the tool from the list and click Copy Tool.
2. Click Data Source and select the data sources that are used to retrieve the fields against which the tool can be run.
   The data sources also determine which user groups and event classes can be used to define the access criteria in step 10. The data sources that you select in this step are not used for the event feed, only for determining fields, users, and event classes.
3. Click Data Source to select the data sources against which you want to run the SQL instructions.
   The data source selection also specifies the user groups or classes that are used to define the access criteria.
4. Type a name for the tool in the Name field. Do not use spaces or special characters in the name.
   By default, the following characters cannot be used in tool names: $ ! £ % ^ & * ( ) + = ¬ ` ~ # @ ' : ; < > { } [ ] ? / \ \ | , ". By default, the following characters cannot be used as the initial character of tool names: / \ \ * ? " < > | & .. These illegal characters are defined in WEBGUI_HOME/etc/illegalChar.prop.
5. To configure the tool, complete the step for the tool type that you selected in step 1.
   The GUI displays the configuration options only for the selected tool type.

   Tool type	Complete this step.
   CGI/URL	6
   SQL	7
   Command-line	8
   Script	9

   After you complete the step in the table, proceed to step 10.
6. To define a CGI/URL tool, complete the following fields:

   URL

   Type the location of the CGI script. By default, this field contains the correct path to the cgi-bin directory on the local Web GUI server. The $(SERVER) keyword is resolved at run time to protocol://host:port/ibm/console/webtop/. Append the path with the file name of the script that you want to associate with the tool. To pass field data to a script on a remote server, replace $(SERVER) with an external URL address. For example, http://www.ibm.com.

   Fields

   Click Show. From the Available column, select the ObjectServer columns that you want to pass as arguments to the tool. If you select multiple data sources from the Data Sources list, the Fields list contains only columns that are common to all data sources.

   Note: To pass a list of all selected rows to a tool:

   • Select Serial from the Fields list.
   • Select the Execute for each selected row check box.
   • Clear the Window for each selected row check box.
   • If you select multiple data sources, add the $selected_rows.datasource parameter to the CGI script.

   At run time, the Serial field resolves to the $selected_rows.Serial parameter. For multiple data sources, the $selected_rows.datasource parameter distinguishes between identical serial numbers from different data sources.

   Method

   Specify the method for submitting field data to the CGI script:

   GET

   Appends the name-value pairs to the URL. This option is useful to bookmark the page that contains the output.

   POST

   Encodes the name-value pairs inside the body of the HTTP request. Firewalls can be configured to intercept and destroy this DataStream, causing the form to be interpreted as empty.

   The CGI script receives the data via a QUERY_STRING environment variable regardless of the method chosen. This method of receiving data differs from the CGI convention where, if POST is used, the script receives data via stdin.

   Open in

   Defines where the tool output is displayed. If you select Specific window, type a name for the window in the adjacent text field.

   Execute for each selected row

   Runs the tool against all individual selected rows in the event list. Clear the check box to run the tool against only the first row in the selection.

   Window for each selected row

   Select this check box to open a separate window for each selected row in the event list.

7. To define an SQL tool:
   1. Type the SQL command and specify how the SQL tool runs by completing the following fields:

      SQL Commands

      Type the SQL commands that you want to update the alerts.status table.

      Execute for each selected row

      To run the tool against all the selected rows in the event list, select this check box. Clear the check box to run the tool against only the first of the selected rows.

      Important: Do not select this check box if the SQL instructions explicitly state that the command must run against all rows.

   2. To update the alerts.journal table of the data sources, click SQL and complete the following fields:

      Journal Entry

      Type the SQL commands that you want to update the alerts.journal table. If you leave the field empty, no journal entry is made when the tool is run. If you want a blank journal entry to be made, enter a space or type any single character.

      Tip: You can use a Multiline String prompt for forced journal entry.

      Execute for each selected row

      To run the tool against all the selected rows in the event list, and make all the corresponding journal entries, select this check box. To run the tool against only the first of the selected rows, and make only one journal entry, clear the check box.

8. To define command-line tool, complete the following fields:

   Platform

   Select this check box to specify which client operating system types can access this tool from the event list.

   Command

   For each selected client operating system, change the default entry and type the command to launch the target application. Include the full path to the command.

   Tip: Use the following construct to ensure the DOS console closes when the tool completes: start /b cmd /k.

   You can launch multiple applications from one tool by inserting && between each command. For example, to launch two Internet Explorer windows, use start /b cmd /k cmd iexplore.exe && start / cmd /k iexplore.exe.

   Execute for each selected row

   Runs the tool against all individual selected rows in the event list. Clear the check box to run the tool against only the first row in the selection.

9. To define a script tool, complete the following fields:

   Script Commands

   Type the script that you want the tool to run.

   Execute for each selected row

   Runs the tool against all individual selected rows in the event list. Clear the check box to run the tool against only the first row in the selection.

10. Define the Access Criteria for the tool.
    Access to tools is based on membership of user groups and the class of events.

    Group

    Select the user group that you want to give access to the tool and click >. To give all groups access, click >>. If you multiple data sources are selected, all groups from all selected data sources can be selected.

    Fields

    Select the field against which the tool can be run.

    • The Field options are defined by the available Colname of the ObjectServer alerts.conversions table. That is, only fields with conversion values are available options. Also, for a field to be an option it must be available in alerts.conversions across all data sources available in the Web GUI server.
      Note: A change of data source(s) selection in the Tool Configuration editor will reset the current access criteria conditions in the Field tab. This is to prevent stale data being used by the tool during access criteria testing. If the server detects that the field access criteria values for the tool are specified against invalid data source(s), that is data sources that have been removed after tool creation, the field access criteria for the tool will be erased in the Tool Configuration editor. As a best practice, if there are data source changes in your environment, the field access criteria values for a tool should be reviewed and re-saved.
    • The Comparator operators are described in the following table.

      Table 1. Comparison operators in Access criteria

      Operator	Description
      =	Tests for equality.
      !=	Tests for inequality.

    • The Value options are defined by the ObjectServer alerts.conversions table for a given Field.

    Two radio buttons allow for the selection of Any or All operator options. A tool can be run against a selected event if the event honors the conditions set by the access criteria, depending on the operator that has been selected.

    • All enables the tool when each field specified in the access criteria has at least one matched value to the selected event. This option is selected by default.
    • Any enables the tool when any of the fields specified in the access criteria have at least one matched value to the selected event.

    Note:

    1. The Active Event List only supports Access Criteria that include the Class field, groups, and the equality comparator.
    2. Event Viewer supports all Access Criteria, since V8.1.0.3.
    3. A tool that is defined with Access Criteria of multiple fields and has the equality operator = selected will automatically apply the Any condition to the multiple values for that Access Criteria, regardless of whether All or Any is specified. This is because there can be only one field value per event, and the All operator evaluates both top-level elements and child elements. For example, in Tool Configuration > Access Criteria > Fields select Class. Next, select multiple options from the drop-down list of Values. If the equality operator = is selected in this scenario, the Any condition is automatically applied to any Access Criteria with multiple values and the equality operator =.
    4. In order for Access Criteria to be applied to event fields, the fields must be part of the event list view. Otherwise, the Access Criteria condition will not be fulfilled, and the tool might not be available as expected. The following fields are always available for Access Criteria to be applied:
       • StateChange
       • Serial
       • Class
       • Flash
       • Acknowledged
       • OwnerUID
       • Severity
       • OwnerGID

11. Click Save.
    The tool appears as an entry in the list of available tools and is now available for use in the event lists.
12. Define how the output of the tool is resolved after the tool is executed:

    Option	Description
    New Window	Displays the output of the tool in a new browser window.
    Specific Window	Opens the tool output in a window of your choice. Type a name for the window in the text field.