Import Overview

This document is designed to help explain the technical details necessary create one time and recurring data imports within Testimonial Tree. The overall goal is to create a seamless user experience for professionals. Part of that experience is to make sure users have an account with updated data on Testimonial Tree and that feedback can be requested.

Data Transfer Options

There are a number of ways TT can get access to the data required for automation.

1. Pull from customer's FTP
2. Customer pushes to our FTP (or sFTP)
3. TT pulls from URL hosted by customer (http or https)
4. TT can pull from customer's API
5. Customer can use TT's API 

If you chose to use TT's API, here is a link to some documentation:

https://documenter.getpostman.com/view/1022086/testimonialtree-api/2LNYbH#46a2bfb1-df90-9149-ee43-c543a15d2a84 

Import Setup

Generally, TT will setup any imports for enterprise level customers.  We work with customers to make sure we map the data correctly, etc.

Import Types

The type of import allows for multiple different imports to occur. There are five separate imports that are available, these imports are:

• Locations
• Survey Requests
• Teams
• Testimonial Requests
• Users

Each type of import has been specifically designed to efficiently import data into the correct locations by way of mapping different data fields for each type.

Import Name

This is the name of the import that is used for reporting and reference. This has no bearing on imported data or functionality.

Recurring Schedule

Scheduling can be set to only import the file at the time of import and no more, or it may be set to be a recurring import.

Testimonial Tree allows for a very wide range of import options. A start date and time must be first entered; all recurrences are based on the original start date and time. Imports can recur as frequently as hourly, but are able to recur once a day or weekly on selected days of the week. The ending can then be selected to either not end, end after a specified number of occurrences, or to end on a specific date.

Notes:

1. Recurring imports cannot use uploaded files, they are required to use an internet URL.
2. Time is based on GMT. Testimonial Tree will try to note the local time when GMT Is entered but the computer must be in the correct time zone. Please use http://www.worldtimebuddy.com/ if there are any questions about time zones and execution times.

FTP Upload

Data for importing may optionally be uploaded to Testimonial Tree’s FTP server located at ftp.testimonialtree.com. (SFTP available, as well.) More information here https://testimonialtree.zohodesk.com/portal/en/kb/articles/ftp-setup-for-survey-automation

During import configuration a copy of the data file is required. It is used for data column mapping and data integrity checks as well as for the first processing at the time of import creation.

The file uploaded to the FTP server must have the exact same filename as the file used in creating the import and must be unique between all of the imports created by a single user.

Data File

The data file can either be a single uploaded file (for one time imports only) or it can be an internet URL in XML, CSV, or PSV format.

URLs can either be HTTP, HTTPS, or FTP addresses. FTP will require the username and password for the FTP server to be entered. HTTP access must be publicly available for web requests to come in without authentication.

Mapping

Once the import type has been specified, imports are uploaded and pared for mapping. In this stage, each of the fields in the data set are displayed, and 5 rows of data are displayed. The dropdowns for each column/field should be set to the type of data. Once each column has been mapped with the dropdown then the data can be imported, and if it is a recurring it, the schedule is set in the scheduler. 

Locations

Introduction

Physical locations allow for creating logical grouping of users based on the physical location that they are at, whether that location is a branch office, a store, brokerage, or a dealership.

Fields

Below are the fields that Testimonial Tree is capable of importing for Locations, not all fields are required and fields that are not used do not need to be in the import feed/file, they would not be mapped during the import setup process.

Please be aware that the Manager Email and Manager Username are not both required to assign a manager, only one is needed if a manager should be assigned to the location. However, for any additional Location managers, the username is required. Furthermore, any additional Location managers must abide to the required format. The usernames must be surrounded by curly braces {} and must be separated by only a comma with no spaces. See the Data Format Example below.

• Address 1
• Address 2
• City
• Country
• Description
• Email Address
• Facebook Page
• Manager Email
• Manager Username
• Additional Manager Usernames
• Location Code
• Location Name
• Phone Number
• Photo URL
• State
• Website URL
• Zip

Data Format Example 

Testimonial Tree can handle XML, CSV, and PSV files, below is an example of an XML entry.

<?xml version="1.0" encoding="UTF-8"?>

<locations>

            <location>

<address1></address1>

<address2></address2>

<city></city>

<country></country>

<description></description>

<email></email>

<facebook_page></facebook_page>

<manager_email></manager_email>

<manager_username>fred</manager_username>

<additional_managers>{username1,username2,username3}</additional_managers>

<code>north</code>

