For background, you should at least skim-read the paper Transient Astronomy with ACP Scheduler (PDF) and focus on the Message Classification and Filtering section.For background, you should at least skim-read the paper Transient Astronomy with ACP Scheduler (PDF) and focus on the Message Classification and Filtering section.
The role of the event filter is to look at incoming VOEvent messages and determine which ones should be acted upon by the observatory. If a VOEvent is of interest, the filter is responsible for the following tasks:
This information is passed back to the receiver by writing it to the filter program's standard out. For details see Return Data below.
Before writing your own event filter, it is strongly suggested that you familiarize yourself with the standard filter, a script called DefaultEventFilter.js. You really should understand it completely, including its usage of command line parameters and its return data under various circumstances. The filter logic is somewhat complex, but it offers a high level of flexibility. There's a limit to what can be written here; we've done the best we can in a practical amount of time.
The filter can be any type of Windows command line program, written in any language. This includes Windows Script programs which run under the Windows command line script host cscript.exe, plus Perl and Python scripts which have their own execution engines. If the filter is an executable program, it can be written in any language which provides a command line interface and which supports reading from "standard in" and writing to "standard out" and "standard error".
The validated VOEvent XML is piped into the script or program’s standard input and the result parameters (described above and detailed below) are expected to be written by the filter to its standard output. The receiver simply waits for the (external) filter program to exit before moving to the next phase of processing, constructing the observing request from RTML and optionally interrupting the scheduler for time-critical events.
If the incoming VOEvent message is digitally signed, the receiver will have already checked the signature. If the signature is valid, the signer's ID is passed on the command line to the filter program (see below). If the signature mode is set to "strict" and the signature check fails, the event is discarded before it reaches the filter. If the signature mode is set to "lenient" and the check fails, the signer ID passed to the filter is blank. This allows you (for example) to make a further requirement that all incoming messages must be signed if your filter requires a non-blank signer ID.
The VOEvent XML that is piped into the filter has already been validated by the receiver, therefore you can load it into an XML engine (e.g. MSXML) and work with either the Document Object Model (XMLDOM) or use XPath programming to traverse the document tree and extract the information you need to make your decision and construct your returned items. If you don't know XPath, you should probably get familiar with it, as this is the easiest and most efficient way to extract information from the VOEvent XML. The object is to reject events that are not of interest
If the filter program encounters an error and must exit unsuccessfully it is vital that it do both of the following:
You have control over your program's exit status value, and as you'll see below, the receiver will report the exit status value in its log and in a balloon popup if your program exits with any error status. Therefore, you can use the exit status value to help you isolate between sources of error within your program.
The Windows Script Host (cscript.exe) automatically does these two things. If your script fails to compile or if there is a fatal run-time error, cscript.exe puts all error text on its standard error and exits with non-zero status. The exit status value isn't too useful, but the error text is usually very useful.
The command line passed to the filter contains several items. They are (in order of appearance on the command line):
//ftypes:XXX,YYY... These are the three-letter filter type codes from the receiver's configured Active Event Types (see image to right). These codes are used by the filter to select the types of events that will be passed on for observation. The Windows Script Host exposes the arguments in 3, 4, and 5 as "named arguments" in a separate collection. The rest of the arguments are separated into the "unnamed arguments" collection and are indexed according to their order on the command line. The //NoLogo argument is not passed to the script. Look at the DefaultEventFilter.js script and the Windows Script Host documentation (included in ACP's online help set) for more info.
The receiver has a configuration item Active Event Types in which is a list of three-letter codes (SWF, TOC, CRT, US1, US2). These codes are used by the filter to determine which types of events will be accepted for observing. It is the filter's responsibility to recognize these codes. The receiver has no knowledge of the codes themselves, it simply passes the list of active codes to the filter via the //ftypes: command line argument. Look at the standard event filter DefaultEventFilter.js for an example of filter code usage.
Besides telling the filter which types of events to pass on along for observation, the filter code can be used to select an RTML observing request template which the receiver used to construct the observing request for the event. The template name can contain the filter type code, making maintenance easier. This is not required, however.
Depending on the decision made by the filter, it must return data to the receiver on its standard out. The return data is a single string consisting of up to four parts separated by the vertical bar (|) character. The parts, are, in order:
The target name should be something that makes type of event recognizable i the list of plans in the scheduler. For example, you might extract the "Trigger ID" from a Swift GRB alert message and form a target name of "Swift trigger #nnnn".
The target name must be unique, so use something from the event that is unique to that particular event.
If the target name is empty, it indicates that the VOEvent was rejected by the filter.
This is what gets shown in the receiver's log and in a balloon popup message (when the filter exits). If the filter accepts the event, resulting observations being queued, the receiver will pop a balloon message announcing the observations, so in that case the message should be empty. For other conditions, such as a message that was received but discarded for some reason, you can announce it with a balloon popup.
The message string can optionally specify an icon for the balloon popup. To do this, start the message with a tilde character (~) followed by a single lower case letter per the table below
| Code | Meaning |
|---|---|
| i | Information |
| w | Warning |
| e | Error |
| n | None |
For example, "~iThis is a test" would result in a balloon containing "This is a test" with an Information icon. Omitting the icon code prefix is the same as including "~n".
This is the file name of an RTML observing request template to be used by the receiver to construct the observing request for the event. If no extension is given, it is assumed to be .rtml. Typically, different types of events require different observing strategies, so the receiver provides a way for the filter to pick an appropriate observing strategy by picking the RTML template to be used. Once it knows which template to use, the receiver does some substitutions before importing the final RTML into the schedule database as the new request. This is described in detail in Customizing Observing Strategies.
For advanced applications, the filter can construct the RTML observing request on the spot, using the data in the VOEvent to determine the observing strategy (images, filters, exposures, etc.) beyond the simple template substitutions made as described at the end of Customizing Observing Strategies.
If the filter returns a target name, indicating that it has accepted the event for observations, this final part of the return string can indicate that the observations are of a time-critical nature. If this is the case, the final part of the string must be exactly timecrit (not case sensitive). Anything else will be ignored and will be logged as an unknown option from the filter.
A Swift alert we're interested in, using the SWFObsRequest.rtml template
Swift Trigger #12345||SWFObsRequest|timecrit
An event we rejected:
|~iA Catalina test message was received and discarded||
The receiver's configuration settings provide for the path to the executable and command line arguments to be passed to the program (see diagram on the right). The receiver will invoke the filter program as follows: