How to Build a Filter Script Transcript for Video:
Welcome to the video tutorial on how to build a filter script. In this tutorial, we’ll be going over the basics of how to configure the script to filter content based on your desires.
The first step is to open pgfilter.xml
This XML file controls what the filter script does and what steps it takes to accomplish the desired results. What we’re doing is providing the steps it needs to follow.
To start, let’s have a look at the filter script’s basic XML template.
The template provides specific technical information you’ll need to understand all of the available options you have and gives you an overview of how filter statements are constructed.
There are three major sections that need to exist:
<InputFile>
The <InputFile> section governs what file or files this rule should apply to. This section is optional and at most there can only be one InputFile section in the script. If this section is omitted, then the file name passed by the preproc.bat file will be used.
<OutputFile>
The <OutputFile> section governs what file naming convention the script should use when it outputs the final content. Basically, we’re telling the script how it’s going names the files it outputs to the folder. This section is also optional and at most there can only be one OutputFile section. If omitted, the OutputFile will be the same as the InputFile.
<Filter>
The <Filter> section governs what happens to the data in the files read from the InputFile section before it uses the OutputFile section to write the new data. There can be many Filter sections in each script.
Let’s go over the InputFile section in detail.
<InputFile>
<Name>
Value Here
</Name>
<Delete>
Value Here
</Delete>
</InputFile>
The Inputfile section determines which file or files this rule should apply to and consists of two flags that need to be configured, Name and Delete.
<Name> can be set to the value: Parameter
It is case sensitive, so be sure to use a capital P. This is the default value that is used if the InputFile section is left out of the script.
Name can also be set to a static file name with path.
For example, you could use: c:\PageGateData\ASCII\Filter\output.txt or c:\CADOutput\caddata.wba
If you use a static file name, the filter will read information from the specific file and use it for the input.
Otherwise, you’ll want to use the word: Parameter. Preproc.bat is, by default, configured to pass the name of the file read as the Parameter value.
So, GetASCII finds new data to read and checks for the existence of preproc.bat. If it exists, GetASCII will run it and pass the name of the file 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.
When using the FILE protocol output method, the Connectors will check for the existence of pstproc.bat after writing the file(s). If pstproc.bat exists, the Connectors will run it (and thereby execute the filter script) after the file is written. This allows you to pass the data through a filter script after a file is written, post-processing it.
<Delete> can either be set to True or False and determines whether the script will delete the input file when its processes finish. If this section is omitted, then the default value is False.
Next we have the <OutputFile> section. This section determines what you want to name the files output by the filter's modifications and has a single value that needs to be set.
<OutputFile>
<Name>
Value Here
</Name>
</OutputFile>
<Name> can be set to the value: InputFile
Or you can provide a static output file name.
The value InputFile (it is case sensitive) tells the filter that the file output should match the original input file's name. So, for example, if the file read was named example.txt, then the file output would also be called example.txt. This is the default value if this section is omitted.
Alternatively, you can specify a naming convention for the output files. This value supports the following variables:
%InputFileName% provides the full input file name, including extension.
%InputFileNameBase% provides just the name of the input file.
%InputFileNameExtension% provides just the extension of the input file.
%InputFilePathAndName% provides the full path and name, including extension, of the input file.
%InputFilePath% provides the path to the input file.
For example, you could specify this as the value: c:\PageGateData\Ascii\%InputFileNameBase%.asc
That would tell the filter that it should use the original name of the file read but the output file should have the extension .asc instead of the extension on the original file.
Using c:\PageGateData\ASCII\%InputFileName% would do the same thing as using the InputFile variable. However, you could put an additional extension on the file, like this:
c:\PageGateData\ASCII\%InputFileName%.filtered
Now that we’ve told the script what to read and how to name the output once it’s finished, we’ll need to tell it what to do.
A Filter statement instructs the filter on how to perform a task. You can have multiple filter statements in a single script.
A Filter statement is composed of two sections:
<Search>
<Replace>
The <Search> section determines what data this filter should look for and <Replace> tells it what it should do with what it finds.
The <Search> section contains three values that will need to be specified:
<Section>
<Type>
<Text>
<Section> determines where in the data this filter statement needs to look. Before we get in to the specific values that can be set, let’s go over why certain names are the way they are. The PageGate filter works specifically in conjunction with PageGate’s GetASCII module and, as a result, uses some of the GetASCII module’s logic to perform its functions.
The GetASCII module has a standard file format that is as follows:
Recipient
Sender
Message
So, from GetASCII’s basic perspective, the first line of a file is the ‘recipient’ section, the second line is the ‘sender’ section and the third and following lines are the ‘message’ section. Effectively, ‘Recipient’ just the first line of a file, ‘Sender’ is the second line of a file and ‘Message’ is the third and following lines of a file.
To get back to the values that can be set for Section, this can be set to:
· All
This value tells the filter to scan the entire input data.
· Recipient
This value tells the filter to scan just the first line of the input data.
· Sender
This value tells the filter to scan just the second line of the input data.
· Message
This value tells the filter to scan everything at and beyond the third line of the input data.
· Temp
Temp is a temporary string variable. In your filter script you can assign values to the Temp variable and then use it later for additional searches or replacements.
For example, you can have certain information stored in the Temp value, and then search on and output that Temp value in successive Filter statements.
· Flag
Flag is another temporary variable that you can have the script assign values to. However, it is a boolean variable and can hold only a true or false value. It can be used with boolean logic like "And" or "Or" statements to create advanced logic chains.
<Type> determines what sort of information the filter should expect to see in the Text section. This can be set to RegEx or Literal.
If Type is set to RegEx, the value in the Text section will need to be a RegEx expression.
If Type is set to Literal, the filter will expect a literal text value in the Text section and won’t expect any RegEx expressions.
For example, you could enter the text ‘Fire Department’ in the Text section if you want the filter to key off of that literal sequence of alphanumeric characters. It’s also important to note that the Text section supports the following boolean parameters:
* - Multiple Character Wildcard
For example, fire* would find fire, firewood, fireplace, fireman and similar.
? - Single Character Wildcard
For example, fire? would find fires, fired but would not find fire.
~ as first character means 'the start of section/file'
~ as last character means 'the end of section/file'
For example, ~123~ would only find 123 and not 01234 or 1237, etc.
~123 would find 12340 but would not find 01234.
123~ would find 0123 but would not find 01234.
This section also supports the following variables:
%Recipient% - the current value for Recipient
%Sender% - the current value for Sender
%Message% - the current value for Message
%All% - the current value for All of the text
%Temp% - the current value for anything written to the Temp variable
\ASCIIVALUE – This character is used when you want to include a character as represented by its Ascii Decimal value. For example, since the filter directly references the character ~ in its function, if you want to use the ~ character in your text, you'll need to represent it with its ASCII value, \126. All ASCII values must be three digits long, so for a value of 13 you would use \013
For examples of how to construct Search statements, have a look at the ‘Filter Statement Examples’ as well as examples 1 through 6 in the ‘Complete Script Examples’ in PageGate’s documentation:
https://www.notepage.net/manuals/pg/v8/server/html/index.html
The Replace section determines what you want to do with the data found in the Search and contains five values that will need to be specified.
<Section>
<Type>
<Scope>
<All>
<Text>
<Section> determines where in the data this filter statement needs to look and can be set to the following values:
· All
This value tells the filter to scan the entire input data.
· Recipient
This value tells the filter to scan just the first line of the input data.
· Sender
This value tells the filter to scan just the second line of the input data.
· Message
This value tells the filter to scan everything at and beyond the third line of the input data.
<Type> determines what sort of information the filter should expect to see in the Text section and can be set to the following values:
Literal, RegEx, And, Or
If <Type> is set to RegEx, the value in the Text section will need to be a RegEx expression.
If the value Flag is used in <Section> then one of the Boolean operators (And, Or) can be used in the <Type> section. They will use this operator and the new <Text> section value to modify the Flag variable. For example, in one <Filter> section you could set Flag to True if certain text is found. In the next <Filter> section you could search for different text and update the Flag variable using the value 'And' or 'Or' in the <Type> section, depending if you want the new Flag variable's value to signify if BOTH the first text searched for AND the second text searched for were found, or if EITHER the first text searched for OR the second text searched for was found. See Example 3 in the ‘Complete Script Examples’ section of PageGate’s documentation:
https://www.notepage.net/manuals/pg/v8/server/html/index.html
If <Type> is set to Literal, the filter will expect a literal text value in the <Text> section and won’t expect any RegEx expressions.
The <Scope> section tells the filter how much data to replace if a match is found. It can be set to a value of either Match or Section.
If <Scope> is set to Match, only the text found in the <Search> section will be replaced
If <Scope> is set to Section, then all the text in the data specified by <Section> will be replaced
For example, you could search for the text ‘Fire Department’ and then set <Section> to Recipient and <Scope> to Section, to tell the script to replace the recipient section with the new text, effectively telling the script: So, if you find this text in the body, change the recipient to the value specified.
The <All> section tells the script whether it should replace all matches found or just the first match found, and can be set to True or False.
For example, if you’re searching for the word ‘pills’ and that word appears multiple times in the data, if <All> is set to True, the replacement will happen for all instances of the word ‘pills’. If <All> is set to False, the replacement will happen only for the first instance of the word ‘pills’.
The <Text> section, of course, controls the text used to make the replacement, and the type of information you can use in this section is controlled by the <Type> section.
As an example for the <Text> section, you could enter the text ‘Fire Department’ in the <Text> section if you wanted the filter to replace the text found in the Search with that literal sequence of alphanumeric characters.
This section supports the following variables:
%Recipient% - the current value for Recipient
%Sender% - the current value for Sender
%Message% - the current value for Message
%All% - the current value for All of the text
%Temp% - the current value for anything written to the Temp variable
\ASCIIVALUE – This character is used when you want to represent a character as represented by its Ascii Decimal value. For example, since the filter directly references the character ~ in its function, if you want to use the ~ character in your text, you'll need to represent it with its ASCII value, \126. All ASCII values must be three digits long, so for a value of 13 you would use \013
For examples of how to construct Replace statements, have a look at the ‘Filter Statement Examples’ as well as examples 1 through 6 in the ‘Complete Script Examples’ in PageGate’s documentation:
https://www.notepage.net/manuals/pg/v8/server/html/index.html
Our last two sections are Continue and Abort.
The Continue section tells the script whether or not you want the script to continue to the next action if it finds a match and can be set to a value of True or False.
Abort can be set to True or False and tells the script to abort its processes if no match is found.
So, to go through a brief overview of everything we’ve just covered, to build a filter script, you’ll need to:
1) Declare the file or files the filter needs to look for (optional).
2) Declare the file naming convention for the files the filter will output (optional).
3) Build a filter statement that tells the filter what to search for within the files and then what to do with the data it just found, before it outputs the modified content for GetASCII to process.
This concludes the video tutorial on how to build a filter script.
|
