Overview 

In addition to creating a  real-time data feed into Totango from your application and CRM, another common way to upload data into Totango is using CSV files.

You can upload Accounts, Users, Collections, or Usage file integration types using CSV files and use the Totango Customer Data Hub to feed that information into Totango - either as a one-time operation or by instructing Totango to pull files (using SFTP, S3, Dropbox or others) in a recurring pre-defined schedule.

This article includes the following topics:

• How to create CSV files
• Account Information File 
• User Information File
• Collection Information File
• Usage Information File
• Totango User Information File
• Account Assignment Information File
• Tasks information file
• Touchpoints information file
• Important CSV Format Requirements
• Default Value Assignment
• FAQs

 Related articles:

• CSV file best practice and FAQ
• Uploading Data Files Using Customer Data Hub
• How to Configure a Customer Data Hub Connection
• Managing Account and User Tags Using CSV
• Uploading Aggregated Usage Data
• Schedule Data File Uploads
• Using an API Endpoint to Trigger File Uploads

How To Create CSV Files

Account Information File

To upload account data into Totango use the following format, typically sourced from a report from your CRM, data warehouse, or other sources. 

A common use-case is when you first set up your Totango and want to add all your existing customer accounts into Totango to create an appropriate portfolio, analyze customer information, create customer-driven automation or review the holistic customer picture in the Account Profile.

The CSV file format should be (sample account file is attached at the end of the article):

Account Id, Account Name, [ Account-Attribute-1, Account-Attribute-2, ... ]

Where:

• Account Id (mandatory)- represents the internal shared account Id you use to cross-reference accounts in Totango, your application, your CRM, and data warehouse (where applicable).
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• Account name is the name of the customer which will be used as a display name for this customer across all Totango products.
• parent_id - In order to create account hierarchy, you will need to map child accounts to their parent account. In a file containing child accounts, map a column with the account id of the parent account to the system attribute 'parent_id'
• Account-Attribute-N - List of attributes you want to update for every account (if any). These attributes can already exist in Totango or created dynamically by the integration.
  These attributes format can be Text, Number, Date, List, or Currency.

User Information File

You can upload information on an individual user or contact to Totango using a CSV file. This information will be used for Totango Campaigns module and be presented in the user profile.

A common use-case is when you first set up your Totango and want to add all your existing customer users or customer contacts in order to engage directly with the right contact, analyze user information, create user-driven campaigns or review the user information in a user profile.

The CSV file format should be (sample user file is attached at the end of the article):

User Id, Account Id, User-Attribute-1, User-Attribute-2, ... 

• User Id (mandatory)- The user's email (or another unique user identifier in Totango)
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• Account Id (mandatory)- Represents the internal shared account Id you use to cross-reference accounts in Totango
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• User-Attribute-N: List of attributes you want to update for every user (if any).
  These attributes can already exist in Totango or created dynamically by the integration.
  These attributes format can be Text, Number, Date.

Collection Information File

A Collection is a read-only object which stores transactional information. The collection is part of the customer data model and uses for exposing actionable information in the account profile which complete the holistic customer picture. Read more about collections here.

A common use case is upload opportunities, orders, feature requests, and sales handover details as a collection to let users better understand the latest status of the customer.

The CSV file format should be (sample collection file is attached at the end of the article):

Collection Id, Account Id, Collection-Attribute-1, Collection-Attribute-2, ... 

• Collection Id (mandatory)- A unique identifier of the collection. It is usually the external system id for this object.
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• Account id (mandatory)- Represents the internal shared account Id you use to cross-reference accounts in Totango.
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• Collection-Attribute-N: List of attributes you want to update for every collection.
  These attributes can already exist in Totango or created dynamically by the integration.
  These attributes format can be Text, Number, Date, Currency.

Usage Information File

You can upload usage information on users or accounts in two formats: activity stream and aggregated usage. The usage information will be used for understanding the user and customer behavior in your application to understand and verify its common use of your application, and find usage anomalies to trigger actions like training activities, risk alerts, upsell opportunities, and more,...

Activity stream file format

An activity stream is usually used to send usage information to Totango as captured on your application, or from a 3rd party usage behavioral tools (like Google Analytics, Mixpanel,...)

The CSV file format should be (sample activity stream file is attached at the end of the article):

User id, Account id, Module, Action, Count

• User id (mandatory)- The user's email (or another unique user identifier in Totango)
• Account id (mandatory)- Represents the internal shared account Id you use to cross-reference accounts in Totango).
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• Action (mandatory): Name of the activity the user performed. The value must be a text.
• Module (mandatory): Name of the module the user performed. The value must be a text.
• Count (optional): Number of times the aciton/module happened. The value must be numeric, if no count is provided it will be counted as 1 time.

Aggregated Usage File Format

Aggregated usage is usually used to send usage information to Totango as stored in a relational data store, usually your company data warehouse.

The CSV file format should be (sample aggregated usage is attached at the end of the article):

Account Id, Daily active users, Daily total activities, Daily time spent in minutes, [ Aggregated-Usage-Attribute-1, Aggregated-Usage-Attribute-2, ... ]

Where:

• Account Id (mandatory)- represents the internal shared account Id you use to cross-reference accounts in Totango,
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• User Id (mandatory)- The user's email (or another unique user identifier in Totango)
  This is an optional column. In case there is no user id the information will be stored on a “dummy” user within the account id specified.
  Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• Aggregated-Usage-Attribute-N: List of modules and actions information you want to update for every account.
• The aggregated usage columns in the file should use this preserve format <Module>##<action>, for example, “Reports##View Report”.
• The column value is the number of actions done.
• These modules and actions can already exist in Totango or created dynamically by the integration.
• This column data format is numeric.
• Preserved column names can be used for uploading usage metrics.
  Daily active users, Daily total activities, Daily time spent in minutes.
  Read more about aggregated usage uploads here.
  
  

Totango User Information File

You can upload information on a Totango user (which are system users of Totango) to Totango using a CSV file.

A common use-case is when I am defining Totango users, and I want to initially upload Totango system users, I am able to create and maintain system users by uploading a CSV file from Totango Users page.
Read more about the Totango Users integration here. 

The CSV file format should be :

User Email, First Name, Last Name, License, [Totango-User-Attribute-1,Totango-User-Attribute-2, ... ]

• The CSV file must contain this information:
  • User Email (mandatory)- system user email. This is the system user id key in Totango.
    
  • Note: Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and dot “.”).
  • First Name (mandatory) - the system user first name. This is mandatory only for new Totango users
  • Last Name (mandatory)- the system user last name. This is mandatory only for new Totango users
  • License (mandatory)- the system user license (Spark or Zoe). This is mandatory only for new Totango users
    
  • Manager_id - mandatory only if you are using Manager Based SuccesTeam Assignment, then you will need a column that includes the manager's email address and it should map to Manager_id.
  • The file can contain any additional Totango user information.
    
    

Account Assignment Information File

To upload mass account assignments into Totango, use the following format, typically sourced from your CRM, data warehouse, or other sources. 

Please note, the same data can be uploaded using the Account Information file but in a different format.

The CSV file format should be (sample account assignment file is attached at the end of the article):

Account Id, Account Role ID, User Email, [User Name]

Where:

• Account Id (mandatory)- represents the internal shared account Id you use to cross-reference accounts in Totango, your application, your CRM, and data warehouse (where applicable).
  Note, Totango only accepts alpha-numeric Ids without special characters (except underscore “_” and minus “-”).
• Account Role ID (mandatory)- the account assignment role id which is configured in the "Account Assignment" page under Global Settings > User Management.
  Note, use the account role id as a column value and not the account role display name.  
• User email (mandatory)- the account role user email.
• User Name - It is very common that the account role user is a Totango user. In these cases, the account user display name will be the Totango user name. In case the account role user is not a Totango user, the account role user name will be the one uploaded in this column.

Tasks Information File

To upload tasks into Totango, use the following format, typically sourced from your CRM, data warehouse, or other sources. 
The CSV file format should be (sample account assignment file is attached at the end of the article):

