Reference - Token Substitution

TSL Ping Tree > Reference

Reference - Token Substitution

Token Substitution is available in several places to turn placeholders for selected data items into specific String values at run time.

Places where Token Substitution is done include:

  1. Interface - Parameter Mapping - For example, an Interface might map its FIRSTNAME parameter using the string "${f.'First Name'}".

  2. URL Set - URL - For example, a URL might be specified as "http://www.somewhere.com/offer.php?affiliate_id=${sp.'Affiliate ID' urlencode}".

  3. Promotion - Pixel - For example, a Pixel might be specified as "<img src='http://www.somewhere.com/imgpixel.php?tracking_id=${sp.'Sub ID 1' urlencode}'>".

You don't need to memorize our token formats!  We have graphical Expression Builders everywhere that Token Substitution expressions are allowed.

If you are interested in the details about the format of our tokens or you want to review the entire set of available data items for our tokens then continue reading this document.


The general format of a Token Substitution expression is ${Category.'Item Name' modifiers}.

The Category.'Item Name' part is one unit - an item.  Either it and/or modifiers must be specified.  An example with just an item is ${f.'First Name'} which represents the current value of the user defined field First Name.  An example with just modifiers is ${chr(9)} which represents the Tab character.  For more about modifiers see Reference - Modifiers.

Some categories support or require an index after the item name, e.g. ${lpr.'Disposition'(123)} produces the ping tree disposition for lead point number 123.

Categories

Category Description and Allowed Tag Names
Field - f a custom Field that you have defined, e.g. ${f.'EmailAddress'}
Global Constant - gc a custom Global Constant that you have defined, e.g. ${gc.'MegaBuyerAffiliateId'}
Lead Point Item - lpi one of the following properties for the current Lead Point

${lpi.'Allowed Response Time'} - the configured "Timeout Seconds" for this Lead Point in the current Ping Tree; useful when the corresponding system accepts a maximum response time parameter

${lpi.'Generated Ping/Post GUID'} - the Globally Unique Identifier that is generated at run time when this Lead Point is considered in the current Ping Tree, e.g. "96182090-3faa-11e2-a25f-0800200c9a66"; this is good to use when the corresponding system accepts a unique identifier for the post

${lpi.'Internal ID'} - its Internal Unique Identifier; an integer value

${lpi.'Test Mode'} - indicates whether this lead point is in test mode; a checkbox value

${lpi.'Tier Name'} - the text name of the ping tree tier which contains the currently running lead point.  This value is available before tier filters run; a string value

