Using Filter.aspx

TSL Ping Tree > Page Usage

Using Filter.aspx

A Filter is a set of rules based on field values, the current IP Address, the current date/time, etc.  Filters can be global or they can be made "attachable" and then attached to a Promotion, Ping Tree, or Lead Point.  If a Filter fails then an error or a decline will occur depending on its configuration settings.

Note:  Filters run after Field Validations when a lead is submitted to the submit.ashx form submission handler.  If any Field Validations produce an error then Filters will not run.


Schedules

A Filter is where a Schedule may be used. Select the data item type Schedule, pick a Schedule that you have defined, and then pick whether to block transactions that occur on this schedule or require transactions to occur on this schedule.

IP Filter Sets

A Filter is also where an IP Filter Set may be used. Select System Attribute "IP Address" -- the IP Address of the current HTTP Request from the caller -- or System Parameter "Browser IP Address" -- the unverified IP Address of the visitor as posted by the caller via System Parameter "ip", then pick an IP Filter Set that you have defined, and then pick whether to block transactions that match this IP Filter Set or require transactions to match this IP Filter Set. Note that when the "ip" System Parameter is not set then the value of the physical IP Address of the caller will be used. Whether you use one or both of these IP Address data items in your Filter definition depends on whether you are receiving server-to-server posts or you are receiving post directly from a front site.

Settings for Filters

The table below describes the common settings available for all Filters.

Configuration Item Description
Name A unique filter name up to 255 characters.
Filter Type Global - Runs for all Submits after basic data type and field level validations have passed.
Attachable - Runs for the configuration items to which it is attached.
Pass If When you have multiple filter entries, this determines whether they all have to pass for the filter to pass (AND) or if any rule passing causes the filter to pass (OR). If you only have one entry, then that single rule must pass for the filter to pass regardless of the "Pass If" setting.
Filter Causes When a filter is violated on a submit the system can either record internal messages, decline, and not inform the caller about the details (the behavior when Decline is selected) or the system can produce an error and inform the caller about the details (the behavior when Error is selected).  Note that this option does not apply to Lead Point level filters; Lead Point level filters always do the Decline behavior.
Notes Anything goes here.
Enabled You can disable a Filter without removing it from all of the places where you used it.  Only enabled Filters execute.
Update Comment You can provide a comment here to be included in the audit trail entry when updating the Filter.
Entries Here is where you define one or more rules that make up the definition of this validation. See below for a detailed explanation of these entries.

Filter Entries

You can define one or more rules that make up a Filter. The settings that define one rule are:

Configuration Item Description
Note A description of up to 255 characters that describes the individual entry.
Filter Mode A rule may be of type Require or Block.  Require means that the current lead must match the rule while Block means that the current lead must NOT match the rule.
Filter Style A rule can be a simple wizard type rule with an upper and lower bound and/or a modifier chain validation, or it can be an extremely powerful lefthand/righthand expression.

Wizard Style Filters

You can use a wizard style entry when all you want to do is check the minimum and maxium values (or lengths for strings) and/or run a built-in validation (such as CheckABA or CheckMX).

The user interface here is similar to what we use for our Expression Builder.  You pick an item type and a specific item to examine and then you define a rule against it. The item you select from the menu bar will either be a schedule or a item of data type CheckBox, DateTime, Decimal, Integer, IP Address, String, or String Enumeration. For every type except Schedule, you can provide a modifier chain to validate the entry. The resulting value of that modifier chain must be of type CheckBox. Based on the data type for items other than Schedules, these are the other filters you can specify in a wizard style entry:

Data Type Description
CheckBox You can either specify that the checkbox should be checked or unchecked.
DateTime You can either specify a relative date range or an absolute date range.

A relative date range allows you to specify a minimum and maximum date (in any order) that is based off of the current time (Now) or off of a DateTime Field or Global Constant.

An absolute date range allows you specify a specific start and end date that a value must fall between. One of the values for an absolute date range can be left blank to indicate Now.

Note that the system uses Now in the US Eastern Standard Time zone which makes comparisons in short time frames problematic for other time zones.  Tip: For longer times periods add an extra day.
Decimal You can specify a minimum and maximum value. You can leave either one of them blank to indicate no constraint. For example you can set the minimum to 0.00 and leave the maximum value blank to indicate that the value must be greater or equal to 0.

