• Introduction
• Recipient Menu
• Recipient Configuration
• Tools Menu
• Settings Dialog Window
• "Config" Tab
• "Filters" Tab
• "Connection" Tab
• "Alarm Regions" Dialog Window
• "Add/Edit Circle/Polygon Region" Dialog Window
• Libraries
  

     The QuakeWatch Emailer ("QWEmailer") program receives event messages from a QuakeWatch server and, subject to various user-configurable "alarm" criteria items, sends out alert email messages to a user-configurable list of recipients.  Two alert-message formats are supported:  The "long" format provides detailed information about the event, while the "short" format provides a concise description (suitable for pagers).
     This manual describes the configuration settings for the QWEmailer program.  These settings are accessible via the "Tools | Settings" menu item and via the alert-recipient configurations, and are stored in the "conf/QWEmailerConfig.xml" file in XML format.  The contents of this file are overwritten anytime the settings are modified.

     The "Recipient" menu contains the items described below.  Each of these menu items may also be selected by pressing the associated button to the right of the "Alert Recipents" list.  This list displays an entry for each alert recipient that has been entered into the program.

• Add Recipient ("Add" button):  Adds a new alert recipient to the program.  The "Recipient Configuration" window is shown and is used to enter the necessary information for the recipient.   See the "Recipient Configuration" section below for details.
• Edit Recipient ("Edit" button):  Edits the currently-selected recipient entry in the "Alert Recipents" list.  The "Recipient Configuration" window is shown and is used to edit the information for the recipient.   See the "Recipient Configuration" section below for details.
• Alarm Regions for Recipient ("Regions" button):  Edits the alarm regions for the currently-selected recipient entry in the "Alert Recipents" list.  See the "Alarm Regions" Dialog Window section below for details.
• Remove Recipient ("Remove" button):  Removes the currently-selected recipient entry in the "Alert Recipents" list.

     The "Recipent Configuration" window allows information for a recipient to be entered and edited.  All of the items in the "Recipent Configuration" window apply only to the one recipient.  The window contains several "tabbed" panels, one of which may be selected at a time.  These tabs and their items are described below.

At the bottom of the window are the following buttons:

• OK:  Accepts and saves all the changes made (on all the tabs) since the window was displayed.
• Cancel:  Discards all the changes made since the window was displayed.
• Reset:  Discards any changes made on the current tab and restores all the items on the current tab to the values they had when the the window was displayed.
• Defaults:  Discards any changes made on the current tab and sets all items on the current tab to their factory-default values (the values they had when the program was first installed).
• Help:  Displays the Settings Manual documentation, with the screen positioned on the section of the manual that describes the items on the current tab.

     The items on this tab configure the general operation of the recipient.

Recipient name:  The name to be associated with the recipient.

Email address(es):  One or more email addresses for the recipient.

Enable sending emails to this recipient:  When this checkbox is selected, the recipient is enabled and may be sent alert email messages.  When this checkbox is not selected, the recipient will never be sent alert email messages.

Use "long" email message format:  When this checkbox is selected, the alert email messages sent to the recipient will use the "long" format, which provides detailed information about the event.  When this checkbox is not selected, the alert email messages sent to the recipient will use the "short" format, which provides a concise description (suitable for pagers).

     The items on this tab configure the "alarm" criteria used to determine which events will trigger alert email messages.  Note that "alarm regions" may be configured for the recipient; see the "Alarm Regions" Dialog Window section for details.  The following items define the "recipient" alarm settings.

Minimum magnitude for alarm:  Sets the minimum-magnitude criteria value for the alarm.  The magnitude of an earthquake event must be at this value or greater for the alarm to be triggered.  This is a floating-point value.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.

Minimum depth for alarm:  Sets the minimum-depth criteria value for the alarm, in kilometers.  The depth of an earthquake event must be at this value or higher for the alarm to be triggered.  This is a floating-point value.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.

Maximum depth for alarm:  Sets the maximum-depth criteria value for the alarm, in kilometers.  If this value is greater than zero then the depth of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will be disabled.  This is a floating-point value.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.

Maximum event age (hours):  Sets the maximum-event-age criteria value for the alarm.  If this value is greater than zero then the number of hours passed since the event-time of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria will be disabled, allowing events of any age to trigger the alarm.  Note that all of the alarm criteria items must be satisfied for the alarm to be triggered.

Only verified events trigger alarm:  When this checkbox item is selected, only "verified" events (those that have been reviewed) will be allowed to trigger the alarm.

     The "Tools" menu contains the following items:

Settings:  Displays the "Settings Dialog Window", described below.

Reconnect to Server:  Disconnects from and then connects to the QuakeWatch server.

