Data Integration/Upload Contacts

Jump to topics: 

Import contact page

Multiple Contact Lists

SFTP Integration 

What is PII?

Data types and .csv file format

Viewing your contacts

Reuploading contacts and updates

Automatic Contact Syncing

Analyze Demographic Data in Results 

Uploading a list of contacts to your ThoughtExchange customer account allows you to easily send invitations or set up code access for any engagements you create in that room. 

Before you upload contacts, make sure you have the following:

• A list of participant information, saved as a CSV file (Note: you can download a sample template to get a better understanding of the file formatting requirements - You can have a maximum of 25 columns of demographic data - not including the mandatory columns - in your CSV file. 
• An account with Admin permissions in ThoughtExchange.

To upload contacts to ThoughtExchange:

1. Click the avatar icon in the top right-hand corner of the page.
2. Go to Admin Settings
3. Click on the “Contacts” tab
4. Click on the “CSV Import” button (or "Reupload CSV", if one has previously been uploaded) to access the import contacts page.

Import contact page

1. File upload: upload a CSV file of your contacts. You can click on “Choose file” or drag your file to the file upload area. 
   

   Once you’ve successfully uploaded the file a ‘success’ message will appear, click on “Data mapping” to move on to the next step.

   

2. Data mapping: the data mapping step will allow you to select your CSV column data and map it to required and custom ThoughtExchange fields. 
   
   First name, Last name, and either Email or an Access code are required. An engagement access code can be based on a student or employee ID number or any other unique numerical identifier; during 'data mapping' you must match the appropriate column (in the example below it is 'Employee ID') to the Label in ThoughtExchange called 'Access code'. Map the ‘source’ columns (most left) to the ThoughtExchange fields (middle); note: you have the option to customize the labels to your liking in ThoughtExchange.
   
   If the first row of your CSV file doesn’t contain headers (e.g. Department) you can disable the ‘First row contains labels’ option.
   
   Data type: we will make our best assumptions to map the correct ‘Data type’ (furthest right) to the source data (e.g. Date = Date). Please ensure that the correct data type matches your source data.
   

   - For more information about the Opt-out column, click here

   - Unless your account has the 'Assignments' feature enabled, select the 'Column not available' option. 

   -  If you are using the 'Assignments' feature, select the column label that corresponds with the Assignment column in your CSV file. For more information about this feature, please expand the 'About ASsignments' section below. 

   About Assignments

   Assignments

   Assignments is a limited-release beta feature. It is not available to all accounts. Please reach out to your ThoughtExchange rep for more information. 
   If you have the 'Assignments' feature in your account, you can assign invited participants to participate multiple times. This feature allows invitees to provide feedback multiple times in the same engagement for different assigments, such as a person giving feedback on a pool of assigned colleagues, or a parent providing feedback on behalf of each of their children. Using a .csv contacts list with an ‘Assignment’ column, admins can now enable participants to submit a response per assignment. This feature’s first iteration works exclusively with access codes and is perfect for collecting detailed, segmented feedback.

   For example, Mary Smith has been assigned to 10 different teachers for feedback in the same survey. In the .csv file, there will be 10 rows for Mary Smith, 

   

   Note: the information in each column is identical with the exception of the Assignment column

   Once Mary opens the survey and enters her access code, she is greeted with a request to select which of her assignments she wishes to participate on behalf of first.

   

   Mary is then taken to the body of the survey which persistently displays her selected assignment. This mitigates any potential confusion.

   Once the survey is completed, Mary is prompted to submit and continue onto the next assignment.

   

   At this point, Mary is brought back to the assignments dropdown, where she can select her next assignment. She can also select a previous assignment in case she wishes to edit her responses. This cycle continues until she has participated for all assignments, at which point the button reads “Submit and complete”

   

   In Results, each response is treated as a participation. If 1000 participants each have 3 assignments, Results will summarize 3000 responses. While results cannot be filtered or compared by assignments, the Participant Response Export, Response Rate Report, and Participant Status Report would each have a column representing the assignee

   ---

   
    

   Import: once you’re happy with the mapping you’ve set up, click “Import” which will bring you to the final step to complete the import process.

When uploading contact data, do not upload sensitive or Personally Identifiable information (PII)*, other than first name, last name, email, or access code**. Contacts can be seen and used by engagement leaders; including sensitive data can create privacy and reporting issues, so always stick to these guidelines.

Editing Contact Lists

If you need to edit your contact list:

• Click the pencil icon to rename the list.
• Click the trash can icon to delete the list.
• To update individual contacts, scroll through the list, click the three dots menu next to a contact, and select Edit.

For bulk updates, you can upload a new CSV file by selecting Reupload CSV

Multiple Contact Lists 

We have expanded contact lists so that Account Admins can now upload and save multiple contact lists.

This enhancement allows Account Admins to upload a separate contact list for each engagement. Using multiple contact lists, you can schedule multiple engagements with overlapping survey windows without any interference between respective engagements.

You can access your lists Iin the 'Contacts' tab of Admin Settings. Here, you can add (+ sign) a new list, edit (pencil icon) the title of existing ones, or delete (trash can icon) existing lists. 

For each engagement, you can select the applicable contact list to ensure the right participants are invited.

You can switch lists while drafting your engagement as long as the engagement has not been launched. If you try to switch contact lists once an engagement is active, you will encounter this error:

SFTP Integration for Contact Import

This feature is currently in BETA. Understanding the requirements and limitations will help ensure a smooth process. If you would like to learn more about this feature, please reach out to your ThoughtExchange representative. 

SFTP (Secure File Transfer Protocol) integration allows you to automatically import contact lists into ThoughtExchange daily. Step-by-step guide on beginning and managing the integration. 

Important note: when using automatic uploads (via SFTP or S3), it’s important to ensure the auto-update utilizes the ‘append’ function.  This is due to the fact that automatic uploads check the source file daily.  If the upload is set to ‘overwrite’, when new information is detected in the source file, the entire contact list is reuploaded and overwrites the list.  When the upload is set to ‘append’, then only new contacts are added to the existing list.

Step 1: Preparing Your File

1. File Naming: Ensure the file is named contacts.csv. This name is mandatory for successful import.
2. Required Data Fields:
   • Include at least the following fields:
     • First Name
     • Last Name
     • Email
     • Access Code (optional, but recommended)
   • Additional demographic data can be added, but avoid sensitive Personally Identifiable Information (PII).
3. File Format: Each contact list must be named contacts.csv and saved in CSV format.

Step 2: Connecting to the xIS Platform

1. Add a New Contact List:
   • Go to Admin Settings > Contacts.
   • Click Add New Contact List and give it a unique name.
2. Choose Modification Behavior:
   • Overwrite (default): Replaces the existing file with the new file during each import.
   • Append: Adds new information from the file to the existing list.
3. Select Automation Type:
   • Choose SFTP from the dropdown.
4. Provide Connection Information:
   • SFTP Username: LTC82630
   • SFTP Endpoint (Host): prod-sftp-19e0.thoughtexchange.com
   • Authentication Type: Password or Public Key Authentication (secure transfer).
5. Important Notes:
   • The SFTP password is only available at the time of creation. To reset it, switch to Manual automation and back to SFTP.
   • Default port: 22 (leave blank unless otherwise specified by the xIS platform).
6. Save and Sync:
   • Copy and paste the connection details into the xIS platform and click Connect.
   • Return to Admin Settings > Contacts and click Sync CSV.

Step 3: Troubleshooting Connection Issues

• Red Screen Error: Indicates the file contacts.csv was not found. Ensure:
  • The file name is correct.
  • The file is located in the correct folder for the SFTP import.
• Green Screen: Indicates a successful connection. Proceed to Data Mapping.

Step 4: Data Mapping

1. Verify Data: Confirm that only required PII is included:
   • First Name
   • Last Name
   • Email
   • Access Code (optional).
2. Map Columns:
   • Match each column label in the CSV file to the appropriate label in ThoughtExchange.
   • For the Opt-out Column:
     • If the column is not in the file, select Column Not Available. This will add an Opt-out column with a default value of False (not opted out).
3. Import Data:
   • Click Import, then Complete.

Step 5: Daily Updates

• Once set up, the SFTP import will run automatically every day at 9 AM UTC.
• Integrated contact data will update based on the latest contacts.csv file.
• Engagement Tracking: The number of engagements using the integrated data is visible in the contact list view.

Tips for Success

• SFTP Endpoint = Host: Use this interchangeably when configuring the xIS platform.
• Port Settings: The default port is 22, but check with your xIS admin if a different port is required.
• File Preparation: Always double-check that the file is named contacts.csv and contains the required fields.

*What is PII? 

PII stands for Personally Identifiable Information. It refers to any data that can be used to identify a specific person. 

Information You Can Safely Upload:

• First Name**
• Last Name**
• Email**
• Access Code**
• Gender
• Ethnicity
• Grade Level
• School Name
• Enrollment in English as a Second Language (ESL) Program
• Team Name / Department Name
• Region (e.g., Americas, EMEA)

Typical Examples of Sensitive/ Personally Identifiable Information to Never Upload:

• Phone Number
• Address (Street, City, State, Zip, Postal Code)
• Date of Birth (DOB)
• ID Numbers (e.g., employee, student)
• Child’s Name (for parent data)

Less Typical examples of Sensitive/ Personally Identifiable Information to Never Upload:

• Social Security Number (SSN)
• Passport Number
• Social Media Handles
• Driver’s License Number
• Credit Card Information
• Bank Account Information
• Health or Medical Information
• GPS Coordinates

**While these data are typically considered Personally Identifiable Information (PII), it is necessary to link a contact's demographic information to an individual. ThoughtExchange ensures that these data are handled securely and are not included in survey results or presented in a way that could compromise the integrity of the survey data.

Data types and .csv file format

Each contact needs to be on its own row in the spreadsheet. If you don’t have data for a particular contact, leave the cell blank. 

 

Note: ‘Date’ and ‘Number’ type fields cannot be blank.

Accepted data types:

• Date: YYYY-MM-DD format (ISO 8601 syntax)
  • E.g. 2021-09-08
• Number: ‘integer’ and ‘float’
  • E.g.  -707, 0, 707 & 707.07, 0.7, 707.00
• String: text values
  • E.g. Marketing, Product, Research & Development, Sales

If you're using a Mac, try saving your file as MS-DOS Comma Separated (.csv). Go to File > Save As > Format.

Viewing your contacts

You can view a simple list of your contacts by clicking the “View list” button on the main Contacts page.

If you need to make adjustments to the contacts you have imported, upload a new CSV file (click on Reupload CSV) with your desired adjustments. You can also make changes to individual contacts in the contact list itself by scrolling to the right, clicking the menu icon that appears as three dots and selecting Edit.

Reuploading contacts and updates

If you need to update your contacts in ThoughtExchange, export a new CSV file with ALL your updated contacts and re-upload it using the same process as above. When you navigate back to the "Integrations > Contacts Upload" card, you'll see a "Reupload Contacts" button.

Important Considerations When Reuploading Contacts:

• Full List Required: When you reupload a new list, any contacts that are missing from the new file (compared to your previous upload) will be removed from ThoughtExchange. To ensure no contacts are lost, always upload the full list, not just new or updated rows.
• Column Names and Order: The column names and their order must remain the same when reuploading contacts. This ensures that contacts can still be added to existing engagements. If there are changes, an error message will appear:

"There has been a change to the columns in your list of contacts. Contacts can no longer be added to this engagement."

• Handling New Contacts:
  • If the Override option is selected when reuploading, new contacts must be manually added to the engagement through the Invite process.
  • If the Append option is selected, new contacts will be automatically added to the engagement.

Automatic Contact Syncing

ThoughtExchange now supports automatic contact syncing!

All you have to do is flip the switch to ON and link your HR system to the ThoughtExchange S3 folder using the information provided. Once you've set up the connection, click "Sync CSV" and map the data as normal. The list will sync daily at 9AM UTC.

Analyze Demographic Data in Results 

With the new Analyze Imported Demographic Data in Results feature, you can analyze, filter, share, and compare engagement results using the demographic data of participants imported from your Contact Upload. This allows you to reduce the number of questions in your survey while still gathering valuable demographic insights.

Step-by-Step Guide to Use This Feature:

1. Ensure Contacts are uploaded in the "Contacts" tab found in Admin Settings: 

   
   This feature requires the Contact Upload capability, which is part of the Engagement360 package. 

2. Run the engagement with Participant Invitations
a. When creating or editing an engagement, navigate to the Participants step.
b. Ensure the Participant Invitations toggle is set to ON.
c. For demographic data to appear in Results, you must launch your engagement using  Unique Links or Code Access

• For each engagement, select the appropriate contact list to ensure the right participants are invited.
• You can schedule overlapping survey windows for multiple engagements, using different contact lists without them interfering with each other.
   

3. Turn on Analyze demographic data in results

This option is 'OFF' by default. Turn this 'ON' to process and view participants' demographic data in Results.

Note: A warning will appear reminding you not to upload sensitive information, such as PII (except for first name, last name, email, or access code)

Analyze Demographic Data in Results

Demographic data is displayed in various formats :- 

• Bar charts on the survey analysis page

• Filters across all Results pages

• Comparison options, such as comparing theme ratings, satisfaction scores, and demographic group sizes

  

  
  Note: Only non-sensitive data (excluding first name, last name, email, or access code) is processed as survey data.

When comparing imported demographic data, a maximum of 50 columns or rows can be displayed. If you exceed this limit, you'll be prompted to reduce the selection.

Filter by contact data 

When unique links are used, any demographic data from the contact upload can be used as a filter in the Survey analysis and Advisor and Article pages of the Results Dashboard. This allows leaders to utilize information they already have about their participants without requiring each individual to answer questions about themselves that they have already answered in the past.

To maintain the integrity of your engagement filters, we make sure the list of invitees associated with each engagement is saved. This helps preserve your imported demographic filters over time, even if your contacts list is updated and overwritten, locking in your preferences so you always get the insights you need.