Planhat's unidirectional integration with Pendo allows you to pull all your customers' usage data into Planhat, for all your apps, all at once.
Now that you've set up the integration itself, you're ready to start mapping metrics from Pendo to Planhat. This article is designed to help you do that as quickly and efficiently as possible.
Contents
This is Part 2 of our 2-part Pendo Guide. In this set-up guide we'll cover how to map metrics from Pendo to Planhat for:
Aggregations; and the
This is your one-stop resource for creating a new metric mapping from Pendo to Planhat, or troubleshooting an existing mapping.
If you haven't set up the integration yet, or are just interested in finding out what the integration can do, check out Part 1: Setting Up the v2 Pendo Integration.
Time to get that data flowing...
How to Map Metrics from Pendo to Planhat
Housekeeping
Now your integration is configured, you can add as many mappings from Pendo as you like, at any time. If for any reason you change your integration's configuration (either from the "Apps" tab or the left configurator panel - always click "Update" when you're done!), remember to click the green "Re-sync all" button to make sure those changes are reflected.
These steps assume that you have already:
configured the left panel of the integration with the correct settings (at minimum, those shown in the view below), so the connection is shown as active
added any applications you wish to map to Planhat individually, from the "Apps" tab
prepared your Reports and Aggregations in line with our recommendations as part of the setup preparation steps
They also assume that you know what to expect from the Pendo integration, so that you are not surprised by any results. If you haven't yet completed these steps, head to the Set Up guide here, particularly the sections on Preparation Steps and Set Up.
Once you're all good to go, read on!
📌 Note: once you've set up a mapping in the Pendo integration, you can't edit it: you'll need to delete it and map again.
1. Start a New Mapping and choose a Pendo Object to map out to Planhat
Click "Add New" on the "Mapping" tab, and choose whether you're looking to map an object of type:
Click one of the links above to shortcut to the mapping for a specific object.
📌 Note: the PES can only be mapped and synced to Planhat if the ExternalId of the object you wish to map to is set to match the Pendo accountId (not any other custom Pendo field).
When you're done mapping, you'll need to "Re-sync all". However, any existing Pendo metric data mapped from more than your "Days to Sync" (1-365) days ago will be permanently deleted. This means you should ideally set up all your mappings (for all your apps) all at once, to avoid needing to "Re-sync all" in future.
📌 Note: 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.
Page or Feature
Features and Pages are the most basic and straightforward type of mapping data from Pendo. The number of feature actions or page visits convert into a custom metric or user activity.
Requirements: numerical datapoints only, and relevant ID fields:
always mapping to the Company External ID and potentially also mapping to:
the End User External ID or End User Email if wishing to map to User Activities
the Asset or Project External ID if wishing to map to Assets or Projects
Select:
the name of the Page or Feature you want to map from Pendo
a metric name that will help you identify the metric when it's in Planhat (remember that if
Multi-appis toggled on, the name of the related app will be added as a prefix "App Name-Metric Name", so only include references to specific apps if you don't want to haveMulti-apptoggledON)whether you want to map the page or feature as a Custom Metric or User Activity
if you map as a User Activity, the global "Automatic Detection of New Contacts" setting will apply. If enabled, this will auto create any End Users which are present in Pendo but not found in Planhat.
the Planhat model you want to map to:
Custom Metrics can be mapped to both the Company and End User
User Activities can only be mapped to the End User, not the Company (although they will always roll up to the Company, meaning they are effectively mapped to both)
If you have populated the Asset and/or Project mappings in the left configurator panel, you will also be able to map to the Asset/Project objects in Planhat. However, one condition holds:
if the Asset or Project
ExternalIdis mapped to a Pendo account field (of the form account.field), you will be able to map to Assets and Projects as both Custom Metrics and User Activities
if the Asset or Project ExternalId is mapped to a Pendo visitor field (of the form visitor.
field), you will not be able to map to these objects as Custom Metrics: only as User Activities
whether you want the Page or Feature to be built by app (toggle
Multi-apptoON): since Pages and Features are always built for a single app, "Multi-app" will simply add a prefix to the metric stating the app it relates to, which can be useful if you have multiple similarly named pages or features relating to different applications.
📌 Note: from a data perspective a User Activity is practically identical to a Custom Metric, but behaves differently in 3 important ways: User Activities..
are always tied to an End User (meaning they require both an End User ID and Company ID to be mapped),
will show up in Planhat System Metrics (featured by default on the Company 360 page) relating to User Activities, such as "Last Seen"
will automatically be aggregated up to the company level
Segments
If you have configured Segments, you will be able to use them to pre-filter the data being pulled from Pendo for any given Feature or Page mapping to match only a particular Segment. If you would like to map a single Page or Feature for multiple Segments separately, you will need to create multiple mappings, 1 per Segment.
Report
Each report has multiple columns (datapoints), each mapped to its own metric.
Requirements: numerical datapoints only (all non-numerical datapoints in a report will not be shown), no fixed date fields (only relative time series with a floating time series window), relevant ID fields:
always mapping to the Company External ID and potentially also mapping to:
the End User External ID or End User Email if wishing to map to User Activities
the Asset or Project External ID if wishing to map to Assets or Projects
Select:
the name of the Report you want to map from Pendo
the report selection dropdown is split into
VisitorandAccountreport sections to help you ensure you map the right report, even if you have similarly named reports of each typenote: we actively discourage reports with a time window greater than 30 days, but the only hard limit is 180 days: any reports of more than 180 days will not show up in the selection dropdown
immediately, any columns in the report which can be mapped (numeric columns) will appear with both their raw source name, and their Pendo column names mapped as default Planhat "Metric Name" values
whether you want to map the metric as a Custom Metric or User Activity
if a report contains the field corresponding to End User External ID, it can be mapped to both a User Activity and Custom Metric. If it contains no field corresponding to End User External ID, it can only be mapped to a Custom Metric.
if you map as a User Activity, the global "Automatic Detection of New Contacts" setting will apply. If enabled, this will auto create any End Users which are present in Pendo but not found in Planhat.
metric names that will help you identify the metric when it's in Planhat (remember that if
Multi-appis toggled on, the name of the related app will be added as a prefix "App Name-Metric Name", so only include references to specific apps if you don't want to haveMulti-apptoggledON)the Planhat model you want to map to:
Custom Metrics can be mapped to both the Company and End User, although one condition holds:
if the report contains the field corresponding to the End User
ExternalId, Custom Metrics can be mapped to both the Company and End Userif not, Custom Metrics can only be mapped to the Company
User Activities can only be mapped to the End User, not the Company (although they will always roll up to the Company, meaning they are effectively mapped to both)
If you have populated the Asset and/or Project mappings in the left configurator panel, you will also be able to map to the Asset/Project objects in Planhat. However, two conditions hold:
if the Asset or Project
ExternalIdis mapped to a Pendo account field (of the form account.field), you will be able to map to Assets and Projects as follows:if the report contains the field corresponding to the End User
ExternalId, metrics can be mapped to these objects as both Custom Metrics and User Activitiesif the report does not contain the field corresponding to the End User
ExternalId, metrics can only be mapped to these objects as Custom Metrics
if the Asset or Project ExternalId is mapped to a Pendo visitor field (of the form visitor.
field), you will not be able to map to these objects as Custom Metrics: only as User Activities
whether you want the report to be built by app (toggle
Multi-apptoON). If the report:has been built only for 1 app, just like for a Feature or Page, "Multi-app" will simply add a prefix to each mapped metric stating the app it relates to, which can be useful if you have multiple similarly named metrics relating to different applications
has been built for more than 1 app, "Multi-app" will split each of the metrics mapped from the report into multiple metrics, 1 corresponding to each
appIdwith values for the report, and each named with the "App Name" (configured in the "Apps" tab of the Integration) as a prefix to the overall metric name
Aggregation
Mapping aggregations is very similar to mapping reports, though we are the ones providing the formula to extract the data from Pendo.
Requirements: numerical datapoints only, no fixed date fields (only relative time series with a floating time series window), relevant ID fields:
always mapping to the Company External ID and potentially also mapping to:
the End User External ID or End User Email if wishing to map to User Activities
the Asset or Project External ID if wishing to map to Assets or Projects
Select the aggregation you want to map to Planhat, and paste it into the "Pipeline" section of the "Mapping" window
Add a name for the aggregation. This will be shown in the Integration table to help you identify the aggregation: it will not be the name of the resulting metric(s)
📌 Note: see here for how to write an aggregation pipeline.
Click "Test pipeline": if the pipeline is valid, a mapping section will appear below:
In this example, my aggregation contains 2 metrics, both relating to "Total Logins", but aggregated over different periods. Both of them apply to logins across all my apps
Just like for Features and Pages, you can now select:
a metric name that will help you identify the metric when it's in Planhat (remember that if
Multi-appis toggled on, the name of the related app will be added as a prefix "App Name-Metric Name", so only include references to specific apps if you don't want to haveMulti-apptoggledON)whether you want to map the metric as a Custom Metric or User Activity:
if the aggregation contains the field corresponding to End User External ID, as well as the field corresponding to Company External ID, its resulting metrics can be mapped to both a User Activity and Custom Metric. If it contains no field corresponding to End User External ID, they can only be mapped to a Custom Metric.
if you map as a User Activity, the global "Automatic Detection of New Contacts"" setting will apply. If enabled, this will auto create any End Users which are present in Pendo but not found in Planhat.
the Planhat model you want to map to:
Custom Metrics can be mapped to both the Company and End User, although one condition holds:
if the aggregation is grouped by visitor, Custom Metrics can be mapped to both the Company and End User object:
{
"group": {
"group": ["visitorId"]
}
}if the aggregation is grouped by account, Custom Metrics can only be mapped to the Company object:
{
"group": {
"group": ["accountId"]
}
}
User Activities can only be mapped to the End User, not the Company (although they will always roll up to the Company, meaning they are effectively mapped to both)
If you have populated the Asset and/or Project mappings in the left configurator panel, you will also be able to map to the Asset/Project objects in Planhat. However, two conditions hold:
if the Asset or Project
ExternalIdis mapped to a Pendo account field (of the form account.field), you will be able to map to Assets and Projects as follows:if the aggregation contains the field corresponding to the End User
ExternalId, metrics can be mapped to these objects as both Custom Metrics and User Activitiesif the aggregation does not contain the field corresponding to the End User
ExternalId, metrics can only be mapped to these objects as Custom Metrics
if the Asset or Project ExternalId is mapped to a Pendo visitor field (of the form visitor.
field), you will not be able to map to these objects as Custom Metrics: only as User Activities
whether you want the aggregation to be built by app (toggle
Multi-apptoON). If the aggregation:has been built only for 1 app, just like for a Feature or Page, "Multi-app" will simply add a prefix to each mapped metric stating the app it relates to, which can be useful if you have multiple similarly named metrics relating to different applications
has been built for more than 1 app, "Multi-app" will split each of the metrics mapped from the aggregation into multiple metrics, 1 corresponding to each
appIdwith values for the aggregation, and each named with the "App Name" (configured in the "Apps" tab of the Integration) as a prefix to the overall metric name
PES (Product Engagement Score)
There are 4 metrics per PES score - Stickiness, Adoption, Growth, and the total PES score. Each day, the score is calculated per Pendo App (you can only pick one app per score) and time period: e.g. If you have a 30-day PES score, the score for 2023-06-15 would cover the PES data for 2023-05-15 - 2023-06-15.
Requirements: have the PES configured in Pendo, have your Apps named in the configurator's "Apps" tab, have the Company (and/or Asset/Project) ExternalId in Planhat set to match the Pendo accountId (which is the default), and not another custom ID field in Pendo.
Select:
the name of the Pendo app (
appId-App Name) that you want to map PES for in Planhat: if you haven't configured your Applications in the integration, follow these steps to get set upthe window of time you want the PES to be calculated for (for example, a 30-day PES will be calculated using values only from the past 30 days, each day) - anywhere from 1 to 90 (which is the maximum limit Planhat allows)
whether you want all the PES components (Growth, Stickiness, and Adoption) metric names, or just some of them: you can simply delete any components you're not interested in mapping to Planhat
there's no need to change the metric names for your PES scores: by default, they will be named "
App Name-Metric Name", so you can clearly track all your PES metrics by appthere's also no need to modify the metric type, since the PES can only exist as a Custom Metric at the non-End User level
the Planhat model you want to map to:
as mentioned above, you cannot map PES to the End User model, so the Company model will be the default, unless you also have Assets and Projects configured with their
ExternalIdmapped to the PendoaccountId
When you're done mapping, you'll need to "Re-sync all". However, any existing Pendo metric data mapped from more than your "Days Since" (1-365) days ago will be permanently deleted. This means you should ideally set up all your mappings (for all your apps) all at once, to avoid needing to "Re-sync all" in future.
📌 Note: to ensure that the all (not just the last 2 weeks) of the raw data pulled from Pendo as a Custom Metric or User Activity is rendered into any resulting Calculated Metrics, you must "Rebuild" them immediately after they are created.
Editing your Mappings
You can edit existing Pendo mappings by clicking the pencil icon to its far left.
The properties you edit will determine whether a Re-sync all is required or not. Remember that if you Re-sync all, Planhat will only sync events back as far as your Days to Sync configuration, so contact your CSM if you need this to be extended (up to 365 days) to minimise data loss.
Re-sync all required when editing:
Aggregation Query
Report Columns
Metric Name
Metric Type
Metric Model
Multi-App
If you edit any of these properties, Planhat will recommend a Re-sync.
Re-sync all not required when editing:
Passive?
If you edit any of these properties, Planhat will not force a Re-sync. Instead, the change will apply to all future events. To apply the change to historical events too, you can click Re-sync all.
📌 Note: since Passive? will affect how end users are classified as active in system
metrics, you should contact your CSM to discuss a system metric rebuild before performing a Re-sync all.
Troubleshooting
How can I migrate from Pendo v1 to v2 without losing my existing metric history?
Export your existing Custom Metrics (generated by the Pendo v1 integration), and download a Custom Metric (Dimension Data) import Excel sheet
Delete the existing Custom Metrics
Turn off the Pendo v1 connection
Activate the Pendo v2 connection and configure it using these steps
Map all the metrics you want following the steps in this article above
Copy and Paste your historical Excel metric data from the export into the Excel import template
Remove the most recent "Days Since" (1-365) days of data for each metric in the import Excel sheets (so you ensure you're not overwriting the latest sync from V2)
Import these Excel sheets into Planhat: these dimension data imports will update the history for the custom metrics you're syncing from the v2 Pendo integration
Click "Rebuild Metric" to ensure the historical data is processed
When should I Re-sync all?
There are some actions which require a full metric re-sync. The sync is not performed automatically to not disturb the current data sync, but is recommended to ensure correct mapping of all metrics.
You will be advised to Re-sync all when:
Adding/removing/editing application mappings
Changing configuration settings (External ID fields)
When a full Re-sync is needed, a warning will show up in the integration status page, advising the user to perform it. After starting the Re-sync, all metric data will be deleted and re-fetched from Pendo.
Do I need to manual Re-sync after editing a single mapping?
No. To avoid the need for a full Re-sync each time a single metric is modified, a popup will show allowing you to trigger a Re-sync just for the metric you've edited.
What should I know if I want to change the ExternalId mapping?
Once you've changed the ExternalId mapping, you should click Re-sync all.
If you wish to import historical data from Excel after this change, keep in mind that you will need to update the ExternalId field to match.
When should I manually delete metrics created by the Pendo integration?
As mentioned above, when you click Re-sync all, all existing metrics will be deleted and replaced. This means if you simply edit an existing mapping, or edit the global integration settings, a Re-sync all will propagate changes to the resulting Metrics.
However, this does not apply if you delete a metric mapping and click Re-sync all. In this case, the mapping is removed (meaning no more data will flow to it), but the resulting metric will still exist. In this instance, you will also need to delete the metric.
Where can I check for failed Metric syncs?
Until all requirements are met, received metric data will not be fully ingested into Planhat.
If you haven’t set up the required ID mappings in Planhat, you can find the non-ingested data points in the data module, Metrics tab. You can evaluate these failed Metrics from the kebab (ellipsis) menu in the top right, Review > Failed Metrics/Activities.
This will open a sample of the ingested data with no External ID match. You can export the entire file to Excel, match the IDs as needed, and then click “Repeat All” to bring your data successfully into Planhat.
Where can I see my successfully synced Metrics?
All metrics with correct matching IDs should be visible in the All Metrics table, from the Data Module. If not, and no metrics can be seen under Failed Metrics, then you can access "Refresh List" via the kebab (ellipsis) menu in the top right.
If that still produces no results, you should contact Planhat support.
My Metrics don't seem to be mapping correctly. Can you help?
As mentioned throughout this documentation, we rely largely on External IDs to be able to match data in Planhat with data in Pendo. However, there are some exceptions. For complete transparency, here is a list of our ID requirements per metric type:
Custom Metric
Mapping to Company: Company External ID
Mapping to Asset: Company External ID + Asset External ID
Mapping to Project: Company External ID + Project External ID
Mapping to End User:
Company External ID + End User External ID
Company External ID + End User Email
End User Email (with configured domain)
User Activity
Automatic Detection of New Contacts OFF
Mapping to End User:
Company External ID + End User External ID
Company External ID + End User Email
End User Email (with configured domain)
Mapping to Asset:
Asset External ID + Company External ID + End User External ID
Asset External ID + Company External ID + End User Email
Asset External ID + End User Email (with configured domain)
Mapping to Project:
Project External ID + Company External ID + End User External ID
Project External ID + Company External ID + End User Email
Project External ID + End User Email (with configured domain)
Automatic Detection of New Contacts ON
Mapping to End User: Company External ID OR Email with domain
Mapping to Asset: Asset External ID + Company External ID OR Email with domain
Mapping to Project: Project External ID + Company External ID OR Email with domain
How can I clear my connection to Pendo?
If you wish to connect to Pendo using a new API key, you can do that by clearing the connection. Once the integration is disabled, a button will show up with an option to clear connection data. Once that is finished, you can safely enter a new API URL/Key and set up a new Pendo integration.