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:

  • Features and Pages: single user event streams

  • Reports: (multiple) streams of aggregated event data, summarised in table form at either the Visitor (end user) or Account (company) level

  • 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". See here for how to configure a multi-app connection.

📌 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.

End User Creation

The integration can create end users in Planhat for any User Activity mapped to any object. Simply toggle "Auto-create users?" to ON when shown, 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.

📌 Note: the Pendo accountId - or equivalent Company ID field - must always be populated, and a corresponding Company must exist in Planhat in order to map to the End User object and/or Auto-create End Users.

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 ExternalId or Email, in addition to Company ExternalId)

  • 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 its ExternalId to 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 90 days history

Historical Data

  • When synced fully, the integration will only bring Pendo data from the past 90 days into Planhat, not the full data history. As a result, reports can only be mapped to Planhat if they are built for a time period of 90 days or less.

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 ExternalId in 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 using visitorId - or the equivalent End User ID field - or Email.

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 90 days: any reports of more than 90 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 all button. 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 90 days, any values stored in the metric from more than 90 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 90 days ago, and fetch new data. This means you will end up with all the metrics you have mapped, but with only 90 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:

  1. Prepare Planhat-specific reports

  2. Define your aggregation pipelines

  3. Create your Integration Key

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 90 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:

  1. Login to the Pendo Application as an Admin user.

  2. Visit the Integrations section in the Pendo App, and then click on the Integration Keys tab

  3. Click on the Add Integration Key button at the top right-hand side of the screen.

  4. Give your new key an appropriate description, such as "Planhat Integration Key".

  5. Ensure the box marked Allow Write Access is ticked

  6. 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

  • Hover over your profile in the bottom right of the Planhat screen and select "Integrations" from the popup menu

  • 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 Keys page 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. Check the required field mappings on the left panel

  • By default, the connection only maps to Companies and End Users, and can only map using these objects' Planhat External ID field (ExternalId)

  • Since these Planhat ExternalId are mapped by default to accountId and visitorId fields in Pendo, you will need to ensure that:

    • either all Companies have the Pendo accountId as their ExternalId field and all End Users have the Pendo visitorId as their External Id field

    • or that the External Id of all Companies 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 may want to do in the rare case that you have custom ID fields set up in Pendo)

📌 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.

4. (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 ExternalId of 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 ExternalId or Email, in addition to Company ExternalId)

    • 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 leave the default mapping as it is, but additionally populate the "End User Email" field with the name of the field in Pendo containing the end user's email address.

📌 Note: in order to match End Users by Email, "Auto-create users?" must be toggled ON for all relevant User Activity mappings.

📌 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, you must toggle "Auto-create users?" ON when configuring the specific User Activity mapping.

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 via the "Auto-create users?" toggle 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 this is not the case, the toggle will be disabled. When the mapped object (Feature, Page, Aggregation, Report, PES) has no such value, the "Auto-create users?" toggle will be locked. Similarly, 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.

5. 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 90 days ago.

6. (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 values: -323232 and unknown. Since the first app associated with your Pendo subscription will always have the appId value -323232, you can navigate to the domain https://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/5629499534213120 the appId is 5629499534213120. To collect all your App IDs and populate this table, go into Pendo, navigate to Settings -> Subscription Settings, then click View App Details for each of the apps you want to map individually into Planhat. On the Planhat "Apps" tab, click "Add New" and copy the appId and name ("Metric Prefix") into the popup

  • Finally, unknown is 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

📌 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". In order to have all your current "Multi-app" metric mappings built for this new app, remember, you'll need to click "Re-sync all" and wait for your metrics to be updated.

Now you're all set to start mapping metrics from Pendo to Planhat! Here's Part 2, to show you how it's done.

Did this answer your question?