Using Interface.aspx

TSL Ping Tree > Page Usage

Using Interface.aspx

An Interface is the physical part of posting leads for a given Lead Point.  If you have an agreement with one of your Lead Buyers to buy leads at different price points based on its real-time assessment of quality and uniqueness, for example, then you would probably use just one Interface for that Lead Buyer and you would have a Lead Point for each pricing tier in your agreement.

 
Configuration Item Description
Name A unique interface name up to 255 characters.
Lead Buyer The lead buyer associated with this interface.
Notes This is used for you to add any descriptions about the interface that you want.
Enabled When an interface is disabled then no Lead Points that use this interface will be executed.
Post Type The post type can be one of the following:

-none- - This interface type does not build posting URL, it does not post to another system, and it does not process any response. This interface type can be used as a place holder to run filters. Note that if you specify a post type of "-none-" then you can not access configuration to define how to process the response since without a post, there can be no response. Duplicate rules for "On Post" and "On Any Response" do not cause a set but "On Accept" and "On Decline" duplicates do get set. All duplicate types get tested.

Build Redirect URL Only (no post) - This interface type does not post to another system and it does not process any response. It just builds up a redirect URL. Duplicate rules for "On Post" and "On Any Response" do not cause a set but "On Accept" and "On Decline" duplicates do get set. All duplicate types get tested.

Get/QueryString - This interface type sends the data to the remote system using an HTTP "GET" method posting all of the form data to the URL using URL encoded name/value pairs separated by "&"

Post - This interface type sends the data to the remote system using an HTTP "POST" method. The content type is sent as "application/x-www-form-urlencoded".

XML/Soap - This interface type sends the data to the remote system as the body of an HTTP "POST" method with the content type sent as "text/xml".

Post Http Headers This option allows you to inject one or more HTTP headers into the HTTP request to the remote system. Each header entry is in the format Tag:Value  Note that if you specify the same Tag more than once only the last instance of that Tag will be posted.  This is frequently used in SOAP requests to put in the action type--for example: 

SOAPAction: "http://somecompanyxyz.com/webservices/SubmitLead"

You can also use this to override headers that the system put in, such as

Content-Type:"some-other-content-type"
Post Tags for Empty Values If this option is checked then any values that are empty are sent as "tag=". If the option is unchecked then any empty values are not sent at all. This setting does not apply to XML/Soap interfaces.
Post Xml Template For XML or Soap interfaces this is the layout of the XML document to be posted to the remote system. For Soap interfaces, include all of the Soap envelopes surrounding the XML body. This MUST be valid XML.
Post Xml Soap Parameter Root This is a path that is added to the front of every parameter name that is defined with a leading "." for its name. If a parameter name does not start with a leading "." then it is considered to be a absolute path in the XML and this root path is not added to the front of that name.
Response Type The response type can be one of the following:

-none- - No response is parsed. The response will always be considered an Accept.

Delimited Attribute/Value List - An example of this type of response is "response=accept|amount=7.00".

Delimited Value List - An example of this type of response is "accept|7.00" or a simple response where "0" means decline and "1" means accept or vice versa.

XML - The response is XML.

JSON - The response is JSON.

Custom - The response is handled by a custom response handler written by TSL staff.

Custom Response Handler (only for Response Type=Custom)

This is the name of the custom response handler. TSL staff will provide this for you once they have finished writing the custom handler.
Response Field Delimiter The single character that separates the fields. For example, this would be "|" for a delimited attribute/value list response like "response=accept|amount=7.00" or for a delimited value list response like "accept|7.00".
Response Value Delimiter The single character that separates the the attribute and value in a delimited attribute/value list. This would be "=" for a response like "response=accept|amount=7.00".
Resp XML Parameter Root This is a path that is added to the front of every response path that is defined with a leading ".". If a response path does not start with a leading "." then it is considered to be a absolute path in the XML and this root path is not added to the front of that path.
Lead Point Variables

Lead Point Variables (LPV) are used to provide values that change for each Lead Point. A common use for this is when you are posting to one lead buyer with the same format post but at different price levels.

Let's say that the lead buyer has a parameter called "LVL" which is set to either "A" or "B" depending on the price level. You could define a LPV called "Level" and use this Lead Point Variable as the mapping for the parameter LVL.

Name - A unique name of up to 255 characters defining the name of the Lead Point Variable.

Description - A description of this LPV of no more than 255 characters.

Interface Parameters

Parameters are the individual values that get sent to the lead buyer.

Name - A unique name of up to 255 characters. For non-XML/Soap interfaces this can be any legal HTTP parameter name. For XML/Soap interfaces this is the path into the XML that describes this node. See XML/Soap Parameters and Responses for more information.

Expression - Any valid Token string. See Token Substitution for more information on expressions that can be used in this field.

Test Protocol Expression - If "Same as Expression" is checked then Lead Points in test mode use Expression as the value. If "Same as Expression" is not checked then you can specify a unique expression in the "Test Expression" field to be used when the Lead Point is in test mode. See Token Substitution for more information on expressions that can be used in this field.

Notes - You can provide a description for this parameter here.

Required - Checking this makes the parameter required. If the parameter evaluates to the empty string, the lead will not be posted and the disposition for the interface will be Failed due to Missing Required Parameter.

Interface Dispositions

Dispositons allow you to map responses to dispositions for the Interface. The dispositions you can map based on the response are:

  • Accepted
  • Declined
  • Declined as Duplicate
  • Declined as Error
  • Failed due to Configuration Error
  • Failed due to Unexpected Error
