INTRODUCTION

System Overview

The Earthworm Alarms System is intended to satisfy the need for an easy-to-use, web-centered method for dispatching notifications about automatic and reviewed earthquakes. The initial requirements are that the system must support several delivery mechanisms such as email, pager, and QDDS. Furthermore, the user must be able to specify and modify the text of the notification messages. The system must keep an audit of all notifications that were sent, and this audit should be used to ensure that subsequent alarms are sent to the same list of recipients who received the original notification.

The system is comprised of an Oracle database, SQL and C source code which allows for manipulation of the database objects, web server resident C source code which processes web forms, and an Earthworm configuration with a ring onto which alarms messages are written and from which alarms processing modules actually execute alarm notifications. See below for more details on the system setup.

This document is intended for the target user of the system, one who has a managerial decision capacity to define who will receive what types of alarm notifications. The user should also be familiar with Earthworm as well as with the Earthworm Quick Review (EQR) system.

Glossary Notes

Format. The Earthworm Alarms System allows flexibility in defining and modifying the formats in which alarms messages are delivered. Using the Formats Manager (see below for more details) each format is assigned two message templates: insertion and deletion. The Formats Manager uses a token-based template to allow easy definition of new formats. Each token is bracketed by the ~ character, and each format definition must end with the ~End~ token. The system then replaces each token with the particular value associated with the event which caused the event to be issued:

The following tokens are currently recognized:

• ~EventID~ : Database ID assigned to the event.
• ~Otime@TIMEZONE~ : Origin time for the event.TIMEZONE must specify a valid value for the TIMEZONE environmental variable corresponding to the timezone for the desired display. If the @TIMEZONE is omitted, the time will be displayed in the timezone of the webserver.  Example: ~Otime@US/Mountain~ will display the origin time in Mountain Time.
• ~Towns@<TOTAL>,<BIG>~:  List of towns nearest to the event.  <TOTAL> is the total number of towns to list, <BIG> is the number of big or significant towns.  The population limit for big towns is specified by the administrator in the Review configuration file.  Example:  ~Towns@5,2~ will display five nearest towns, two of which will be "big" with population above the limit set in the configuration file.
• ~PrefMag~ : Preferred Magnitude.
• ~Md~ : Duration Magnitude.
• ~ML~ : Local Magnitude.
• ~Lat~ : Latitude in degrees with the format of +/- xx.xxxx.
• ~Lon~ : Longitude in degrees with the format of +/- xxx.xxxx.
• ~Depth~ : Depth (km).
• ~Nph~ : Number of phases used in the solution.
• ~Dmin~ : Distance to nearest station (km).
• ~Rms~ : rms misfit (seconds).
• ~ErrLat~ : Lattitudinal location error (km).
• ~ErrLon~ : Longitudinal location error (km).
• ~ErrZ~ : Vertical location error (km).
• ~Gap~ : Azimuthal gap (degrees).
• ~RevAuto~ : If the solution is automatic this token is replaced with the string Automatic, otherwise the string Reviewed is used.
• ~InvokedBy~ : This token is replaced with a string supplied by the program which invoked the execution of alarms. This is useful for distinguishing alarms raised when various parameters of an event are inserted into the database.
• ~End~ : Required at the end of each format.

Criteria Program. A Criteria Program (CP) is simply one attribute of the alarm specification. It is a program written in any language, invoked by the alarms system. It is passed information about the event and it signals back to the caller whether the event passed some set of criteria defined and checked by the program. CP?s are specified in the Program Manager (see below for more details).
 
 

WEB FORMS

The main component of the system is a sequence of web forms which interact with the database allowing the user to manage recipients, formats, and criteria programs.

Alarms Manager

The Alarms Manager web form is the starting point of the system. It is divided into three areas allowing the user to add or modify recipients, formats, and criteria programs. Each area presents a list of previously defined entries (if any) as well as the option to define a new entry. To create a new entry, the user highlights the choice for a new entry (New Recipient, New Format, New Program) before clicking Submit. To view, modify, or delete an existing entry, the user highlights the desired entry and clicks Submit. By clicking Submit, the user enters the relevant sub-manager area, i.e., Recipient Manager, Format Manager, or Program Manager, described below in more detail.

The Format area also allows the user to preview a previously defined format by highlighting a format in the list and then clicking on Preview. In this case, the insertion and deletion templates will be shown with the recognized format tokens highlighted in red.

Recipient Manager

The Recipient Manager allows for adding, deleting, and modifying rules which trigger alarms. Each rule consists of the following attributes:

• Delivery mechanism - email, pager, phone, or QDDS
• Message Format - user-defined templates such as CUBE.
• Minimum magnitude threshold.
• Automatic or reviewed solution
• Criteria Program - program which checks against user-defined criteria.

Here, the user will be prompted for further information based on the delivery mechanisms desired, such as the recipient?s email address, phone number, or QDDS target directory.

Clicking Submit will insert the recipient and all defined rules into the database.

The Recipient Manager can also be invoked for a previously defined recipient. In this case, the web form will show all rules defined for the recipient along with blank spaces for five more rule definitions. Along with the Submit button, which acts as described above, there is a Delete button which will delete the current recipient and all associated rules from the database. Furthermore, in this mode each individual rule can be deleted by clicking the Delete Rule checkbox. The attributes of each existing rule can also be changed by changing the magnitude limit, or selecting a new or different delivery method and format before clicking Submit.

If Delete Recipient is clicked, a confirmation form is shown where the user must click Continue to actually delete the rules from the database.

Note: the system does not enforce any content-based constraints on the rule attributes. Therefore, it is up to the user to correctly match the delivery mechanism with the desired message format (e.g., messages delivered by QDDS should typically be in CUBE format).

Format Manager

Each format has three required attributes:

• Description - Human readable description of the format (e.g., CUBE, pager).
• Insertion Format - Insertion template consisting of the text of the message including tokens which will be translated into the notification message sent when an event is inserted into the database.
• Deletion Format - Deletion template consisting of the text of the message including tokens which will be translated into the notification message sent when an event is deleted from the database.

Note: The user must specify both the Insertion Format and Deletion Format.

Note: the CUBE format is pre-defined in the source code and can only be changed by modifying source code.

Program Manager

A criteria program (CP) is a program written in any language, invoked by the alarms system. It checks the information about an event against any predetermined set of criteria, such as magnitude range, location, type, and even trends or swarms.

Each CP has three required attributes:

• ProgramName - Full path to the location of the program executable.
• ProgramDir - Temporary directory where this program has write permission. This is necessary for simple communication between the calling program and CP. ProgramDesc- human readable description of what this CP checks for (e.g., Utah Polygon, Menlo Automatics 2.5).

Criteria programs are stand-alone programs. This causes some challenges with respect to communication to the rest of the alarms system. Each CP is executed as a stand-alone program and it writes its results to a file in the temporary program directory where the alarms system knows to look for those results. Therefore, the directory specified by ProgramDir attribute must be writeable to the web server application.
 
 

SYSTEM SETUP

The system is comprised of an Oracle database, SQL and C source code which allows for manipulation of the database objects, web server resident C source code which processes web forms, and an Earthworm configuration with a ring onto which alarms messages are written and from which alarms processing modules actually execute alarm notifications.

The installation and setup of the Oracle database is beyond the scope of this document. This section assumes that Oracle has been installed and that the latest version of the Earthworm DBMS schema has been successfully loaded.

Because the Quick Review system is closely related to the alarms system, reference to the EQR documentation is recommended.
 
 

Configuration Files

The Alarms System uses two configuration files:

• alarms.d - defines database connection parameters, hostname of the web server, and the path to a temporary directory which must be writeable to the web server.
• review_event.d - defines the name of an Earthworm ring into which alarms messages are written. Refer to EQR documentation for more details.

In order for alarm notifications to be issued and delivered, an Earthworm construction must be running on the web-server host. At the minimum, it must contain one ring into which the EQR system writes alarms messages, and one or more delivery modules.

The following message types are currently supported:

TYPE_EMAIL_MSG

<email address>

<mail server>

<subject line text>

<database ID of the audit associated with the alarm>

<text of the alarm message>

TYPE_QDDS_MSG

<target directory>

<database ID of the audit associated with the alarm>

<text of the alarm message>

TYPE_CUSTOM_MSG

*** Format not yet defined ***

TYPE_PAGER_MSG

*** Format not yet defined ***
 
 

The following two delivery modules are currently available:

• email_sender - picks up TYPE_EMAIL_MSG messages from the ring, parses them and calls the SendMail() earthworm library routine to delivery the message. Then, it updates the appropriate entry in the AlarmsAudit table to indicate that the message has been delivered.
• qdds_sender - picks up TYPE_QDDS_MSG messages from the ring, parses them and writes the text of the message to the specified QDDS target directory. For now, this program only deals with placing the files in CUBE format into the correct directory, leaving the bulk of the delivery work to an outside QDDS-capable process.