Connection Status:  Displays a window showing the current status of the connection to the QuakeWatch server.

Test Email-Server Connection:  Tests the connection to the SMTP email-server configured on the "Config" tab in the "Settings Dialog Window".

Send Test Email Message:  Displays a window that the user may use to send a test email message to the entered email address.

     Clicking on the "Settings" item in the "Tools" menu brings up the "Settings" dialog window.  The window contains several "tabbed" panels, one of which may be selected at a time.  These tabs and their items are described in the sections below.

At the bottom of the window are the following buttons:

• OK:  Accepts and saves all the changes made (on all the tabs) since the window was displayed.
• Cancel:  Discards all the changes made since the window was displayed.
• Reset:  Discards any changes made on the current tab and restores all the items on the current tab to the values they had when the the window was displayed.
• Defaults:  Discards any changes made on the current tab and sets all items on the current tab to their factory-default values (the values they had when the program was first installed).
• Help:  Displays the Settings Manual documentation, with the screen positioned on the section of the manual that describes the items on the current tab.

     The items on this tab define a set of general configuration parameters for the program.

'From' real-name for messages:  The "real" name that will appear in the "From:" field of sent alert email messages.

'From' email-address for messages:  The email address that will appear in the "From:" field of sent alert email messages.  For the sending of email messages to succeed, this setting must contain a valid email address.

Address of SMTP server for sending mail:  The address of the SMTP email server to be used for sending email alert messages.  For the sending of email messages to succeed, this setting must contain the address of an SMTP email server that will accept send-mail requests from the machine on which the program is running.

Maximum number of send-mail retries:  Sets the maximum number of times the program will attempt to send an alert email message after all previous attempts have failed.

Local time zone for messages:  Selects the "local" time zone to be used in alert email messages.  In "long"-format alert messages, both the "local" and the GMT event times are given.  If the "Use GMT for date/times in short messages" checkbox is not selected then the specified "local" time zone will be used in the "short"-format messages.

Use GMT for date/times in short messages:  When this checkbox is selected, the date/time shown in "short"-format alert email messages will use the GMT time zone.  When this checkbox is not selected, the messages will use the "local" time zone (specified via the "Local time zone for messages" setting).

Max loaded-events age (days):  Sets the maximum age (in days) for earthquake events to be held in the program's memory.  Events are held in memory to allow the program to keep track of which events have generated alert messages.  Events older than this age will be removed.  The age is measured from the event-time for the events and is specified as a floating-point value (which must be greater than zero).

     The items on this tab define the earthquake-event filter that is used to select which events are accepted as being eligible for generating alert email messages.  For an event to be accepted, it must satisfy all of the enabled filter items.  Events that do not satisfy all of the enabled filter items are ignored.

Minimum event magnitude:  Only earthquake events with a magnitude of this value or greater will be accepted.

Maximum event age (days):  Only earthquake events that are newer than this age (in days) will be accepted.  The age is measured from the event-time for the event and is specified as a floating-point value.  Setting this item to zero will disable it (allowing events of any age to be accepted).

Keep events from these data sources:  This item may contain a comma-separated list of data-source specifiers (i.e. "CI, NC").  If this item is not blank then only earthquake events with matching data-source specifiers will be accepted, and this item will override the "Drop events from these data sources" item.  If this item is blank then earthquake events from all data sources will be accepted (except those dropped via the "Drop events from these data sources" item).  The data-source specifiers are not case-sensitive.

Drop events from these data sources:  This item may contain a comma-separated list of data-source specifiers (i.e. "CI, NC").  If this item is not blank and the "Keep events from these data sources" item is blank then earthquake events with matching data-source specifiers will not be accepted.  If this item is blank then it will have no effect on filtering.  The data-source specifiers are not case-sensitive.

Minimum event latitude:  Earthquake events with a latitude less than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "Maximum event latitude" item are zero then earthquake events of any latitude will be accepted.

Maximum event latitude:  Earthquake events with a latitude greater than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "Minimum event latitude" item are zero then earthquake events of any latitude will be accepted.

Minimum event longitude:  Earthquake events with a longitude less than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "Maximum event longitude" item are zero then earthquake events of any longitude will be accepted.

Maximum event longitude:  Earthquake events with a longitude greater than this item's value will not be accepted.  The value is specified in decimal degrees.  If both this and the "Minimum event longitude" item are zero then earthquake events of any longitude will be accepted.

     The items on this tab define the parameters used for the connection to the server.

Server host address:  Sets the host-address value for the server.  The value may be in name (i.e. "www.caltech.edu") or numeric-IP (i.e. "131.215.220.4") form.

Server port number:  Sets the port-number value for the server.

