Planhat's unidirectional integration with Pendo allows you to pull all your customer's usage data into Planhat, for all your apps, all at once. By following these setup steps, you'll ensure that your Pendo data flows exactly where you want it to go in Planhat.
Contents
This is Part 1 of our 2-part Pendo Guide. In this set-up guide we'll cover:
To find out how to map metrics to Planhat once your integration is set up, check out Part 2: Mapping Data with the v2 Pendo Integration.
Let's get your integration up and running!
What Pendo V2 Supports
Data Types
The Planhat integration supports syncing of all 3 forms of Pendo data to Planhat:
Aggregations: (multiple) streams of aggregated event data, summarised in a single JSON pipeline
Additionally, the integration supports Pendo's much loved PES:
Product Engagement Score (PES): a stream of aggregated event data representing the combined impact of i) feature adoption, ii) return user stickiness, and iii) new user growth. You are able to map the PES itself, in addition to any of its three components, to individual metrics in Planhat.
📌 Note: you'll only be able to map PES if your Company ExternalId in Planhat is set to match the Pendo accountId (which is the default), and not another custom ID field in Pendo.
Multiple Applications
Planhat's integration also supports Pendo's multiple application (Multi-App) configurations. Any Report or Aggregation relating to multiple apps can be synced simultaneously to multiple metrics in Planhat, each containing data only for the related app.
When Multi-app is toggled in a mapping, Planhat will automatically name each metric as follows "App Name - Metric Name".
📌 Note: the integration does not support Multi-App functionality for the PES score, so you'll need to map the PES to Planhat for each app individually - the configurator will guide you.
End User Creation
The integration can create end users in Planhat for any User Activity mapped to any object. Simply toggle the global "Auto-detect new end users?" setting ON from Admin Settings, and whenever an end user is detected from Pendo but not found in Planhat (a visitor is found in Pendo which cannot be matched to an existing End User in Planhat via the ExternalId field, or the email field, if configured), they will be created automatically. All that is necessary is to have an External ID/email domain match for the parent entity (Company/Asset/Project).
📌 Note: if an End User match exists, the corresponding data will be applied to the existing End User. This includes both usage data and additional user metadata (Name, Email) which will be added to the existing user if needed.
Passive Events
The Passive? toggle on User Activity mappings will determine whether events are brought in actively or passively. Passive events will not:
impact contact/user last seen/active dates (they will not show in system metrics like "Users Active Last 7 Days"), Beat & Experience
show in the Company Profile “Overview” tab under “Recently Active”
However, they will still show in “Recent Activities” both in the Company Profile “Usage” tab and the End User Profile “Overview” tab.
End User Updating
In Planhat, the End User Name and Surname fields will be updated by the Pendo integration, as long as:
the "End User Name" and "End User Surname" fields are being mapped from Pendo to Planhat
the End User is matched successfully between Pendo and Planhat (either on End User
ExternalIdorEmail, in addition to CompanyExternalId)the End User has a value for the corresponding (Name or Surname) field in Pendo, but not in Planhat
The End User Email field will also be updated by the Pendo integration when populated in Pendo but not in Planhat, with the additional conditions that:
the "End User Email" field is mapped from Pendo to Planhat
"Auto-create users?" is toggled on for the specific metric (which also requires the Pendo
accountId- or the equivalent Company ID field - to be populated, and the Company with that ID as itsExternalIdto exist in Planhat)
📌 Note: if the Name, Surname or Email fields are already populated in Planhat, they will never be overwritten by the values in Pendo.
Should you want these values to be overwritten by Pendo, you should delete the Name, Surname and/or Email of the end user(s) in Planhat and perform a sync (click the blue "Sync now" icon) of the relevant metrics in the Pendo integration with "Auto-create users?" toggled on (which also requires the Pendo accountId - or the equivalent Company ID field - to be populated, and the Company with that ID as its External Id to exist in Planhat).
Important to Know
Planhat syncs data from Pendo on a daily basis. If you wish to sync data outside of the scheduled daily sync, you can click "Sync" to update any individual mapping, or "Re-sync all" if you wish all mappings to be rebuilt from scratch. We caution against "Re-sync all" use, since:
the process can be data-intensive and slow the application
it will erase all current data mapped into Planhat from Pendo, and rebuild all metrics with however many days history you specified in the "Days to Sync" parameter
Historical Data
When synced fully, the integration will bring Pendo data in anywhere between 1 and 365 days in the past into Planhat, not the full data history: simply choose how far back to sync in the left sidepanel.
End User Email
Email will only be used to match and create End Users for a given metric if:
the "End User Email" field is mapped in the configurator panel
the Pendo
accountId- or the equivalent Company ID field is populated"Auto-create users?" is toggled on for that specific metric (and the Company with that ID as its
ExternalIdin Planhat actually exists)
Auto-Creation of Users
End User auto-creation requires the Pendo
accountId- or the equivalent Company ID field to be populated in Pendo, regardless of whether End Users are being mapped usingvisitorId- or the equivalent End User ID field - orEmail.
Reports
Certain types of reports are incompatible with the integration, and therefore will not be shown in the list of report options. Types of incompatible reports include:
reports with a fixed date range (rather than a time window)
reports with no numerical columns (since these are necessary for metrics)
Any non-numerical columns of a compatible report (a report with at least one mappable numeric column) will not show as available mappings when the report is loaded
We actively discourage reports with a time window greater than 30 days, since data volumes can be extremely high, resulting in slow syncing. However, the only hard limit is 180 days: any reports of more than 180 days will not show up in the Planhat configurator.
Re-sync all
Some actions will require a manual full metric re-sync, via the
Re-sync allbutton. We don't perform this sync automatically, as not to disturb the ongoing daily data sync, but recommend doing so to ensure correct metric mapping.These actions are:
Adding, Removing, or Editing App mappings in the "Apps" tab of the configurator
Changing any settings in the configuration panel (after clicking "Update")
So if your mapping is correct, but you're not seeing the data you expect, there should be no need for a Re-sync all: you should simply click "Sync now" on the specific metrics to pull any updates.
❗Careful: performing a re-sync will also remove all historical metric data from Planhat. While it will sync Pendo data from the past 1-365 days (depending on how you have configured "Days to Sync" in the sidepanel), any values stored in the metric from more than this number of days ago will be deleted permanently
🔄 Syncing: Re-sync all will permanently delete all metrics created by the integration, reset the mappings to pull data from your "Days to Sync" days ago, and fetch new data. This means you will end up with all the metrics you have mapped, but with only 1-365 days of historical data. Sync now will simply fetch the latest updates to a specific mapping. It does not delete any data, but if the configuration has been updated, it will not build to the new configuration, which is why any configuration updates require a Re-sync all.
Preparation Steps
To ensure the smoothest and most effective integration between Pendo and Planhat, we recommend three preparation steps before you activate the connection:
If you've already optimised your reports for efficiency, got your aggregation JSONs to hand, and created your Integration Key, feel free to skip directly to setting up the integration.
1. Setting Up Reports
Reports are the most common way to structure data in Pendo, because they allow you to quickly summarise multiple Features and Pages, covering multiple apps. For this reason, they're also the most user-friendly and efficient way of syncing data relating to multiple features, pages and applications into Planhat. But if you don't need to map reports to Planhat, feel free to skip ahead and create your integration key.
Reports can bring a lot of data into Planhat all at once and, for that reason, there are some best practices around how your reports should be prepared before syncing with Planhat:
only the columns you need: if you have a report containing some metrics you want to bring into Planhat, make sure it doesn't also have lots of columns you're not interested in mapping to Planhat, since redundant columns will just slow down the overall sync. Instead, build a new report with just the columns you need.
more columns, fewer reports: it's most data-efficient for us to sync the fewest reports possible, with as many columns as you need, rather than many reports with just a few columns each.
smaller time windows: unless absolutely necessary, try to keep the time window for your reports below 30 days. We impose a hard cap on reports any longer than 180 days.
2. Defining Your Aggregations
As mentioned above, Pendo aggregations are more technical user-defined JSON pipelines which follow a very specific structure. If you don't need to map aggregations to Planhat, feel free to skip ahead and create your integration key.
If you've already defined the aggregation pipelines you want to bring into Planhat, make sure you have them to hand for the aggregation mapping step, in Part 2
If you haven't defined your aggregations yet, but would like to bring aggregations into Planhat, we recommend reading Pendo's introduction to aggregations here.
Additionally, here's our own example of what an entire request to Pendo's aggregation endpoint might look like:
{
"response": {
"mimeType": "application/json"
},
"request": {
"pipeline": [
{
"source": {
"timeSeries": {
"first": "now()",
"count": 1,
"period": "dayRange"
},
"pageEvents": {
"pageId": "zJ-O9iMQAt5ecY5Ylg-iFuNSZes"
}
}
},
{
"bulkExpand": {
"account": {
"account": "accountId"
}
}
},
{
"bulkExpand": {
"visitor": {
"visitor": "visitorId"
}
}
},
{
"group": {
"group": [
"visitorId"
],
"fields": {
"numEvents": {
"sum": "numEvents"
},
"accountId": {
"first": "accountId"
},
"visitorId": {
"first": "visitorId"
},
"appId": {
"first": "appId"
}
}
}
},
{
"select": {
"accountId": "accountId",
"metric1": "numEvents",
"metric2": "numEvents",
"appId": "appId",
"visitorId": "visitorId"
}
}
]
}
}
And, more specifically, here's how a pipeline for creating a custom aggregation in Planhat should look:
[
{
"source": {
"timeSeries": {
"first": "now()",
"count": 1,
"period": "dayRange"
},
"pageEvents": {
"pageId": "zJ-O9iMQAt5ecY5Ylg-iFuNSZes"
}
}
},
{
"bulkExpand": {
"account": {
"account": "accountId"
}
}
},
{
"bulkExpand": {
"visitor": {
"visitor": "visitorId"
}
}
},
{
"group": {
"group": [
"visitorId"
],
"fields": {
"numEvents": {
"sum": "numEvents"
},
"accountId": {
"first": "accountId"
},
"visitorId": {
"first": "visitorId"
},
"appId": {
"first": "appId"
}
}
}
},
{
"select": {
"accountId": "accountId",
"metric1": "numEvents",
"metric2": "numEvents",
"appId": "appId",
"visitorId": "visitorId"
}
}
]
3. Creating Your Integration (API) Key
To setup the Pendo integration, you'll need a unique Pendo "Integration Key". A Pendo Admin can create and manage your active Integration Keys here.
To create an Integration Key:
Login to the Pendo Application as an Admin user
Visit the Integrations section in the Pendo App, and then click on the Integration Keys tab
Click on the Add Integration Key button at the top right-hand side of the screen.
Give your new key an appropriate description, such as "Planhat Integration Key".
The box marked Allow Write Access does not need to be ticked
Click on Create to finish
You'll soon copy this API key directly into Planhat's Pendo integration. For now, copy it somewhere private and secure for future reference.
Setting Up the Integration
Now you've gone through the preparation steps and have both your Integration (API) Key and any necessary aggregation JSON pipelines close by, it's time to get set up.
1. Go to the Integration Configurator
Navigate to the Operations Module on the left navigation Bar > Integrate
From the integrations menu, scroll down and select "Pendo v2"
2. Paste your Integration Key (API Key) into the field on the top left panel, and select your API Domain
Copy your API key directly from Pendo's
Integrations>Integration Keyspage and paste it into the "API Key" field on the left panel of the integration menu in Planhat
Select your API domain:
if you have a European Pendo instance, choose the first domain (app.eu.pendo.io)
if you're using Pendo from anywhere else, choose the second domain (app.pendo.io)
If you're not sure, just switch to Pendo and check which option your browser URL matches.
Now both these fields are populated, scroll down past the Field Mapping section and click "Create"
When you click, you'll see the integration perform some checks, and if your API Key and API Domain are valid, the connection will come alive! As shown below:
"Connection is active" will appear in green on the left panel
"Map Custom ID Fields to Planhat" will be populated with defaults
You'll now be able to click everything on both the left panel and the main "Mapping" and "Apps" pages
3. (Optional - with your TAM) Choose how many days back to sync ("Days to Sync")
This setting will be greyed out, showing 90 days by default. If you would like to adjust the "Days to Sunc" from this 90 day default, speak to your TAM.
When you "Re-sync all", the integration will fetch historical data from Pendo only for a specific period of time. By default, this "Days to Sync" is 90 days, but in special cases, your TAM can configure it anywhere from 1 to 365 days.
Every time you click "Re-sync all", the integration will erase all mapped metric data, and re-fetch data for all mapped metrics for the period you specify in the "Days to Sync" setting. This can be modified later, but you will need to "Re-sync all" when modifying the setting, losing any data logged in Planhat outside of the "Days to Sync" period
4. Check the required field mappings on the left panel
By default, the connection can only map to the Company object, and can only ingest users based on their
ExternalId. To enable mapping to Assets and/or Projects, and enable ingesting users via email, we need to set the corresponding ID fields.
Since the Planhat Company and End User
ExternalIdare mapped by default toaccountIdandvisitorIdfields in Pendo, you will need to ensure that:either all Companies have the Pendo
accountIdas theirExternalIdfield and all End Users have the PendovisitorIdas theirExternal Idfieldor that the
External Idof all Companies and End Users in Planhat is set to the same values as in the fields chosen to populate the configurator's "Company External ID" and "End User External ID" fields (which you should do in the rare case that you have custom ID fields set up in Pendo), respectivelyhowever, if you wish to map End Users via Email only, then the End User
External Idcan be cleared: to do so, the email mapping on the left panel must be complete, all End Users must have a value in the correspondingemailfield, and then the End UserExternalIdcan be cleared (set to "-")
📌 Note: if the Pendo field mapping to the Company ExternalId in Planhat is not accountId, you will be unable to map PES or its components to Planhat.
5. (Optional) Complete the field mappings on the left panel
Assets and Projects
If you would like to map data from Pendo to Planhat's Asset and Project objects, as well as Companies and End Users, you will also need to select the field in Pendo which contains a unique asset identifier and/or the field that contains a unique Project identifier (both of which must match the
ExternalIdof the Asset/Project object(s) in Planhat)
It's common to use the Pendo accountId field to map to the Asset and Project External Id fields in Planhat, as shown above.
End Users: Name and Surname Metadata
If you want to use Pendo to input End User's Names and Surnames - both for new and Existing End Users, simply populate the "End User Name" and "End User Surname" fields in the left panel with the names of the fields containing these values in Pendo. As mentioned above...
The End User Name and Surname fields will be updated by the Pendo integration, as long as:
the "End User Name" and "End User Surname" fields are being mapped from Pendo to Planhat
the End User is matched successfully between Pendo and Planhat (either on End User
ExternalIdorEmail, in addition to CompanyExternalId)the End User has a value for the corresponding (Name or Surname) field in Pendo, but not in Planhat
End Users: Mapping with Email
If you would like to be able to map End Users using their email as a unique identifier, rather than their Pendo
visitorId(or the equivalent End User ID field in Pendo), you should populate the "End User Email" field with the name of the field in Pendo containing the end user's email address, and clear the End User External ID mapping field to "-".
📌 Note: the if the "End User Email" field is populated, the End User mapping will always try to map End Users using Email before Planhat's End User ExternalId field (discussed above). However, if for any reason there is no value for the Pendo Email field, the integration will use the field value corresponding to the End User ExternalId.
Creating End Users
If for any reason, neither the Pendo End User (visitor) email field nor the Pendo End User (visitor) ID field matches the Email or ExternalId fields of any Planhat End User, the integration can create a new End User with these values.
If you would like these End Users to be created in Planhat when they are discovered in Pendo, the global Admin Setting to auto-detect new users must be toggled ON.
This will then populate both the Email and ExternalId fields for that End User in Planhat, as well as Name and Surname (if these mappings are populated with the corresponding Pendo fields).
📌 Note: End Users can only be created automatically if the Pendo accountId or equivalent Company ID field is populated and a Company with that value as its ExternalId actually exists in Planhat. If no mappable End User exists in Planhat (no match on either End User ID or Email) and they have no mappable Company ID in Pendo, the End User cannot be created (End Users must always be related to a Company) and all data relating to them will not be synced to Planhat.
6. When all mappings in the left panel are accurate, click Update
📌 Note: if at any time you wish to modify the configurator settings, don't forget to click "Update", and then remember to perform a full re-sync via the green "Re-sync all" button. This will ensure your current mappings are updated in line with your changes, but will also permanently delete any data already mapped to Planhat from more than your "Days to Sync" days ago.
7. (Optional) Multi-App Set Up
If you have data on multiple apps in Pendo, you may wish to map their data to Planhat separately. Inputting your Pendo appIds in the "Apps" tab of the configurator will ensure that, when you toggle "Multi-app" ON for a given metric mapping, Planhat will actually build one metric per app, with that app's name as a "Metric Prefix".
For example, a metric “Click Events”, relating to both your “Cloud Store” and “Partner Portal” Apps, will be built simultaneously in Planhat as “Cloud Store - Click Events”, and “Partner Portal - Click Events” when Multi-App is selected.
If you would like to map multiple apps separately, you should:
go into Planhat's integration configurator, click the "Apps" tab, next to the default "Mapping" tab.
In this tab, you'll see that the table is pre-populated with 2 unremovable default values:
-323232andunknown. Since the first app associated with your Pendo subscription will always have the appId value-323232, you can navigate to the domainhttps://app.pendo.io/admin/app/-323232, copy the name of the app, click on the blue edit icon in the first row of the App table, paste in the name, and Save.
All other apps will have a system generated value. For example, in this URL
https://app.pendo.io/admin/app/5629499534213120theappIdis5629499534213120. To collect all your App IDs and populate this table, go into Pendo, navigate toSettings->Subscription Settings, then clickView App Detailsfor each of the apps you want to map individually into Planhat. On the Planhat "Apps" tab, click "Add New" and copy theappIdand name ("Metric Prefix") into the popup
Finally,
unknownis a catch-all ID where any unmapped ID will go: edit this item and add an intuitive "Metric Prefix" such as "Other Apps" so you can keep track. If the metric prefix of any app is left empty, they will be split into different metrics whenMulti-app?is toggled on, but no prefix will be added.
📌 Note: if at any time you want to add an app to the app mapping, simply select "Add New" and enter the appId and desired "Metric Prefix". When you add/edit/remove any App mappings, remember, you'll need to click "Re-sync all" and wait for your metrics to be updated retrospectively.
8. (Optional) Multi-Segment Set Up
If you'd like to use Pendo Segments to bring Features and Pages into Planhat, you'll need to configure them in much the same way as Apps, above.
Head over to the "Segments" tab, select Add New and input the relevant Segment ID and Segment Name. Your segment will then become available at the bottom of the mapping selector for Pages and Features.
9. (Optional) Timezone Set Up
Pendo uses local time for their data, but Planhat uses UTC. This means that by default, the Pendo integration will sync data 2 days back to ensure that no datapoints have been missed due to timezone. As a result, any Metrics created using Pendo data will always have values trailing the rest of your metrics by 1 day.
To avoid this, you can input your local timezone (to match your Pendo timezone) in the sidepanel of the configurator.
As a result, we will be able to sync in line with the rest of your Metrics, resulting your data being current up to 1 day ago.
Now you're all set to start mapping metrics from Pendo to Planhat! Here's Part 2, to show you how it's done.