Task ID, Account_ID, Title, Description, SuccessFlow, Priority, Status, Estimated Task Effort, Actual Task Effort, Assigner,Assigned_To, Create_Date, Due Date, Last Update Date, Associated Users

Where: Task ID, Account_ID, (Title or Description) are mandatory

Touchpoints Information File

To upload touchpoints into Totango, use the following format, typically sourced from your CRM, data warehouse, or other sources. 
The CSV file format should be (sample account assignment file is attached at the end of the article):

touchpoint_id, account_Id, Subject, Content, Successflow, Touchpoint Type, Touchpoint Tags, Participants, Touchpoint Date, Last Update Date, Last Updater

Where: touchpoint_id, account_Id, (Subject or Content) are mandatory

Important CSV format requirements

Please make sure the CSV complies with the following formatting requirements:

• The first row in the CSV file should be the header row containing the name of the attributes, followed by the actual data.
• The CSV file should contain one row of data per each object (for example in an account data file, each row should contain information for a single account).
  In case of duplications, the file will not pass the validation. On a recurring upload, when duplication occurs only the last row of this account will be uploaded and stored in Totango.
• Account ID column cannot have blanks or special characters other than underscores (“_” ), minus (“-”).
• Date type columns must comply with ISO 8601. For example 2019-09-17T08:00:00.0Z or 2019-09-17T00:00:00-08:00 in case the time zone is -0800.
• Be advised that unless timezone was added to the date format, all date attributes are considered to be in UTC format and are automatically converted to the service’s timezone on display.
• Numeric and Currency types should not contain comma-separated (i.e., -1000.50 or 1234).
• An empty value in a row will generate the default value behavior for this attribute. Default value behavior can be configured in the Data Modeler page.
• In case a column contains special characters such (a comma, a semicolon, apostrophe, or a newline), the field needs to be encapsulated with double quotes ("). For example,  john,doe must be represented as "john,doe".
• In a case of columns containing text with Unicode characters, encapsulation with double quotes is not required.
• A column text value must not contain quotes.
• Make sure there is no system log information generated at the end of your CSV file.  (usually occurs when extracted from CRM or any report generator systems).
  Note, if your information is extracted from Salesforce, there is generated information section at the end of the file.

CSV File Structure Limitations

• There is no file size limitation for recurring uploads.
• Due to browser limitations, a file uploaded from your local computer cannot exceed 100MB.
• A CSV file cannot contain more than 1,000 columns.

Default Value Assignment

Totango enables bulk deletion or assignment of default values of account attributes using the Customer Data Hub. To trigger the default value mechanism for an attribute simply define an empty cell in the relevant intersection.

You can define the behavior of the default value per each account attribute. These are the default value options:

• Delete the value
• Keep the previous value
• Set it up to a specific value
• Set the value to today (in case of a date)

Note, you can not configure the default value behavior of a user attribute, user attribute default value behaviour is "delete", it means that if the value is uploaded empty it will be deleted for this user.

Important note

Note that the default value functionality can cause data irregularities if the CSV file creation is automated and does not properly handle missing data.

In such cases, an attribute can disappear when an empty cell is provided and will reappear when data becomes available. If the attribute is used for custom metrics, health or other segmentations, data might fluctuate and might seem incorrect.

We highly recommend handling cases where no value exists by setting up a default value according to your business logic case if you do not wish to delete the attribute.

Read more about attribute default values and the system defaults per attribute type.

FAQs

Q: The file I uploaded contains duplicate account ids, will the data be uploaded to Totango?
A: Only the data of the last record of this account will be stored, in case there is a need to upload all the duplicated rows, you can aggregate it yourself in the file, or split it into several files.

Q: What happens if an attribute used in integration is deleted from the data model?
A: You cannot delete an attribute which is mapped in an IHDF recurring job. You will be able to delete an attribute which was in use in a one-time upload.

Q: What happens if the file in the data source was not updated? Will it upload it again?
A: The IH data files skip the file in case it is the same file from the last successful upload. The file integration run will be “skipped” and mark in red as it is a failure.