${lpi.'Tier Number'} - the position number of the ping tree tier which contains the currently running lead point.  This value is available before Tier filters run; an integer value with the first tier starting at 1
Lead Point Response Item - lpr(index a particular part of the response received for the specified Lead Point during this Ping Tree run

The Lead Point Response Item data dictionary category allows you to back reference responses from earlier in the Ping Tree.  The index is the Internal ID for the Lead Point; this is a globally unique integer value.  The Expression Builder presents a list of all Lead Points by name when working with Lead Point Response Items so that you do not have to know an internal integer identifier for a Lead Point.

${lpr.'Disposition'(1234)} - the integer Disposition value; see Reference - Dispositions for the possible values

${lpr.'LookSequence'(1234)} - the order in which this Lead Point received a post (a.k.a. a "look" at the lead) in the current Ping Tree run; this value will be zero if filters were not met e.g.

${lpr.'Position'(1234)} - the configuration Position of this Lead Point in the current Tier of the current Ping Tree

${lpr.'PostSequence'(1234)} - the order in which this Lead Point was considered in the current Ping Tree run

${lpr.'ReceivableAmount'(1234)} - the receivable amount; zero if no receivable event was raised

${lpr.'ResponseDisposition'(1234)} - the raw string captured for Disposition during response mapping

${lpr.'ResponseMessages'(1234)} - the raw string captured for Messages during response mapping

${lpr.'ResponseReceivableAmount'(1234)} - the raw string captured for Receivable Amount during response mapping

${lpr.'ResponseRedirectUrl'(1234)} - the raw string captured for Redirect URL during response mapping

${lpr.'ResponseStatus'(1234)} - the HTTP status of the response when the Interface is an HTTP type

${lpr.'ResponseUniqueIdentifier'(1234)} - the raw string captured for Unique ID during response mapping

${lpr.'Tier'(1234)} - the configuration Tier where this Lead Point exists in the current Ping Tree
Lead Point Variable - lpv
a custom Lead Point Variable setting for the current Lead Point as permitted by the set of Lead Point Variables defined for the Interface that the Lead Point uses, e.g. ${lpv.'TierId'}

Lead Point Variables are not common.
  They are available for situations where for example a lead buyer allows you to post in to the exact same Interface at multiple tiers and payouts and each of your posts must specify some sort of tier ID in their system.  Rather than have to create a copy of the Interface definition for each Lead Point you make a single Interface and you define Lead Point Variables for the parts that differ from Lead Point to Lead Point.

For example to have a different buyer's tier ID for each Lead Point you can define a custom Lead Point Variable for the Interface called "TierId".  Then for each Lead Point that uses this Interface you set the value of this variable.  At post time the expression ${lpv.'TierId'} will evaluate to the value that you assigned to the Lead Point.
System Attribute - sa System Attribute started out as a category for items like the current HTTP request's IP address or the current date and time.  It has since become a sort of catch-all for items that don't seem to fit into any of the other data dictionary categories and that did not justify creating a new category at the time.

${sa.'Buyer Names This Ping Tree Run'} - a tab-delimited list of the lead buyer names that have produced quota-counting accepts so far for the current ping tree execution; this is useful for example to communicate a summary of what happened during a ping tree run to a CRM at the bottom of that ping tree

${sa.'IP Address'} - the current HTTP request's IP address;  for the IP address of the lead as specified by the trusted system that is posting the lead use ${sp.'Browser IP Address'}

${sa.'Lead Accept Count This Ping Tree Run'} - the total number of quota-counting accepts so far for the current ping tree execution only; does not include prior ping tree runs for same ping tree and lead

${sa.'Lead Accept Count Total'} - the total number of quota-counting accepts so far for the current lead including prior ping tree runs; uses ping tree's Unique Lead definition

${sa.'Now'} - the current date and time;  to be specific about the time zone and the format use the time zone and format modifiers, e.g.
${sa.'Now' timezone('Pacific Standard Time') format('yyyy-MM-dd')}

${sa.'Payout'} - the Decimal payout amount that was issued during the HTTP request; only guaranteed to have a non-zero value at the end of the HTTP request, e.g. if the request is running on submit.ashx then this token will only have a non-zero value at the end of running the ping tree and if and only if a payout was triggered during the processing of the request; this token is meant for Promotion pixels only

${sa.'PayoutId'}
- a String payout ID if a payout was issued during the HTTP request; only guaranteed to have a good value at the end of the HTTP request, e.g. if the request is running on submit.ashx then this token will only have a GUID value other than "00000000-0000-0000-0000-000000000000" at the end of running the ping tree and if and only if a payout was triggered during the processing of the request; this token is meant for Promotion pixels only

$(sa.'Revenue This Transaction'}
- the Decimal total revenue booked so far during the processing of this HTTP request not including any revenue generated from previous HTTP requests for the same Click.

${sa.'URL Scheme'}
- either "http" for non-SSL or "https" for SSL based on whether the current HTTP request is using SSL; this is useful for example to build a redirect URL that matches the current request's SSL mode
System Parameter - sp a System Parameter is a reserved inbound HTTP parameter, e.g. "pt" is for specifying the ID of the Ping Tree to execute on a form submission

${sp.'AcceptRedirectUrl'}  ( parameter = acceptredirecturl )  - submit.ashx only; allows the caller to override the default redirect URL on an overall Accept disposition for the Ping Tree

${sp.'Affiliate ID'}  ( parameter = a )  - valid for all click handlers as well as submit.ashx for a "headless site"; this optional tracking parameter allows the caller to augment the tracking signature with an ID for itself

${sp.'Affiliate/Promotion Authentication Key'}  ( parameter = k )  - reserved for future use and will be valid for all click handlers as well as submit.ashx for a "headless site"; this optional parameter will allow the caller to authenticate itself with a password once we roll out an Affiliate Management module where Affiliates are managed configuration items; today there is no easy way to use this parameter

${sp.'Browser IP Address'}   ( parameter = ip )  - valid for all click handlers as well as submit.ashx for a "headless site"; this parameter allows the caller to specify the IP address of the lead when the current inbound HTTP post is being routed through a server versus coming directly from a web browser; when not specified then the value will be the IP address of the current HTTP request

${sp.'Click ID'}  ( parameter = c )  - valid for all handlers; this is a globally unique integer ID for the Click... our system's internal unique identifier for every "visit"

${sp.'DeclineRedirectUrl'}  ( parameter = declineredirecturl )  - submit.ashx only and only for a Ping Tree that issues an HTTP Redirect versus an XML response; allows the caller to override the default redirect URL on an overall Decline disposition for the Ping Tree

${sp.'ErrorListParameter'}   ( parameter = errorlistparameter )  - submit.ashx only and only for a Ping Tree that issues an HTTP Redirect versus an XML response; allows the caller to override the parameter name to append to the ErrorRedirectUrl and encode with any encountered errors on an overall Error disposition

${sp.'ErrorListType'}   ( parameter = errorlisttype )  - submit.ashx only and only for a Ping Tree that issues an HTTP Redirect versus an XML response; allows the caller to override the parameter name to append to the ErrorRedirectUrl and encode with any encountered errors on an overall Error disposition
  • H = HTML List Item
  • T = Tab Delimited
  • N = None
${sp.'ErrorPostErrors'}   ( parameter = errorposterrors )  - CheckBox data type for submit.ashx only and only for a Ping Tree that issues an HTTP Redirect versus an XML response; allows the caller to override whether to post errors to the ErrorRedirectUrl on an overall Error disposition; accepted inbound values for YES are "1", "on", "t", "true", "y", or "yes"; anything else is interpretted as NO

${sp.'ErrorPostFormFields'}   ( parameter = errorpostformfields )  - CheckBox data type for submit.ashx only and only for a Ping Tree that issues an HTTP Redirect versus an XML response; allows the caller to override whether to post field names to the ErrorRedirectUrl along with any field specific errors on an overall Error disposition; accepted inbound values for YES are "1", "on", "t", "true", "y", or "yes"; anything else is interpretted as NO

${sp.'ErrorRedirectUrl'}   ( parameter = errorredirecturl )  - submit.ashx only and only for a Ping Tree that issues an HTTP Redirect versus an XML response; allows the caller to override the default redirect URL on an overall Error disposition for the Ping Tree

${sp.'Landing Page URL'}   ( parameter = lp )  - clickthru.ashx only; allows the caller to specify an explicit landing page

${sp.'Maximum Wait Seconds'}   ( parameter = w )  - submit.ashx only; allows the caller to request that the Ping Tree runs at most this many seconds

${sp.'Minimum Payout'}   ( parameter = p )  - submit.ashx only; allows the caller to require that at least this amount must be earned as a payout in order for the lead to get an overall Accept disposition;  only works for revenue share promotions

${sp.'NoAcceptRedirectUrl'}   ( parameter = noacceptredirecturl )  - submit.ashx only; allows the caller to specify that there is to be no default redirect URL on an overall Accept disposition for the Ping Tree regardless of the Ping Tree's configuration

${sp.'Ping Tree ID'}   ( parameter = pt )  - submit.ashx only; this required parameter specifies the ID of the Ping Tree to run

${sp.'Promotion ID'}
   ( parameter = p )  - valid for all click handlers as well as submit.ashx for a "headless site"; this required tracking parameter specifies the ID of the Promotion (a.k.a. campaign)

${sp.'Response Format'}   ( parameter = rfmt )  - submit.ashx only; allows the caller to override the response format
  • X = XML
  • R = Redirect
${sp.'Session ID'} - reserved for future use; will always be "00000000-0000-0000-0000-000000000000" today

${sp.'Site ID'}   ( parameter = s )  - valid for all click handlers as well as submit.ashx for a "headless site"; this optional tracking parameter specifies an ID for the web property where the lead originated

${sp.'Sub ID 1'}   ( parameter = s1 )  - valid for all click handlers as well as submit.ashx for a "headless site"; this optional tracking parameter allows the caller to augment the tracking signature for the click with a custom ID

${sp.'Sub ID 2'}   ( parameter = s2 )  - valid for all click handlers as well as submit.ashx for a "headless site"; this optional tracking parameter allows the caller to augment the tracking signature for the click with a custom ID

${sp.'Sub ID 3'}   ( parameter = s3 )  - valid for all click handlers as well as submit.ashx for a "headless site"; this optional tracking parameter allows the caller to augment the tracking signature for the click with a custom ID