Configuring Segment.com Connection

This article covers setting up an integration between Segment.com and Totango.  If you're looking for help using Segments within Totango, please head over to the Segments Overview.

Overview

Totango is built to accept multiple streams of data from many different sources.  It’s possible for customers to send their CRM data to Totango from a source like Salesforce or Hubspot, while opting to send usage data via a web request, javascript collector, CSV file, or a third party solution like Segment.

Segment is a leading customer data platform that allows businesses to send data to a single platform, sanitize, validate, and then forward that data to another platform in real time.  Some Totango customers might find value in using Segment to transmit usage data from directly within their application.  While it is possible to send all customer data, the push nature of the tool does not usually lend itself to capturing CRM data as data can only be added or updated when there is a transaction against a Source.

This guide will walk you through sending usage data via Segment. By the end, you should be able to configure your application as a Source, configure Totango as a Destination, and send usage data from within your app. I will provide code snippets in both Python and NodeJS, however you are not limited to these two environments.  Segment supports most programming languages and software stacks; please reference their documentation for more information on building an implementation that is compatible with your application stack.

If you already have an integration set up with Segment then you can skip the Source configuration, however please read the “Sending Data” section carefully as Totango has some specific data requirements to make the integration function properly.

 

Configuring a Segment Source

First you will need to configure your application Source within Segment.  If you have already done this step, feel free to skip to the next section.

To set up a Source within Segment, click on the Sources tab in the left menu and then click the Add Source button on the top right.

mceclip1.png

 

Search for the Source that matches the language your application is written in.  For this example, I will be setting up a NodeJS app.

mceclip2.png

 

Give the Source a name and click Add Source

mceclip3.png

Your Source is now configured in Segment and ready to receive data. Copy your Write Key somewhere as you will be using this later to send data from your application.

 

Configuring a Segment Destination

Before setting up the Totango Destination in Segment, you will first want to locate your Totango Service ID. You can locate your Totango Service ID by logging into Totango and clicking on the user profile in the top right.  Your Service ID is near the bottom of the dropdown and follows a format similar to SP-12345-01.  Take note of this ID, it will be used later in this section.

mceclip4.png

 

To set up a Totango Destination in Segment, navigate to the Destinations tab and click Add Destination in the upper right corner.

mceclip5.png

 

Next, search for and select Totango then click Configure Totango.

mceclip6.png

 

Select the data Source you configured earlier and click Next.

mceclip7.png

 

Name the Destination and, if prompted, select Fill in settings manually.

mceclip9.png

 

Click Region and select either US or EU then enter your Totango Service ID retrieved earlier into the Service ID field.

mceclip10.png

 

Important: Remember to enable the connection by clicking on the switch next to the Destination’s name.

mceclip11.png

 

Sending Data to Totango via Segment

To finalize this integration, you will need to add some telemetry code to your application.  I will provide two identical examples to integrate - one using NodeJS and the other using Python. You are free to set this up in whatever language/environment your application uses.  See Segment’s Documentation for examples using other languages.

These samples were built using the following language/library versions:

node 17.6.9
analytics-node 6.0.0

python 3.9.10
analytics-python 1.4.0

 

Dependencies

Start by including the Segment libraries in your application.

NodeJS

npm install --save analytics-node

Python

pip install analytics-python

 

Within your application, include and instantiate the Segment library. Replace the Hashed (######) string with the Write Key supplied by Segment for your Source.

NodeJS

var Analytics = require('analytics-node');
var analytics = new Analytics('##############');

Python

import analytics    
analytics.write_key = '###########'

 

Users

Segment tracks users using the Identify function.  At a minimum, this function should include the following data to ensure data flows properly into Totango:

  • User ID - This data should match the User ID used to identify the user in Totango - often times this is the user’s email address or the Salesforce contact id.
  • Name - The first and last name of the user.
  • Email - The user’s email address
  • Group ID - The Totango Account ID that the user belongs to.  This field must match the Account ID used in Totango.

NodeJS

analytics.identify({
 userId: 'Batman', 
 traits: {
   name: 'Bruce Wayne',
   email: 'bwayne@gotham.city'
 },
 context: {
   groupId: 'WayneEnt'
 }
});

Python

analytics.identify(
   'Batman',
   {
       'name': 'Bruce Wayne',
       'email': 'bwayne@gotham.city'
   },
   {
       'groupId': 'WayneEnt'
   }
)

 

Accounts (Groups)

Groups within Segment are analogous to Accounts in Totango.  The Group function is also used to add users to groups (customers to accounts).

  • User ID - This data should match the User ID used to identify the user in Totango - often times this is the user’s email address or the Salesforce contact id.
  • Group ID - The Totango Account ID that the user belongs to.  This field must match the Account ID used in Totango.
  • Name - The full name of the account.

NodeJS

analytics.group({
 userId: 'Batman',
 groupId: 'WayneEnt',
 traits: {
   name: 'Wayne Enterprises'
 }
});

Python

analytics.group(
   'Batman',
   'WayneEnt',
   {
       'name': 'Wayne Enterprises'
   }
)

 

Usage Data

Now that Users and Accounts are defined, you can generate a tracking request and start populating usage data.  Segment offers several different types of events; for this example, let’s focus on the Track event which most closely represents a standard piece of usage data.

  • User ID - This data should match the User ID used to identify the user in Totango - often times this is the user’s email address or the Salesforce contact id.
  • Event - The Activity performed by the user.
  • Category - The Module where the user performed the action.
  • Group ID - The Totango Account ID that the user belongs to.  This field must match the Account ID used in Totango.

NodeJS

analytics.track({
 userId: 'Batman',
 event: 'Viewed',
 properties: {
   category: 'PoliceReport'
 },
 context: {
   groupId: 'WayneEnt'
 }
});

Python

analytics.track(
   'Batman', 
   'Viewed',
   {
       'category': 'PoliceReport'
   },
   {
       'groupId': 'WayneEnt'
   }
)

 

More Resources

For more information on Segment’s data types and guides to set up other languages head over to their documentation.

Attached to this article are the full code samples for both Python and NodeJS.

 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request