Planhat's Segment integration enables you to both send usage data to Planhat and push back customer-related data including revenue data to Segment's data warehouse. In Planhat you can leverage the usage data in health scores, create proactive alerts when usage level changes and much more.

Below we will walk you through how the integration works and how you can set it up.

Summary

The integration should be set up by a Segment admin
Data can be associated with an enduser, a company or any of our custom objects (e.g. assets and projects)
The usage data is designed to track trends and does not update object’s fields
Data is synced based on Planhat's objects associated external id and /or email
It is possible to let segment data create endusers, if matching endusers don’t already exist in Planhat
Three types of calls are possible, “Group” is only associated with a company, whereas “Identify” and “Track” are associated with endusers, company and potentially a custom object e.g. Asset or Project
The integration has three sections described below. You may choose to enable one or more
The integration will be marked as OFF in Planhat's user interface unless section 3 is enabled

1. Segment User Tracking - Enables integration to receive user activities

Before we dive into the steps, let me share some context to how the two types of calls work. The Identify call is used to provide user details so Planhat can match the Track events to the correct enduser or create them if these do not exist yet. The required attributes are:

company_id: this refers to the unique account Id that the user belongs to, usually stored in your database. In Planhat this ID is mapped to the company field externalId.
user_id: this refers to the unique user identifier in your system. In Planhat you'll find it in the enduser field externalId.
email: the email address is required if the user_id is not provided.

If any of the user attributes can be found in Planhat the events are then matched to the corresponding enduser. Otherwise, and as long as the company_Id is available in the event, Planhat will create a new enduser (the global setting covering this is enabled by default).

An example identify event:

{
    "messageId": "1234ABC",
    "type": "identify",
    "timestamp": "2022-11-28T23:48:23.813Z",
    "email": "elon@spaceX.com",
    "traits": {
      "Name": "Elon Musk",
      "company_id": "123spacex"
},
    "user_Id": "test-user-23z7oi"
}

An example track event (to the company object):

{
    "messageId": "1234ABC",
    "type": "track",
    "timestamp": "2022-11-28T23:48:23.813Z",
    "user_Id": "test-user-23z7oi",
    "event": "big rocket"
}

Another example track event (to the Asset object):

{
    "messageId": "1234ABC",
    "type": "track",
    "timestamp": "2022-11-28T23:48:23.813Z",
    "email": "elon@spaceX.com",
    "event": "big rocket",
    "properties": {
          "assetExtId": "Mars"
    }
}

As this track event suggests, to send events from Segment to Planhat objects other than Company, simply include the relevant ExternalId in the "properties" expression.

📣 Pro tip: There are cases where we do not require identify calls to receive Segment activities. For example, if the company externalId and email are part of the "track" event then we can still map the data without an associated identify call.

📌 Important to note: Planhat will drop the request without an error if you don't provide a company_Id matching the companyExternalId in Planhat along with the track request, and a matching user_Id (that cannot be found in Planhat within the enduser externalId).

Now that we have a better understanding of the calls, let's set up this section by following the steps below

Log into Segment and navigate to the Destination setup
Log into Planhat - Hover over your avatar in the bottom left corner, go to "Integrations" and click on "Segment"
Copy over the Subdomain and Tenant Token (see print screen below) from Planhat to segment

2. Enables the integration to map Group calls to Company Metrics

This section describes how you can track company metrics fetched from Group segment events. If you would like to know more about this type of Segment call then check out this article 👍.

By default, the integration is expecting:

group_Id: this should match to a company externalId saved in Planhat.
traits.xyz: where xyz is the name of the attribute that contains a numerical value.

An example group event sent from Segment:

The numerical values passed in the traits object will be synced to Planhat as Company Metrics as long as you pre-define them on the integration page (see below).

📌 Important to note: when adding a new Company Metric you need to press "Enter" and then press the "Save" button. Once you have added the Metric, you can send data to test it. As soon as you start generating Group calls the events will be displayed as Company Metrics in Planhat on the Customer Intelligence module (Trends & Analytics).

3. Segment Data Warehouse - Enables integration to push data from Planhat to Segment

Customers on our Enterprise plan can sync Planhat data to Segment and further on to Amazon Redshift, Google BigQuery, etc. if the Segment Data Warehouse feature is activated. We sync data from Planhat to Segment 3x a day but if you need to, you can use the "Push data to Segment" button to manually sync your data.

📣 Get started: if you would like to get set-up and start using the "Segment Data Warehouse" then check out this article 👍.

The Segment integration also tells you when the last sync occurred and how long the sync took to run. Below that you will see 3 columns:

Model: these are the data objects in Planhat that are syncing to Segment
Objects Synced: the total count of objects that have synced from Planhat to Segment
Errors: a count of errors that occurred in the sync

For more information about section 3 please read this article.

4. Troubleshooting notes

If the "Push data to Segment" button in Planhat is greyed out, it either means:
- The "Active" flag just above is not enabled
- There is an active job running (note: if there have been several hours/days and it's still grey, it likely means something has stuck. Please contact Support with a clear description of the situation, in that case)