AlphaSense Ruleset File Details

This document explains the construction and content of each field used in creating ruleset entries for the AlphaSense ruleset file. The information below applies to firmware 4.60 and all later versions - until this document is revised to indicate a higher version number. You may wish to print this page, or keep it on the screen while creating or editing your ruleset file.

General Notes

The AlphaSense ruleset file is a collection of rulesets; one to a line. AlphaSense uses rulesets to evaluate the data sent to it from various data sources, such as sensors, alarm panels, contact closures, network SNMP traps, RS232 serial data, and more. Each ruleset specifies "what to look for" in each incoming data block, and "what to do" if that desired data is found. A ruleset is entered as a single line, and is comprised of fields separated by the "|" character. Whenever AlphaSense receives data from any data source, the data is "scanned" by each ruleset that the user has defined and set to be active. A given data block may meet 1 or more rules (in which case the designated action specified by each met ruleset is performed), or it may not meet any rules at all, in which case no action is taken. Incoming data is logged and timestamped in all cases.

Hints and Things to Remember

The ruleset file can be edited right from the AFN browser interface, or using a text editor. You can prepare ruleset lines in any text editor that does not add formatting - pure text is needed. Each ruleset line begins at the left margin, and ends by pressing the Enter key.

If all this seems too complicated, Compuquest, Inc. can do it for you!! Cost-effective Support Modules are available for purchase at our website for whatever assistance you may require.

Fields which are unused should be kept at their default setting, with the number "0" entered. Empty (blank) fields are NOT allowed.

Only put into the ruleset the lines you need - leave the rest as comment lines.

Incorrect formats or absence of required fields may cause unpredictable results and/or failure of AFN to operate.

Details of Ruleset Fields

Below are details on each field that comprises a ruleset line. Remember, any ruleset file line beginning with the "#" character is a comment line, and is ignored. This makes for a very easy way to have several rules constructed and "ready to go" - leaving the ones that you dont want to use as comment lines. Simply remove the comment character, and that ruleset will be evaluated by AlphaSense; leave the comment character present, and the line will be ignored.

First, here is a "skeleton" ruleset line, showing the field names. Below it is a (commented) actual ruleset line, but all fields are set to their default value, which is the number "0". Please refer to these lines to help remember field names, and the positions of certain fields within the ruleset line. These two lines are also found in the original ruleset file you have received with AlphaSense - simply construct and enter your desired ruleset line(s) into that file using a simple text editor. Simply replace the "0" default field entries with your entries for the fields you want to use, and leave all unused fields at "0". At the end of each ruleset line, you should press the ENTER key in your text editor to complete the ruleset line.

activeflag - length: 1 numeric character - this field tells AlphaSense if that ruleset is active, inactive, and also designates some special-use values. The possible entries are:

The Well-Check feature is very useful for installations where the monitored data source(s) produce infrequent messaging data. Since no messages are being generated, how can one be assured that AlphaSense is working? By using Well-Check. Each day, at the time designated with the "wctime" parameter that is set in the parameter configuration file, AlphaSense will process the ruleset having activeflag=4, delivering the message in accordance with the remaining ruleset fields.

**...this feature is currently disabled...** The cable disconnect feature provides alerting if the cable connecting the AlphaSense host serial port to outside equipment is cut, disconnected, or broken. To enable this feature, simply set the activeflag of any ruleset to 5, and the message will be delivered in accordance with the remaining ruleset fields.

the heartbeat feature works with the "hbtime" value that is set in the parameter configuration file. If hbtime is not disabled, at the end of each hbtime interval, AlphaSense checks to see if the desired data as defined by the actrule field "has been received" at least once during the designated time interval, and if not, the ruleset is processed for messaging in accordance with the remaining ruleset fields.

AFN-100 products can deliver messages using 3 types of SNMP traps - v1 Trap, v2c Notification, and v2c Inform. The Inform type expects a response to validate that the message was received. If no response is received within the few-seconds timeout period, AFN will look for a ruleset having its activeflag set to 7. If one exists, the ruleset is processed for messaging in accordance with the remaining ruleset fields. Note: it is unadvisable to designate any form of trap delivery for this ruleset - the timeout failure indicates trap reception is not functional - use XMPP instant message, email, or dialout delivery methods. Message content is pre-defined, so the msgbody and actrule fields may be left at their default values. The Subject and Prefix fields may be defined as usual.