<name>North Branch</name>

<phone></phone>

<photo></photo>

<state></state>

<website></website>

<zip></zip>

            </location>

</locations>

Example Files

XML – http://www.testimonialtree.com/secure/import/examples/xml_locations.txt

CSV – http://www.testimonialtree.com/secure/import/examples/csv_locations.txt

PSV – http://www.testimonialtree.com/secure/import/examples/psv_locations.txt

Survey Requests

Introduction

Survey requests allow for automated requests for survey responses to be sent out periodically without the need to send out requests manually, one at a time.

Fields

Below are the fields that Testimonial Tree is capable of importing for Survey Requests, not all fields are required and fields that are not used do not need to be in the import feed/file, they would not be mapped during the import setup process.

The Recording Userid/Email should be set to assign the results to a specific user if the response should not be assigned to the primary Userid/User Email.

Please be aware that the Userid and User Email are not both required to assign the response to the user, only one is needed if the response should be assigned to a specific user. This also is applicable for Recording Userid and Recording User Email.

Fields that are bold are required fields.

• To Email Address - Recipient of the survey requset
• To Name - Name of recipient
• Survey ID - ID of survey in TT (can get from admin screen)
• Userid - userid of sender of survey (not required since it usually is enterprise level user)
• Tracking ID - Can pass a unique tracking ID, if it exists
• Recording Userid - Userid of sub-user in TT.  This ties the survey to that user.  
• Recording User Email - If no recording userid exists, we can use the users's email
• Email Template ID - not commonly used.  
• *Custom Data Fields - Any other data can be passed in and stored. This is very helpful when pulling data back out or connecting data in TT to other datasets in outside systems.

Custom Data Fields

In addition to the standard fields for survey requests, custom field data may be sent in as well if custom fields have been defined within the survey. These fields must always be the last fields for each data row and must be defined in one of two ways depending on the data format.

If the chosen format is XML then the node name must be the custom field name and there must be an attribute of type=”datafield”

If the desired format is either CSV or PSV then the column name in the header must be wrapped in curly brackets

XML example: <my_custom_field type="datafield">XML test content</test_1>

CSV/PSV header example: {my_custom_field}

 The Tracking ID field is an optionally required field. What that means is that if advanced transactional notifications retries are required, it is required. If basic requests are all that are needed, then it is not required.

The Tracking ID is a unique ID per transaction request allowing for Testimonial Tree to track the request coming in the feed. This allows for multiple requests to be sent to the same person/email address but allowing them to be distinct and separate at the same time.

Notes:

1. Custom data fields must come after every single other field, they are required to be the very last fields in the dataset whether it is XML or delimited data.

Data Format Example  

Testimonial Tree can handle XML, CSV, and PSV files, below is an example of an XML entry.

<?xml version="1.0" encoding="UTF-8"?>

<requests>              

<request>                              

<toemail>fred@yahoo.com</toemail>                              

<toname>Fred User</toname>                               <surveyid>2</surveyid>                               <trackingid>sale9204123</trackingid>                               <userid>john</userid>                              

<useremail></useremail>                               <emailtemplateid>1004</emailtemplateid>                               <recorduserid>jane</recorduserid>                              

<recorduseremail></recorduseremail>                              

<test_1 type="datafield">XML test content</test_1>                               <new_home_consultant type="datafield">XML home cont test data</new_home_consultant>              

</request>

</requests>

Example Files

XML – http://www.testimonialtree.com/secure/import/examples/xml_surveyRequest.txt

CSV – http://www.testimonialtree.com/secure/import/examples/csv_surveyRequest.txt

PSV – http://www.testimonialtree.com/secure/import/examples/psv_surveyRequest.txt

Teams

Introduction

Teams allow for creating logical grouping of users based on the role or group that they are in, whether that team is sales, finance, team, or a department.

Fields

Below are the fields that Testimonial Tree is capable of importing for Teams, not all fields are required and fields that are not used do not need to be in the import feed/file, they would not be mapped during the import setup process.

Please be aware that the Leader Email and Leader Username are not both required to assign a leader or manager, only one is needed if there is a team leader.

• Address 1
• Address 2
• City
• Country
• Description
• Email Address
• Facebook Page
• Leader Email
• Leader Username
• Team Code
• Team Name
• Phone Number
• Photo URL
• State
• Website URL
• Zip

Data Format Example 

Testimonial Tree can handle XML, CSV, and PSV files, below is an example of an XML entry.

<?xml version="1.0" encoding="UTF-8"?>

<teams>

            <team>

