#
# $Id: 79619c6cd9f5839b40b00522931cb9e547f64d56 $
#

	Quick Start -
	Principle of operation -
	Subscriber list configuration -
	Flat text files -
	Examples -

Quick Start -
-----------

	1) Enable the msgfilter in the "features.conf" file.
	2) Set the variables

		msgfilter(smtp,originator)
		msgfilter(http,server)

 	   and if needed

		msgfilter(smtp,servers)

	   to appropriate values in "site/msgfilter.conf".
	3) Write the subscribers list(s) (as indicated below).


Principle of operation -
----------------------

The msgfilter is driven by an "rc" file that specifies who
gets what and how. The "how" is specified by the transport mechanism
and perhaps some flags. Currently, the only transport is smtp and the
flags are "F", "S" or "U" for sending the full file, a summary or a
URL, respectively. In this case (smtp), the "who" is an email address.

What each subscriber gets is specified by a combination of product codes
and zones, or product codes and sites, using a regular expression syntax.
For each incoming product, the filter scans the subscriber list and it
builds up a list of recipients according to the regexp matching rules.

Once the filter has collected the recipients list(s), one for each of the
F, S and U flags, it composes the messages and hands off
the delivery to the smtp server (configurable in "msgfilter.conf").
The msgfilter speaks smtp with the server, so that the server
can be either the localhost (the default) or another computer;
the filter doesn't care. In this way, the delivery is off to
another process, in the same or a different computer, and the filter
can go on minding its own business.

Subscriber list configuration -
-----------------------------

The list of "subscribers" is specified in the following form, one
such term for each "subscriber", in the file
"/usr/local/etc/npemwin/msgfilter.rc" (but see below):

lappend subscribers {
	<transport>://<destination>
	<prodzone_spec> or {:<condition>}
	<flags>
}

Here <prodzone_spec> is a comma-separated list of terms where each term
has the form
	
	<prod_code_regex>_<zone_code_regex>
or
	<awips_code_regex>

(if the awips code is blank then the wmoid is used).

For example, given

lappend subscribers {
	smtp://nieves@noaaport.net
	(svs|tor)_txz14[5-9],svr_vaz014
	<flags>
}

then I would receive all svs and tor for TX zones 145 to 149, and also
all SVR for VA zone 014. The comma separated list of product-zone
combinations can be extended indefinitely.

Instead of the prod_code and zone_code combiation, another form is

lappend subscribers {
	smtp://nieves@noaaport.net
	(svs|tor)jsj
	<flags>
}

to specify a site instead of zones.

Another form is to specify a condition instead of the regular
expressions for product code and zones. For example

lappend subscribers {
    smtp://7873432020@tmomail.net
    {:0 [regexp {URGENT} $rc(body)] || [regexp {tjsj} $rc(station)]}
    U
}

When using a "condition" instead of the prodzone_list regular expressions,
the condition must start with the ':0' character to be recognized as such,
and it must be protected by the curly brackets as shown in the example above.

Several sites can be combined in this way

lappend subscribers {
	smtp://nieves@noaaport.net
	(svs|tor)(jsj|lix)
	<flags>
}

and so on. The two forms can be combined in one spec

lappend subscribers {
	smtp://nieves@noaaport.net
	(svs|tor)_txz14[5-9],svr_vaz014,afd(jsj|lix)
	<flags>
}

The <flags> depend on the particular transport. For smtp
it can be "F" or "S" to send the full file or the summary. Each
transport defines its own set flags (for some transports it could be empty).

==
Added Tue Sep 13 11:39:32 AST 2011:

To send sms messages (to a cel phone), e.g.,

lappend subscribers {
	smtp://7873467474@tmomail.net
	(svs|tor)_txz14[5-9],svr_vaz014,afd(jsj|lix)
	<flags>
}

Most useful <flags> is probably the U flag to send a URL to the full file.
==

As already mentioned, the filter reads reads the file

	/usr/local/etc/npemwin/msgfilter.rc

to get the list of subscribers. In practice the list should be written
instead in the "site" file (the filter looks for it as well)

	/usr/local/etc/npemwin/site/msgfilter.rc

Flat text files -
---------------

The list can be kept in a separate flat file, in the format
(space as separator)

<transport>://<destination> <prodzone_spec> <flags>

E.g.,

smtp://nieves@noaaport.net (svs|tor)-txz14[5-9],svr-vaz014 F;
smtp://<phonenumber>@tms.suncom.com (svs|tor)-txz14[5-9] S;

If such a flat list is kept in the file

	/usr/local/etc/npemwin/site/msgfilter-subscribers.txt

then it can be imported by "site/msgfilter.rc" file by writing in that file

msgfilter_add_flat_file "/usr/local/etc/npemwin/site/msgfilter-subscribers.txt"

Examples -
-------

The files "msgfilter.rc-ex" and "msgfilter-subscribers.txt-ex" have
examples illustrating all this.

-
Jose - Tue Jul  8 18:23:42 AST 2008
     - Fri Jun  3 11:58:25 AST 2011
     - Thu Sep 15 16:34:48 AST 2011 (revised/tested with cel phones.
                                     Added U flag)
