API Terms & Concepts

Account

Accounts in Totango represent any set of record about your customer.  This can be the representation of your Customer, a subsidiary of your customer, a product of yours that a customer purchased in some cases it can represent an opportunity or an asset, or any other object type that you care to model.  As Totango is schema-less we have virtual objects and thus any record in Totango can be any possible object, Totango Accounts can have many meanings depending on your companies modeling in Totango. 

For each Totango Account you MUST supply a unique ID,  this ID is used to aggregate data from your various sources including: CRM, data-warehouse or other systems.  Also you could create virtual IDs that you will derive on the fly if those ID's don't exist in your System.

As an example: You have a customer Acme INC, which has a subsidiary named Acme Boston, and Acme Boston purchased two of your products Widget 1 and Widget 2, also Acme INC itself purchased the Widget 1 product.  You only have identifiers for Acme INC which is XYZ and Acme Boston which is ABC.

Here is an example of identifiers that would be used to push information to Totango for all 5 of these entities. Keep in mind that all of these IDs are yours to manage, and no ID will be provided by Totango.

*These are Virtual Identifiers that don't exist, but are created on the fly by your own logic.

*Note that the _ is not a special character that is interpreted by Totango differently, it's simply a visual aid to assist in understanding the ID.

*The parentID must be explicitly defined, however not every call into Totango needs to include the parentID.  Most customers define parentID from a set of jobs outside the scope of the API.  Do not bring over the parentID unless explicitly intending to do so via API.

User
User in Totango represents YOUR end-users and/or your contacts. If you are sending usage data Totango keeps a track of all active users in an Account, measuring their engagement with your application and usage-frequency of key features.  Typically, an email address is used as user unique identifier (your internal user-id can also be used as an alternative).  Your API call is not required to define the user, it is optional, but if you do want to, a user/contact cannot exist in Totango without identifying the account they are associated to.  Additionally if you want to anonymize your usage but still record it as user usage you can send it for a fake ID.  IE: system_aggregated_user@domain.com

Account Attribute
Account attributes are extra pieces of information (it can be financial, contractual, or meta data ie: contract value, contract renewal date, licenses sold, address, phone) that can be associated with an account, and are later used in Totango for analysis and segmentation purposes. Most customers get this data from CRM, but it can come from any source, including API.

Totango has a number of special Named Attributes which carry special meaning. Usually most of them are sourced directly from your CRM platform, but they can also be updated via the API (either Javascript, HTTP or Data Hub API).

User Attribute
User attributes are like account attributes but used for users.

Module (nouns)
Think of Modules as nouns that describe simular actions. Modules are the main “areas” of your application, for example, if your app is an invoicing-application, it may have modules such as Invoicing, Billing or Reporting. You want Totango to know about the modules users visit, so you can later ask “which users didn’t use the Reporting module for over a month?”. 

Make sure you have a clear definition of which action  and modules to track from your business team. 

Totango supports up to 100 modules, but works best with 3 - 10 modules defined. 

User action (verbs)
Think of User Actions as verbs that describe some specific the user did.  A user action is something users do on your app. In an invoicing application, it could be when users “Send an invoice” or “Deletes bank profiles”. When a user does them, it tells you something about the value they are getting from your product. You want Totango to know about user actions, so you can later ask “which users didn’t Send an invoice in the last 30 days?”

Make sure you have a clear definition of which action and modules to track from your business team. 

Totango supports up to 500 user-actions, but works best with 20 - 100. 

Most customers implement a dynamic method to collect Actions/Modules ensuring that the high level elements are recorded, and not overburdening the CS team with the minutia of the users actions. As an example we want to know that a user opened a report, it is not valuable to know which report they opened, especially when you have 100s of reports. This level of detail is unnecessary.