<address1></address1>

<address2></address2>

<city></city>

<country></country>

<description></description>

<email></email>

<facebook_page></facebook_page>

<leader_email></leader_email>

<leader_username>fred</leader_username>

<code>north</code>

<name>North Team</name>

<phone></phone>

<photo></photo>

<state></state>

<website></website>

<zip></zip>

            </team>

</teams>

Example Files

XML – http://www.testimonialtree.com/secure/import/examples/xml_teams.txt

CSV – http://www.testimonialtree.com/secure/import/examples/csv_teams.txt

PSV – http://www.testimonialtree.com/secure/import/examples/psv_teams.txt 

Testimonial Requests

Introduction

Testimonial requests allow for automated requests for testimonials to be sent out periodically without the need to send out requests manually, one at a time.

Fields

Below are the fields that Testimonial Tree is capable of importing for Testimonial Requests, not all fields are required and fields that are not used do not need to be in the import feed/file, they would not be mapped during the import setup process.

Please be aware that the Userid and User Email are not both required to assign the testimonial to the user, only one is needed.

Fields that are bold are required fields.

• To Email Address
• To Name
• Userid
• User Email
• Tracking ID
• Use Parent Branding
• Email Template ID 

The Tracking ID field is an optionally required field. What that means is that if advanced transactional notifications retries are required, it is required. If basic requests are all that are needed, then it is not required.

The Tracking ID is a unique ID per transaction request allowing for Testimonial Tree to track the request coming in the feed. This allows for multiple requests to be sent to the same person/email address but allowing them to be distinct and separate at the same time.

Data Format Example  

Testimonial Tree can handle XML, CSV, and PSV files, below is an example of an XML entry.

<?xml version="1.0" encoding="UTF-8"?>

<requests>              

<request>                              

<email>fred@yahoo.com</toemail>                              

<name>Fred Client</toname>                                                                                          

<userid>john</userid>                              

<useremail></useremail>                                            

</request>

</requests>

Example Files

XML – http://www.testimonialtree.com/secure/import/examples/xml_testimonialRequest.txt

CSV – http://www.testimonialtree.com/secure/import/examples/csv_testimonialRequest.txt

PSV – http://www.testimonialtree.com/secure/import/examples/psv_testimonialRequest.txt

Users

Introduction

Users are the core of Testimonial Tree’s application; each user can receive testimonials, send requests, and share testimonials.

Fields

Below are the fields that Testimonial Tree is capable of importing for Users, not all fields are required and fields that are not used do not need to be in the import feed/file, they would not be mapped during the import setup process.

There are a few notes about username that should be understood. If the username is bank or not passed then the email address will be used, as the username. Usernames will have the parent user’s username prepended to the passed username. Usernames are required to be unique thought the entire system. If, usernames are required to be exactly as passed, then the Verification button can be used but the disclaimer must be understood first within the user interface.

If the photo data field is to be used, the data should be a publicly accessible URL.

Testimonial Tree suggests that usernames not be passed within the data feed/file for security reasons, a default password can be entered during import setup, otherwise a default password of username concatenated with “!979” will be used.

Fields that are bold are required fields.

• Email Address
• Company Name
• Description
• First/Full Name
• Last Name
• Location Code  (related to Location Code in Locations Admin in TT)
• Phone Number
• Photo  (URL)
• Team Code (related to Team Code in Team Admin in TT)
• Username  (Must be unique, better than email, since emails can change)
• Website URL  (could be link to profile page for enterprise)
• Facebook Page URL (for likes)
• License Number 

Data Format Example

We can handle pretty much any data format (XML, CSV, etc), but here is an XML example.

<?xml version="1.0" encoding="UTF-8"?>

<membership>

            <member>

<company_name>Company 1</company_name>

<description>Description of the current user</description>

<email>useremail@gmail.com</email>

<first_name>Alexis</first_name>

<last_name>Jones</last_name>

<location_code>north</location_code>

<phone>123-123-1234</phone>

<photo>http://domain.com/me.jpg</photo>

<team_code>alpha</team_code>

<username>jonesal</username>

<website>http://www.yahoo.com</website>

<fbpage>http://www.facebook.com/yourpage</fbpage>

<license>SL1232414</license>

            </member>

</membership>

Example File

XML – http://www.testimonialtree.com/secure/import/examples/xml_users.txt

CSV – http://www.testimonialtree.com/secure/import/examples/csv_users.txt

PSV – http://www.testimonialtree.com/secure/import/examples/psv_users.txt