Self Service Alerts

This section contains the following:

§        “Overview” on page 1046

§        “Alert Settings Table” on page 1047

§        “Self Service Audit Table” on page 1048

§        “Alert Construction Limitations” on page 1049

§        “Self Service Alert Demo” on page 1049

Overview

The Self Service Alerts functionality allows threshold, duration and enabled settings of alert definitions to be modified at run-time. Alert definitions are created in the Display Builder and are generally loaded at startup by the Display Server and Data Server. However, sometimes end-users of RTView prefer to modify alert settings at run-time rather than reload a modified alert definition. To enable run-time modification, current values of alert settings are maintained in a database. Optionally, this database can also store an audit trail tracking who has modified alert settings and when those changes were made.

To enable and configure Self Service Alerts and the database to persist alert settings, go to the “Self Service Alerts Tab” in the Application Options dialog. To provide end-users with an interface to modify alert settings, a “Self Service Alert Demo” is included that can be used stand-alone or integrated into your RTView application.

Two database tables are used for Self Service Alerts: the “Alert Settings Table” is required and the “Self Service Audit Table” is optional. An hsqldb database that contains these tables is provided as part of the Self Service Alerts demo.

Note: For other database types, the demos\selfservicealerts\dbconfig directory contains .sql files with the correct table schemas and a README.txt that explains how to use them.

Alert Settings Table

 When Self Service Alerts are enabled, RTView will attempt to connect to the Alert Settings Table in the specified Self Service Alerts Database.

Note: No alert configuration files will be processed until it receives the first update of this table. To view your Alert Settings Table table, make a data attachment to the Alert Settings Table from the “Attach to Alert Data Dialog”.

Column names, types and order must match exactly.

For all alert types, when the alert is loaded RTView will look for a row in the Alert Settings Table with that alert name. If it isn't found, a row will be added. Once the row has been added, the value in the database will be used instead of the value in the property sheet for the corresponding properties. Note that the specified database and table(s) will apply to all alerts; there is no flag to indicate that for a single alert you want to use the values in the property sheet instead of the database.

The initial values for the DURATION and ENABLED fields will be set from the alertDelayTime and enabledFlag properties respectively. For an Event alert, only the ENABLED field will be set. WARNINGLEVEL, ALARMLEVEL, and DURATION are not supported for Event alerts. For all other alerts, values for ALARMLEVEL and WARNINGLEVEL will be set from different properties depending of the alert type:

§        For a Limits alert, the valueHighAlert and valueHighWarning properties map to the ALARMLEVEL and WARNINGLEVEL fields. If these are both disabled, the valueLowAlert and valueLowWarning properties are used. If either valueHighAlert or valueHighWarning are enabled, then valueLowAlert and valueLowWarning are not mapped to the database even if they are enabled (they'll use the values in the property sheet). Note: If only one threshold is enabled only that value will be added to the table and the value for the other field will be inserted into the database as NaN which indicates that the value isn't used.

§        For a Discrete alert the valueHighAlert property maps to the ALARMLEVEL field and the valueLowAlert property maps to the WARNINGLEVEL field. Again, only fields that are enabled are mapped and written to the database. The valueMediumAlert property is never mapped to a field in the database. Note: ALARMLEVEL and WARNINGLEVEL database columns are of type Double, so string thresholds cannot be entered in the database.

§        For a Multi State alert, AlertState01Comparison is mapped to ALARMLEVEL and AlertState02Comparison is mapped to WARNINGLEVEL. Again, only fields that are enabled are mapped and written to the database. Also be aware that range comparison types are not mapped to the database, nor are any alert states beyond Alert State 02. Note: ALARMLEVEL and WARNINGLEVEL database columns are of type Double, so string thresholds cannot be entered in the database.

§        For an Event alert, only the ENABLED field can be set. The WARNINGLEVEL, ALARMLEVEL, and DURATION are not supported.

Self Service Audit Table

If Self Service Alerts are enabled and a Self Service Audit Table is specified on the Self Service Alerts tab of the Application Options dialog, then RTView will insert an entry into the Self Service Audit Table each time it makes a change to the Alert Settings Table. To view your Self Service Audit table, make a data attachment to the Self Service Audit Table from the “Attach to Alert Data Dialog”.

Column names, types and order must match exactly.

The Self Service Audit Table contains the TIME_STAMP of the change, the USER that made the change, the ACTION that was done, plus row information.

§        If the USER listed is RTView.GmsRtViewAlertDs, this indicates that RTView made the change. This happens when a row is added for a new alert, when the threshold enabled flag for an alert that was already in the database changes and when a row is removed due to a selected Clean Settings Table On Startup option.

§        If the USER value is No Login, this indicates that no value was specified for the user in the Update Self Service Alerts command. This could be because RTView login is disabled or because the command was not configured to include a user name.

Alert Construction Limitations

The following limitations apply when creating alerts to use with Self Service Alerts:

§        Alerts can only use numeric threshold values

§        Alerts can only use 1 or 2 thresholds:

–      Limits alerts can use valueHighAlert and valueHighWarning or valueLowAlert and valueLowWarning

–      Discrete alerts can use valueHIghAlert and valueLowAlert

–      Multi-state alerts can use AlertState01Comparison and AlertState02Comparison.

§        Threshold values cannot be attached to data.

Self Service Alert Demo

Self Service Alerts makes it easy to set and persist threshold, duration and enabled settings for your alerts in a database. For details, see “Self Service Alerts”.

The Self Service Alerts demo is located in your RTView installation directory under demos\selfservicealerts. The demo can be modified and used stand-alone or integrated into your RTView application in order to view and administrate alerts. The demo contains some demo alerts and a pre-configured hsqldb database to store your alert settings. See “Modify the Stand-Alone Demo” and “Integrate the Demo into an RTView Application” for more information.

Note: For other database types, the demos\selfservicealerts\dbconfig directory contains .sql files with the correct table schemas and a README.txt that explains how to use them.

The demo contains three main displays (Alert Detail Table, Alert, Administration and Administration Audit). In the top right corner, each display shows the current time, a * button that opens the display in a new window and a ? button that opens Help. These objects are customizable and can be modified, removed or replaced. See the “Customization Options” section for details.

Running the Demo

In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), navigate to the demos/selfservicealerts directory:

1.     Start the XML simulator:

type start run_simdata

2.     Start the hsqldb database:

type start run_hsqldb

3.     Confirm that the demo server is running, if not start it by typing:

run_startup_demoserver.

You can view the demo in the Display Viewer or the Thin Client.

4.     To view the demo in the Display Viewer:

type run_viewer

OR

To view the demo in the Thin Client:

type run_displayserver

open a browser to http://localhost:8068/ssa/panels.html

Alert Detail Table

This display shows all of your current alerts:

Field Name	Description
Admin	Click on this button to open the Alert Administration display in a new window.
You can filter the displayed alerts as follows:
Alert Name Filter	Select an alert name from the list to filter the table by the Alert Name column.
Alert Text Filter	Enter a value to filter the table by the Alert Text column. For example, a value of *High* will filter to rows where the alert text contains the word High. A value of High* will filter to rows where the alert text starts with High.
Show Critical Alerts Only	Only show alerts with a severity greater than 1.
Show Cleared Alerts	Show cleared alerts. The number following the Show Cleared Alerts label indicates the number of cleared alerts that match the selected Alert Name Filter and Show Critical Alerts Only values.
Show Acknowledged Alerts	Show Acknowledged alerts. The number following the Show Acknowledged Alerts label indicates the number of active (not-cleared) acknowledged alerts that match the selected Alert Name Filter and Show Critical Alerts Only values.
The following counts show the number of alerts that match the selected Alert Name Filter, Show Critical Alerts Only, Show Cleared Alerts, and Show Acknowledged Alerts values:
Total	Total number of alerts.
Critical	Number of alerts with a severity greater than 1.
Warning	Number of alerts with a severity of 1.
Alert Settings ConnOK	Indicates the connection status of the Alert Settings table.
Current Alerts Table	Displays all alerts that match the selected filters. §        Red rows indicate the alert has a severity greater than 1. §        Yellow rows indicate the alert has a severity of 1. Select one or more alerts from the table to enable the action buttons below the table. To select more than one alert: §        Click on one alert, then hold the Shift key while clicking on another alert. All alerts in between will be selected. §        Click on one alert, then hold the Control key while clicking on one or more other alerts. Only the alerts you click on will be selected. §        Click on one alert, then hold the Shift key while pressing the up or down arrow on your keyboard. All alerts in between will be selected. §        Click on one alert, then press Control+A to select all alerts in the table.
Selected Alert(s)	Lists ID of currently selected alerts.
The following action buttons are located below the Current Alerts table:
Acknowledge One Alert/Acknowledge Multiple Alerts	Acknowledge the selected alert(s). If more than one alert is selected, you will be asked to confirm before the alerts are acknowledged. If only one alert is selected, it will be acknowledged without confirmation.
Set Owner and Comments	Click to open the Set Owner and Comments display. The ID field at the top of the display lists the IDs for all selected alerts. Any action will be applied to all alerts in that list.
	Set the Owner-The value of the Enter Owner field is filled in as the user name used when you logged in. If you are logged in with a role of admin or login is disabled, you can specify a different value for the owner. Click Set Owner on One Alert/Set Owner on Multiple Alerts to set the owner field for the selected alert(s) to the value specified in the Enter Owner field. Note: If more than one alert is selected, you will be asked to confirm before the owner is set on the alerts. If only one alert is selected, the owner will be set without confirmation.
	Add a Comment - Type a comment in the Enter Comment field, then click Add Comment to One Alert/Add Comment to Multiple Alerts to add the comment to the selected alert(s). The comment will be added to the alert(s) along with the timestamp and the user name from your login. Note: If more than one alert is selected, you will be asked to confirm before the comment is added to the alerts. If only one alert is selected, the comment will be added without confirmation.
	Clear All Comments - Click Clear Comments on One Alert/Clear Comments on Multiple Alerts to clear all comments from the selected alert(s). Note: If more than one alert is selected, you will be asked to confirm before the comments are cleared from the alerts. If only one alert is selected, the comments will be cleared without confirmation.
Details	Click to open the Alert Detail display to view details about the selected alert. Note: If more than one alert is selected, this display will show the details for the last alert in the selection list. See the “Customization Options” section for details on customizing this display.
Options	Click to open Options display showing options for the selected alert.
	Note:  By default, the Options button in the Alert Details table display is hidden. See the “Customization Options” section for details on showing this button and customizing this display.

Alert Administration

This display shows you the current values in the Alert Settings Table in the Self Service Alerts database.

Tabular Alert Administration

This display allows you to override the default warning, alarm and enabled settings on a per-index bases.

Administration Audit

This display shows a history of alert administration actions executed in the Alert Administration and Tabular Alert Administration displays. The Self Service Audit Table contains the TIME_STAMP of the change, the USER that made the change, the ACTION that was done, plus row information.

Alert Action Audit Trail

This display shows a history of alert actions executed in the Alert Detail display.

Modify the Stand-Alone Demo

Replace Demo Alerts

To use the Self Service Alerts demo to monitor your own alerts, you must first replace the demo alerts with your own. There are two ways to do this:

1.     Save your alert definitions in a file named rtv_alertdefs.rtv and replace the rtv_alertdefs.rtv in the selfservicealerts demo with yours.

OR

2.     Save your alert definitions in one or more .rtv files in the demos/selfservicealerts directory.

1. Run the Display Builder from the selfservicealerts directory.

2. In the Display Builder, select Tools>Options.

3. In the Application Options dialog, select Alerts>“Alert Definitions Tab” and remove rtv_alertdefs.rtv and add your own alert definition files.

4. Save and exit the Display Builder.

In either case, your alerts must be constructed as documented for self service alerts.

Replace Demo (hsqldb) Database

To use a different database to store your alert settings, modify the ALERTDB SQL Database Definition.

1.     Run the Display Builder from the selfservicealerts directory.

2.     In the Display Builder, select Tools>Options.

3.     In the Application Options dialog, select SQL.