numtodial - length: up to 40 characters - this field tells AlphaSense what number to dial with modem dialout message delivery for that ruleset. The entry may be prefaced with the letter "F" to denote "Failover" delivery, which means if network connectivity is lost, deliver the message for that ruleset using dialout, but if connectivity is ok, use only the network for message delivery. Note: the config file parameter emcheck must be enabled for failover to operate.

When using the AFN_DCP direct-connect feature package, all rulesets which are to deliver a message using the directly-connected paging or other wireless messaging transmitter shall enter "000000" in the numtodial field for that ruleset. The possible entries for the numtodial field are:

dialmode - length: 1 numeric character - this field tells AlphaSense what "mode" of dialout message delivery to use for that ruleset. The possible entries are:

dialpin - length: up to 18 numeric characters - this field tells AlphaSense the PIN number to use (if needed) with dialout or AFN_DCP delivery for that ruleset. The PIN is needed for delivery to wireless devices like SMS messages, pagers, cellphones, PDA, Blackberry, etc.

imaddr - length: up to 30 characters - this field is a multi-use field to designate message delivery recipients for various forms of instant messaging. The first letter (always upper case) designates the instant messaging method, and the remainder contains method-specific formatted information for the actual destination which will receive the message. Currently, the following designations and formats are supported for this field:

emaddr - length: up to 50 characters - this field tells AlphaSense what email address to use with network message delivery for that ruleset. The entry also may contain the special designator "^S" that tells AlphaSense to deliver the message out the serial port (or virtual port) where the original data came from. Serial or virtual port delivery makes possible powerful command - and - control response, such as for factory automation, lab equipment, and other interactive equipment interfaced to AlphaSense. The possible entries are:

emsubj - length: up to 30 characters - this field tells AlphaSense the content of the "subject" line in network email delivered for that ruleset.

prefix - length: up to 30 characters - this field designates content that will appear "ahead of" the message body of all messages sent by AlphaSense for that ruleset. Remember, this text is "immediately ahead of" the message body, so you may wish to add "colon space" at the end of this entry for nice formatting on wireless devices.

msgbody - length: up to 1024 characters - this field designates content that will be the message body of all messages sent by AlphaSense for this ruleset. Entering user-defined content is useful when the data sources are either sensors, contact closures, or some coded data like "EJR683" which really means "Water Safety Valve #7 Is Leaking". Thus, entering the user-defined content "translates" the sensor or coded data into a meaningful message. Alternatively, this field can contain one or both of two special designators. The first is "^F" which tells AlphaSense to "Forward" the exact data it received from any data source as the message content. This "Forwarding" choice is very powerful, and is used quite often. It allows AlphaSense to bring an exact copy of "just the data you want" to chosen recipients, at any time, and wherever they are. The second special designator is "^T" which tells AlphaSense to append a timestamp at the end message content when email message delivery is used. If "^T is used alone, text immediately following it is the msgbody text that will be included in message delivery. Both used together "^F^T" tell AlphaSense to "Forward" the data as above, and add the timestamp at the end when sending an email message for that rule.

actrule - length: up to 60 characters - this field tells AlphaSense "what to look for" in each block of incoming data (from any source) for that ruleset. This may be entered as a simple case-sensitive text string to match on, or as a "Regular Expression". AlphaSense supports both simple match string entry, or the very powerful Regular Expression (called Regex) syntax, which allows for the construction of precise and sophisticated designations. When the actrule content "matches" with any incoming data block, that is what "triggers" AlphaSense into taking the action(s) that are specified by the other parts of that particular ruleset.

Examples of Ruleset Lines

1) The rule below matches on data from the equipment connected to AFN that contains the string "erator On", and delivers the message "Hospital: Emergency Generator On" to the pager or cellphone having PIN number 6543. It dials the wireless provider at the carrier's dialup access number at 888-123-4567. The rule is active.

2) The rule below matches on data from the equipment connected to AFN that contains the string "water level", and delivers network email to "user@email.com". The msgbody field is set to "^F" which stands for Forwarding, and means "send an exact copy of the entire matching message as the message body". The message will be prefaced with "SiteID: " in front of the message body. (The email "from address" is defined in the parameter config file). The rule is inactive.

3) The rule below does both dialout and email, uses data forwarding for the message content, and matches on "chemical leak". The rule is active. Note: a neat and quick way to stop dialout and keep email for this rule is simply to set the dialmode field to zero....

4) The rule below delivers the message using the SNMP trap delivery method. The trap is sent to the SNMP manager on the machine having IP address 172.16.31.109, and which uses "commstr" as the community string permitting trap message receipt. No dialout or email delivery is defined. The rule matches on "card access alarm", and uses data forwarding for the message content of the trap varbind. The rule is active.