Max secs for server alive msgs:  Sets the maximum number of seconds that this program will wait for a server "alive" message before determining that the message has been missed.  The server will transmit one "alive" message every ten seconds.  When server "alive" messages have been missed and the number of seconds elapsed since the last-received server "alive" message exceeds the "Server connection timeout" value, the program will attempt to reestablish its connection to the server.  Setting this item to zero will disable alive-message checking.

Server connection timeout (seconds):  Sets the number of seconds that this program will wait, after server "alive" messages have been missed, before attempting to reestablish its connection to the server.  Setting this item to zero will configure the program to never attempt to reestablish its server connection.

Max connection-retry wait (minutes):  Sets the maximum number of minutes that this program will wait between consecutive attempts to reestablish its connection to its server (or alternate servers).  After each consecutive failed connection attempt, the amount of wait-time before the next attempt will be doubled (which helps to reduce network traffic during lengthy outages).  This item establishes a maximum wait-time.

Enable fail-over to alternate servers:  When this checkbox item is selected and a connection to the current server cannot be established, a connection to an alternate server will be attempted.  The program maintains a list of alternate servers in its configuration, and also fetches a new list each time it connects to a server.

     Clicking on the "Alarm Regions for Recipient" item in the "Recipient" menu (or using the "Regions" button) brings up the "Alarm Regions" dialog window for the currently-selected recipient entry in the "Alert Recipents" list.   This dialog window may be used to specify regions of interest for deciding which events will trigger recipient alarms, resulting in alert email messages.  For a given alarm region, a minimum-magnitude value may be specified that applies only within that region and is used instead of the "recipient" minimum-magnitude value.  The events must still pass all the other (non-magnitude) "recipient" alarm-criteria settings (configured via the recipient-configuration "Alarm" Tab) in order to trigger an alarm.
     To make an alarm region more "sensitive" than the area outside of the region, the "recipient" minimum-magnitude may be set to a value that is much higher than the minimum-magnitude value for the region.
     Note:  Events first need to pass the "filter" settings (configured via the Settings-dialog-window "Filters" Tab) to be able to trigger alarms.
     The "Alarm Regions" dialog window displays a list of entries, one for each currently-configured region.  An entry may be selected by clicking on it, and the following right-side buttons are available:

• Add Circle:  Brings up the "Add Circle Region" dialog window, which may be used to define a region using a point and a radius.  See the "Add/Edit Circle/Polygon Region" Dialog Window section below.
• Add Poly:  Brings up the "Add Polygon Region" dialog window, which may be used to define a region using a polygon.  See the "Add/Edit Circle/Polygon Region" Dialog Window section below.
• Edit:  Brings up the "Edit Circle Region" dialog window if a circle alarm region is selected or the "Edit Polygon Region" dialog if a polygon alarm region is selected.  See the "Add/Edit Circle/Polygon Region" Dialog Window section below.
• Remove:  Removes the currently selected alarm region(s).  Several regions may be selected and removed at one time.

At the bottom of the dialog window are the following buttons:

• Close:  Closes the dialog window.
• Help:  Displays the Settings Manual documentation, with the screen positioned on the section of the manual that describes this dialog window.

     Clicking on one of the right-side "add" or "edit" buttons on the "Alarm Regions" dialog window will bring up a dialog window that may be used to add or edit an alarm region.
     The following items are available:

Name of region: An optional name for the region.

Minimum magnitude for alarm:  Sets the minimum-magnitude alarm criteria value for the region.  The magnitude of an earthquake event must be at this value or greater for the alarm to be triggered.  This is a floating-point value.  If this setting is blank or zero then the "recipient" minimum-magnitude value (configured via the recipient-configuration "Alarm" Tab) will be used.

Region data:  The geographical data values for the region, using the following formats:
     For circle regions, the data values consist of a latitude, longitude and radius (in miles) with the following format:  "(lat lon) radius".
     For polygon regions, the data values consist of 3 or more latitude/longitude points with the following format:  "(lat lon)", with each point-entry on a separate line.
     Note that the QuakeWatch GUI Display supports alarm regions using the same formats, making it possible to define an alarm region using mouse clicks on the map of the QuakeWatch GUI Display, and copy & paste the generated region-data values into the QWEmailer.

At the bottom of the window are the following buttons:

• OK:  Accepts and saves all the changes made since the dialog window was displayed.
• Cancel:  Discards all the changes made since the dialog window was displayed.
• Help:  Displays the Settings Manual documentation, with the screen positioned on the section of the manual that describes this dialog.

• OpenORB  http://openorb.sourceforge.net
• JDOM       http://www.jdom.org
• Xerces       http://xml.apache.org