4.     Edit the ALERTDB database connection to point to your database.

5.     If necessary, change the Settings Table Name and Audit Table Name entries on the Alerts>“Self Service Alerts Tab” of the Application Options dialog.

6.     Save and exit the Display Builder.

The dbconfig directory, located in the selfservicealerts directory, contains SQL schema files for several databases. You can use these files to create the necessary tables in your database. See the README.txt file in that directory for instructions.

Clear Demo (hsqldb) Database

You can also clear the included hsqldb database by running the DATA\reset_alerts script while the database is not running. This will remove all entries from the Alert Settings Table and the Self Service Audit Table.

Modify Alert Options

The Self Service Alerts demo is setup to limit the number of active alerts in the Alert Detail table to 2000, which removes cleared alerts every 5 minutes. If you anticipate a larger number of active alerts in the Alert Table at one time, you will need to increase this value. You can also adjust the rate at which cleared alerts are removed. Both of these options are available on the “Alerts Tab” of the Application Options dialog.

This demo is setup to use a Custom Alert Definition Property named DrillDownSuffix. You may add additional Custom Alert Definition Properties. See “Custom Alert Fields Tab” for more information.

Customization Options

The Self Service Alerts demo is set up to be easily customized in a few ways:

Modify the time label, new window button, and help buttons in the header

§        These objects are all contained in rtv_alerts_header_include.rtv. Edit this display to add or modify the objects displayed in the header of the displays.

Note: Do not add objects to the center or left top as they will be obscured by objects in the displays.

Use the $rtvAlertDataServer substitution

§        If you have deployed your alerts to a data server, specify the name of that data server for the $rtvAlertDataServer substitution on the General>Substitutions tab in the Application Options dialog.

Use the $rtvUserAlertOptionsEnabled substitution

§        By default, the Options button in the Alert Details table display is hidden. To make it visible, specify a value of 1 for the $rtvUserAlertOptionsEnabled substitution on the General>Substitutions tab in the Application Options dialog.

Override the Options display and do a per-alert-type override

§        Modify the user_alert_options.rtv file to add your own custom alert options. This is useful if you have added Custom Alert Event Attributes that you want your user to set. This file will be displayed when you click on Options in the Alert Detail Table for an alert that has no value for the DrillDownSuffix property in the alert definition. To create a different Options display for different alert definitions, specify a value for the DrillDownSuffix on the alert(s) where you don't want to use the default display. When Options is selected for an alert where the DrillDownSuffix is specified, it will open a file named user_alert_optionsDrillDownSuffix.rtv where DrillDownSuffix is the value you specified in the DrillDownSuffix property for that alert definition.

For example, let's say you have the following alert definitions:

MyAlert1 - This has no value for the DrillDownSuffix property. When you select an instance of MyAlert1 from the Alert Detail Table and click the Options button, it will open user_alert_options.rtv.

MyAlert2 - This has the value "_alert2" for the DrilldownSuffix property. When you select an instance of MyAlert2 from the Alert Detail Table and click the Options button, it will open user_alert_options_alert2.rtv.

MyAlert3 - This has the value "_alert3" for the DrilldownSuffix property. When you select an instance of MyAlert3 from the Alert Detail Table and click the Options button, it will open user_alert_options_alert3.rtv.

Override the Details display and do a per-alert-type override

§        Modify the user_alert_ details.rtv file to add your own custom alert details. This is useful if you've added Custom Alert Definition Properties or Custom Alert Event Attributes that you want to display. This file will be displayed when you click on Details in the Alert Detail Table for an alert that has no value for the DrillDownSuffix property in the alert definition. To create a different details display for different alert definitions, specify a value for the DrillDownSuffix on the alert(s) where you don't want to use the default display. When Details is selected for an alert where the DrillDownSuffix is specified, it will open a file named user_alert_detailsDrillDownSuffix.rtv where DrillDownSuffix is the value you specified in the DrillDownSuffix property for that alert definition.

For example, let's say you have the following alert definitions:

MyAlert1 - This has no value for the DrillDownSuffix property. When you select an instance of MyAlert1 from the Alert Detail Table and click the Details button, it will open user_alert_details.rtv.