If you specify a modifier, you can leave them both blank.
Integer You can specify a minimum and maximum value. You can leave either one of them blank to indicate no constraint. For example you can set the minimum to 0 and leave the maximum value blank to indicate that the value must be greater or equal to 0.

If you specify a modifier, you can leave them both blank.
IP Address You can select an IP Filter Set. For information on defining an IP Filter Set see the help article on IP Filter Sets
String You can specify a minimum and maximum length. You can leave either one of them blank to indicate no constraint. For example you can set the minimum to 6 and leave the maximum value blank to indicate that the value must be have contain at least 6 characters.

If you specify a modifier, you can leave them both blank.
String Enumeration You can specify which enumeration values match the filter entry.

In addition to minimum/maximum rules as appropriate for the given data type there are many built in validation functions that can be specified in the modifier chain and these may require you to supply additional parameters to complete the rule.  The most powerful such modifier is CheckRegEx.  These are not very easy to get right but they can handle many situations.  A simple example of a Regular Expression is CheckRegEx("^(na|n/a|no answer|not applicable)$") which matches the whole strings "na", "n/a", "no answer" and "not applicable".  For more help on Regular Expressions see the online help article for Regular Expressions and for more help on modifier chains, see the online help article for Modifiers.


Lefthand/Righthand Expression Style Filters

You can use a lefthand/righthand (LH/RH) expression style entry when you want to do more sophisticated filtering such as seeing if an item is contained in a String List or using more than one field to perform the validation. A LH/RH expression can be thought of as a comparison in the format:

     LEFT_HAND_EXPRESSON COMPARISON_OPERATOR RIGHT_HAND_EXPRESSION

Some examples could be:
  • ${f.'Work Phone' digitsonly} Does Not Equal ${f.'Home Phone' digitsonly}
  • ${f.'Zip Code'} Is In String List Allowed Zip Codes
  • ${sp.'Affiliate ID'}|${sp.'Affiliate/Promotion Authentication Key'} Is In String List Affiliate List
The settings for a LH/RH expression entry are:
Configuration Item Description
Left Side This is the left hand value of the expression.
Comparison This is the comparison operator of the expression.
Right Side This is the right hand value of the expression or in the case of the operators "Is In String List" and "Is Not In String List" this is the name of the String List
Error Message This is error message that will be generated if the comparison of the expression is True. This field is required.
Blame Field This optional setting allows you to specify which field will be "blamed" if the filter entry doesn't pass. If you configure this setting, then a field level error can be generated when the filter entry fails. If you do not configure this, then only a general error can be generated. Note that the setting for Filter Causes Decline or Error described above ultimately determines if this error will be propagated back in the response.


Note that for a rule with a CheckBox, DateTime, Decimal, or Integer data item on one side -- a single ${} token with optional modifiers -- and a multi-token or literal String on the other, the String side will be cast into the type of the other side using "en-US" (English - US) formatting rules.  For the String side we recommend the format "yyyy-MM-dd" for dates, "yyyy-MM-ddTHH:mm:ssZ" for date/times, and, for numbers, only digits with an optional negative sign prefix and/or an optional period for a radix or decimal point as needed.

Supported CheckBox values (case insensitive) are:

  • CHECKED: T, True, Y, Yes, on, 1
  • NOT CHECKED: F, False, N, No, off, 0


A CheckBox item can only be compared to another CheckBox using the Equals or Does Not Equal operators.  Any other operator will treat both sides as Strings.

A DateTime, Decimal, Integer, and IP Address can only be compared to an item or value of the same type using the Equals / Does Not Equal, Greater Than, Greater Than or Equal To, Less Than, or Less Than or Equal To operators.  Any other operator will treat both sides as Strings.

All operators are valid for the String data type.  For example one can use the operator "Contains" with an Integer field called Phone Number where ${f.'Phone Number'} is on one side of the equation and 678 is on the other.  The Integer phone field will be turned into a string first and then the Contains operator will be applied to look for the substring "678".