If none of your dispositions match the response then the disposition will be "Failed due to Unexpected Error".

The format of the locations for the individual parts of the response depend on the type of the response:

  • Delimited Attribute/Value List - Set the location to the name of the attribute. For example given a response like "rslt=accept|amt=7.00" The result location name should be "rslt" and the location name for the receivable amount would be "amt".
  • Delimited Value List - Set the location to the position number of the value. The position is ZERO based, so for a response like "accept|7.00" then the result location would be "0" and the location for the receivable amount would be "1".
  • XML - Set to the path to the value such as "response.result". See XML/Soap Parameters and Responses for more information.

Location - The location of the value to be evaluated to determine the disposition.

Match String - The string to compare against to determine the disposition. For example "accept". Note the comparisons are case insensitive.

Match Type - Determines the type of comparison used between Location and Match String to determine if there is a match for this disposition. It can be one of these:

Note that if possible, you should use exact matches. If you use a Contains("accept") and your lead buyer changes the decline response from "decline" to "not accepted" your Contains("accept") would now treat a decline response as an accept.

Disposition - Determines the disposition of responses matching the above comparison.

Notes - You can provide a description for this response here.

The remaining values that can be parsed out of the response may or may not be present in the response. The system allows you to define if it is acceptable for a value to be missing. Missing values can be treated in one of these ways:

  • Error - If the value is missing then the disposition will be set to Failed due to Unexpected Error.
  • Warning - If the value is missing then it does not affect the disposition but an internal error message is logged.
  • No Warning or Error - If the value is missing then it does not affect the disposition and no error is logged.

Unique ID - The location of the unique id

Receivable Amount - The location of the reported receivable amount.

Redirect Url - The location of the redirect URL

Message - The location of any message in the response. Note for an XML response if there is an path such as Response.Errors that contains multiple "Error" attributes below it then you can specify "Response.Errors" as the location and all of the values for each "Error" node below it will be concatenated together to form the Message value. An example of this would look like:

<Response>
      <Errors>
            <Error>error number one</Error>
            <Error>error number two</Error>
      </Errors>
</Response>

Using the Post and Response Wizards

There are several powerful wizards built into this page to help you create or update an interface based on a posting specification.

Merging New Posting Specification into Existing Interface

It is quite common to receive a new posting specification which requires you to determine if you need to update your mappings. If you use the wizard (on either XML or non-XML interfaces) after fields are already in the form the parameter list on the "Post General" tab gets a temporary column added to it called "Merge Status" (this column is not saved to the configuration). When you import fields this column gets set to one of three values:

  • "exists" means that the parameter was already defined in the interface and it was also in the newly imported list of fields. This likely means that there is nothing further to do for this parameter.
  • "new" means that the parameter was NOT already defined in the interface. This means that you need to define the mapping for this parameter.
  • If the "Merge Status" column is empty, this means that the parameter was defined in the interface and it was NOT in the list of fields imported. This may mean that you need to remove the parameter from the interface.

The way you used these wizards is slightly different for each type of post and response so this article will go over each type independently.

Post Tools - non-XML/Soap

You can either paste in a list of fields or an example query string and press the appropriate button (either "Import List of Fields" or "Import From Query String"). If you are pasting in a list of fields, the individual fields can be separated by spaces, newlines, commas, or semicolons. When you press the appropriate import button, the fields are added to the list of parameters on the "Post General" tab.

Post Tools - XML/Soap

Paste the XML or Soap into the top text box and if the XML uses attributes check "Use XML Attributes". See XML/Soap Parameters and Responses for an explanation of attributes. Next press the "Process XML" button. Check the lower box to make sure there are no errors in the XML parsing and then select an XML posting root from the dropdown. The dropdown shows the likely roots and how many times each of them are used in the XML. Once you've selected the posting root, click "Set Up Interface". This populates several items on the "Post General" tab:

  • Post XML Template
  • Post XML Parameter Root
  • Parameters

Response Tools - XML/Soap

Paste the XML or Soap response into the top text box and if the XML uses attributes check "Use XML Attributes". See XML/Soap Parameters and Responses for an explanation of attributes. Next press the "Process XML" button. Check the lower box to make sure there are no errors in the XML parsing and then select an XML response root from the dropdown. The dropdown shows the likely roots and how many times each of them are used in the XML. Next select the dispostion. Then select the XML path to the disposition from the "Location" dropdown. When you select this, the "Match String" field will be populated with the value that was in that path in the example XML and a match type will be set to "Exact Match". Next select the path for any other values (Unique ID, Receivable Amount, Redirect URL, and Message) that should exist for this disposition type. Finally press the "Set Up Response" button. This adds the disposition on the "Response General" tab.

Response Tools - JSON

Paste the JSON response into the top text box. Next press the "Process JSON" button. Check the lower box to make sure there are no errors in the JSON parsing and then select a response root from the dropdown (For JSON responses, the system creates a top level node named "root" . The dropdown shows the likely roots and how many times each of them are used in the XML. Next select the disposition. Then select the JSON path to the disposition from the "Location" dropdown. When you select this, the "Match String" field will be populated with the value that was in that path in the example JSON and a match type will be set to "Exact Match". Next select the path for any other values (Unique ID, Receivable Amount, Redirect URL, and Message) that should exist for this disposition type. Finally press the "Set Up Response" button. This adds the disposition on the "Response General" tab.

See also: