Overview of PageGate Filter Pack Transcript for Video:
Welcome to the overview of PageGate’s Filter Pack. In this tutorial, we'll be going over the basics of what PageGate's filtering scripts can do and how they’re implemented.
To start, the filter pack is a series of scripts that allow you to conditionally modify the content of a message, including the message text, who the message is from, and who the message will be sent to. The filter pack can be used with any and all messages that are accepted into PageGate through any of its interfaces. For example you could be pulling information from a web API using an HTTPPOST carrier. You could be checking the memory of a cellular modem for replies to your text messages. You could be using any of PageGate's stock Interfaces, like the GetAscii interface to receive alerts from network monitoring and CAD systems, and the GetMail interface to receive email to translate in to SMS or pages. Regardless of how you do it, once you get the data in to PageGate, that's when the filter pack comes in to play.
The scripts in the filter pack allow you to conditionally modify nearly anything but let's break that concept down a little. When I say 'conditionally modify', what I really mean is that you can tell the script to look for certain key phrases or characters, then do something special when it finds them. As for what 'something special' does? That's up to you when you configure the script. You could have it search and replace any instance of a specific word or phrase. You could change whom the message is meant to be delivered based on the body of the message. You could change the sender's name, execute a batch file or script, and literally thousands of other possible options.
For example, let's say that you're sending SMS using cellular hardware. Let's also say that you have a basic reply system configured in PageGate and that when your people reply to your text messages, all of the replies go to your supervisor's email distribution group.
We could configure the script to scan all reply messages for the word 'lunch' and change the message to go to the 'lunch_preparation' group instead of the normal supervisor's email distribution group. We could configure a script to scan all reply messages for messages sent FROM a specific phone number and redirect their specific messages to a different distribution group or recipient.
As a more complex example, let's say we have emergency management agency using a CAD system and that agency needs all fire, rescue and accident calls dispatched but does not want non-emergency calls dispatched.
We could configure the script to look through the CAD data for certain flags like FIRE,DISPATCHED or RESCUE,DISPATCHED or ACCID,DISPATCHED and allow those through the system while preventing any messages that had VANDALISM,DISPATCHED or TRAFFIC,DISPATCHED or similar from going through.
The greatest strength of the filter pack is the script's flexibility; you can key off of nearly any condition to execute nearly any effect, including executing a batch file to run an external process.
In this tutorial, we’ll be going over the basics of how a script is implemented, but we’ll be going into more detail of how to code the script in the ‘How to build a filter script’ tutorial.
The filter pack's scripts are used by PageGate's GetASCII Interface. If incoming message are not already being processed by the GetASCII interface, but instead are accepted into PageGate via one of its other interfaces, then a Carrier that uses the File protocol can be setup to route those messages back through the GetASCII Interface. This enables all messages that are handled by PageGate to be processed by the filter pack.
The filter has three files associated with it:
These three files must reside within a directory that GetAscii is monitoring. When the GetAscii interface goes through its normal polling routines and finds data that needs to be processed, it first checks for the existence of preproc.bat. If the batch file is found, it is executed, thereby pre-processing the data with the filter.
Let’s take a look at each file. The preproc.bat and pstproc.bat files are batch files configured to run pgfilter.exe and pass certain file name information to it.
The GetASCII interface will check for the existence of preproc.bat before processing data in the folder. If preproc.bat exists, GetASCII will run it (and thereby execute the filter script) before reading any data from the folder. This allows you to run your data through a filter script before processing it in to outbound messages.
pgfilter.exe is the executable for the filter itself.
pgfilter.xml is the configuration file that tells the script how to function and does so through a series of logical statements by using Boolean operators. It’s also important to note that the filter script supports using RegEx aka Regular Expressions, which can allow for some truly detailed and complex filtering.
Effectively, this filter allows you to modify any input fed in to PageGate based on nearly any selection criteria of your choosing so long as the raw data can be read as plaintext; whether that's another program's log files, XML or HTML content, delimited text or anything that can be read as plaintext.
To implement a PageGate filter script, you'll need to copy pgfilter.exe and pgfilter.xml to a directory of your choosing.
For example, c:\PageGateData\ASCII\Filter\
Since you want to engage the filter script before GetASCII can process message data, you will also want to copy preproc.bat in to the same folder.
Next, we’ll need to configure GetASCII to reference the filter script’s directory. To do that, open the PageGate Admin and go to Interfaces – GetASCII – Settings. If you already have a polling directory, you can skip this step.
If you do not have a polling directory, we recommend creating c:\PageGateData\ASCII\ and using that.
Now go to Interfaces – GetASCII – Settings – Advanced Polling – Files.
If the filtered information should only go to a specific recipient or group, select it from the dropdown. Otherwise, leave recipient at * to indicate that messages processed by this rule could go to any recipient or group in the program.
Leave From blank.
Set File(s) to match the extension of the files written by the filter. Since the filter can be customized to output any extension on your files, this is largely arbitrary. For example, if your files will have an extension of .txt, you would use *.txt. If your files will have a .t2a extension, you would use *.t2a
Set the Path to the filter script’s folder. By default, c:\PageGateData\ASCII\Filter\
Click Apply, then click Apply again.
At this point, you’ll need to edit the contents of pgfilter.xml to configure the filter script. For more information on that, please see our ‘how to build a filter script’ video tutorial.
When using preproc.bat and the GetASCII module, this is the chain of events that trigger the script:
1) The GetASCII Interface finds a new file to process.
2) If preproc.bat exists in the directory, GetASCII will run it, passing the name of the file it has just found on the command line.
3) preproc.bat should be set to run pgfilter.exe, again passing it the name of the text file from GetASCII.
4) pgfilter.exe will look to the command line parameters passed to it to get the name of the input text file and the (optional) name of the XML file to use.
5) pgfilter will read the XML settings file from the command line or use pgfilter.xml if one isn't passed. It is highly recommended to use the XML file rather than the command line.
6) pgfilter will perform all functions coded in the pgfilter.xml file, then terminate.
7) The data output by the pgfilter will be processed for delivery by the GetASCII module.
After implementing a filter script, it is highly recommend that you go through a debugging process to verify what you've configured. Please see the ‘Debugging the Script’ section of our documentation for more information on how to do that.
Before we conclude, it’s worth mentioning that everything we’ve described uses the filter to pre-process your data by using preproc.bat
This concludes the overview of Pagegate’s filter script.
There is a second method that can be used to pass messages through the filter pack's scripts. You can set up a Carrier that uses the File protocol to save message files to a folder. When Connectors deliver a message using the File protocol, they check for the existence of the pstproc.bat file. It is used in much the same way as the preproc.bat file with the GetASCII interface. This method can be used if PageGate needs to pass message data to other programs, or if PageGate needs to run an external executable and pass it message data. For more information, have a look at our 'Post Processing Filter'' tutorial.