MyAlert2 - This has the value "_alert2" for the DrilldownSuffix property. When you select an instance of MyAlert2 from the Alert Detail Table and click the Details button, it will open user_alert_details_alert2.rtv.

MyAlert3 - This has the value "_alert3" for the DrilldownSuffix property. When you select an instance of MyAlert3 from the Alert Detail Table and click the Details button, it will open user_alert_details_alert3.rtv.

Use the $rtvUserAlertActiveColumnEnabled substitution

§        By default, the Active column in the Alert Administration display is hidden. To make it visible, specify a value of 1 for the $rtvUserAlertActiveColumnEnabled substitution on the General>Substitutions tab of the Application Options dialog.

Help files

§        The help button (?) in the top left corner of the display is configured to display help files located in the docs directory of the demo. To modify this button to look for help files in another location, add a substitution named $displayHelpURL and set it to the url where you are hosting your help files.

§        To change the name of the help file for each display, modify ssa_displays.xml. This xml file has an entry for each .rtv file in the demo with the name of the corresponding html file to load. This file will be loaded from the url specified in $displayHelpURL.

Integrate the Demo into an RTView Application

Before integrating this demo into your RTView application, you must configure it as described above to monitor your alerts and store the settings in the database of your choice.

Once you have done this, proceed with the following instructions:

1.     Copy all of the .rtv files from the demos/selfservicealerts directory to your RTView application directory. If you will be using the built-in help files, also copy ssa_displays.xml and the selfservicealerts\docs directory to your RTView application directory.

2.     Copy ALERTOPTIONS.ini and CACHEOPTIONS.ini files to the directory where you will be running the alerts. This might be your application directory, or it might be the directory where you are running the Data Server if you want the alerts to run in the Data Server.

Note: If this directory is not your application directory, move your alert configuration files (rtv_alertdefs.rtv and/or your other alert configuration files) and rt_alerts_cache.rtv to the same directory as ALERTOPTIONS.ini and CACHEOPTIONS.ini. Then, copy values from those files in the selfservicealerts directory into the corresponding OPTIONS.ini files in your application.

3.     Add the ALERTDB option to the options file in the directory where you put the ALERTOPTIONS.ini and CACHEOPTIONS.ini:

§        If the directory where you put ALERTOPTIONS.ini and CACHEOPTIONS.ini already contains an OPTIONS.ini file, then add the lines that start with sqldb ALERTDB and dbretry from demos/selfservicealerts/OPTIONS.ini file to that file.

§        If the directory where you put ALERTOPTIONS.ini and CACHEOPTIONS.ini does not contain an OPTIONS.ini file, copy the OPTIONS.ini file from demos/selfservicealerts to there.

4.     In your application directory, add the following display (.rtv) files to your panel configuration file:

rtv_alerts_table.rtv (Alert Detail View)

rtv_admin_alerts.rtv (Alert Administration)

rtv_alerts_audit.rtv (Administration Audit)

5.     The Self Service Alerts demo uses the style sheets rtv_darkstyles.rts and rtv_flat.rtv to set the look and feel of the displays. If your application already uses these style sheets or if you do not want to apply a style sheet, you are finished.

a. If you want to apply the style sheets to your whole application:

In the Display Builder select Tools>Options. In the Application Options dialog, select General>Style Sheet. Click Add Built-in Styles and select rtv_darkstyles.rts and rtv_flat.rts. If you do not want these style sheets applied to the main Display Builder window, deselect Apply Style Sheets to Main Builder Window. Save your options and exit the Display Builder.

b. If you only want to apply the style sheets to the Self Service Alerts display files:

Open each of these files in the Display Builder and in each display, select Tools>Style Sheets. Click Add Built-in Styles and select rtv_darkstyles.rts and rtv_flat.rts. Click OK and save each display.

6.     If you will be deploying the Self Service Alerts in a thin client application and you will be using the built-in help files, include selfservicealerts\docs in the .war file for your thin client application. See the make_war.bat script, located in the selfservicealerts directory, as an example of how to include this in your war file.