Home → API Manual → Live Lookup → Live Lookup Configuration and Implementation

1.2. Live Lookup Configuration and Implementation

As mentioned in the previous page, live lookup works by passing information currently available about a customer in a request to an external script you specify.

This is done through either the command line or over http/https (recommended). Once HelpSpot sends all available information via HTTP or as arguments to the command line script, your script will then processes those arguments to find out additional details about the customer and returns a very simple XML document outlined below.

Steps to Set up

  1. Enable live lookup in admin->settings. Specify if the script is http or command line and provide the full path.
  2. Once enabled, the Live Lookup tab will become active in the customer information box. When this tab is clicked a live lookup request will be made to the location you specified.
  3. The following attributes are passed to your script:
    • customer_id
    • first_name
    • last_name
    • email
    • phone
    • request
    • sUserID
    • xStatus
    • xCategory
    • xPersonAssignedTo
    • Custom# (# is the ID of the custom field being passed)
    • acting_person_xperson (staffer running the Live Lookup)
    • acting_person_fusertype (staffer level 1-admin, 2-HD, 3-L2, 4-Guest)
    • acting_person_fname
    • acting_person_lname
    • acting_person_email

    Note: In command line mode, as of HelpSpot 5.3.0, they are passed in as named parameters. For example:

    /livelookup.sh --customer_id=123456 --first_name=Bob --last_name=Jones --email --phone.

    Prior to HelpSpot 5.3.0, command line live lookup used unnamed options.

    When using live lookup in HTTP mode these are passed as shown. For example, given the information in the image above, HelpSpot would pass this HTTP GET string to your script:
    ?customer_id=123456&first_name=Bob&last_name=Jones&email=&phone=

  4. Your script will process the search parameters passed in and return a result set. A result set containing only one <customer> element is considered a direct match by HelpSpot and the data will be displayed. If multiple <customer> elements are returned then a list of possible matches will be shown to the staff member. They may then click on each to view the details.

Sample PHP Live Lookup scripts are available here:

 

XML Specification

Below is a description and samples of the XML file your script should return when called from HelpSpot Live Lookup. For quick studies here's a simple example:

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<!-- These are standard elements which can be inserted back into a request -->
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<!-- These are custom elements which may be useful to the help desk staff member -->
		<organization>Sample Inc</organization>
		<password>The Password</password>
	</customer>
</livelookup>

Here's a larger Sample File

Root element: <livelookup>

This element must always be the root element of your document. It can contain these attributes:

Attribute Description Example
version A version string, currently 1.0 version="1.0"
columns This attribute tells HelpSpot which columns to display to your staff when more than one <customer> element is returned. columns="Organization,Contract_Date"

Sub element: <customer>

A live lookup result set may contain any number of <customer> sub elements. When none are returned HelpSpot will interpret this to mean no results were found for the search. One is a direct match and if more than one is found each customer element will be listed using the columns described above in the <livelookup> element.

Each <customer> element must return the sub element <customer_id>. All other elements are optional, but if found they will be insertable into HelpSpots request fields.

Element Description Example
<customer_id> Required: should return a unique value for the customer <customer_id>12334</customer_id>
<first_name> The customers first name <first_name>Bob</first_name>
<last_name> The customers last name <last_name>Jones</last_name>
<email> The customers email address <email>bjones@sampleinc.com</email>
<phone> The customers phone number <phone>845-555-8765</phone>
<Custom#> A custom field value where # is the Custom field ID from Admin->Organize->Custom Fields. <Custom1>New York City</Custom1>

User Defined Elements

In addition to the predefined elements listed above, user defined elements specific to your installation may be returned. These elements will be show in the results along with the predefined ones. For example, you may want to return the customers password so staff don't have to continue looking up the password in a seperate browser window. To do that you would simply return <password>The Password</password> along with the other elements in your <customer> tag. The examples below show this feature.

Returning HTML

You can return HTML in your Live Lookup results by using a standard cdata block such as:

<admin_link>
<![CDATA[
<a href="http://admin.company.com">Company Admin</a>
]]>
</admin_link>

This is very useful for passing back tables of information, links to other systems or to emphasize information such as turning an expired support contract into red text.

Custom Field Example

To pass information in which maps to a custom field you need to add your XML tags in a special format. The tags should be <Custom#> where # is the ID number of the custom field (shown on the custom field page within HelpSpot). This tag is case sensitive and will automatically show the correct name of the custom field when the field is displayed.

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<organization>Sample Inc</organization>
		<Custom1>New York</Custom1>
		<Custom5>Building 743</Custom5>
	</customer>
</livelookup>

Example: Single Match

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<organization>Sample Inc</organization>
		<password>The Password</password>
	</customer>
</livelookup>

Results in:

Example: Multiple Matches

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<organization>Sample Inc</organization>
		<password>The Password</password>
	</customer>
	<customer>
		<customer_id>56757</customer_id>
		<first_name>Tina</first_name>
		<last_name>Smith</last_name>
		<email>tsmith@sampleinc.com</email>
		<phone>845-555-8932</phone>
		<organization>Sample Inc</organization>
		<password>abcdefg</password>
	</customer>
	<customer>
		<customer_id>95544</customer_id>
		<first_name>Tim</first_name>
		<last_name>Myers</last_name>
		<email>tmyers@sampleinc.com</email>
		<phone>845-555-9812</phone>
		<organization>Sample Inc</organization>
		<password>thyekbg</password>
	</customer>
</livelookup>

Results in:



Knowledge Tags
API  /  Live Lookup  / 

Downloads

Related Pages
This page was: Helpful | Not Helpful
← Live Lookup Overview Configuration for Global Address Book →