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:

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

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

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

Page or Feature

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-app is 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 have Multi-app toggled ON)

  • whether you want to map the page or feature as a Custom Metric or User Activity

    • if you map as a User Activity, you will have the option to toggle "Auto-create Users?" ON. This will auto create any End Users which are present in Pendo but not found in Planhat, assuming that the End User's Pendo accountId - or equivalent Company ID field - is populated, and a Company with that ID actually exists in Planhat. You will also need to have "Auto-create Users?" toggled on whenever you are planning to map End Users with Email, rather than Planhat's End User ID field

  • 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 ExternalId is 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-app to ON): 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: a Custom Metric is identical to a User Activity, except a User Activity is always tied to an End User (meaning it requires both an End User ID and Company ID to be mapped), and will show up in Planhat System Metrics (featured by default on the Company 360 page) relating to User Activities, such as "Last Seen"

Aggregation

Requirements: numerical datapoints only, no fixed date fields (only relative time series), 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-app is 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 have Multi-app toggled ON)

    • 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, you will have the option to toggle "Auto-create Users?" ON. This will auto create any End Users which are present in Pendo but not found in Planhat, assuming that the End User's Pendo accountId - or equivalent Company ID field - is populated, and a Company with that ID actually exists in Planhat. You will also need to have "Auto-create Users?" toggled on whenever you are planning to map End Users with Email, rather than Planhat's End User ID field

    • 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, one condition holds:

        • if the Asset or Project ExternalId is 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 Activities

          • if 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-app to ON). 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 appId with 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

Report

Requirements: numerical datapoints only, no fixed date fields (only relative time series), 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 Visitor and Account report sections to help you ensure you map the right report, even if you have similarly named reports of each type

    • 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, you will have the option to toggle "Auto-create Users?" ON. This will auto create any End Users which are present in Pendo but not found in Planhat, assuming that the End User's Pendo accountId - or equivalent Company ID field - is populated, and a Company with that ID actually exists in Planhat. You will also need to have "Auto-create Users?" toggled on whenever you are planning to map End Users with Email, rather than Planhat's End User ID field

  • metric names that will help you identify the metric when it's in Planhat (remember that if Multi-app is 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 have Multi-app toggled ON)

  • 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 User

      • if 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, one condition holds:

      • if the Asset or Project ExternalId is 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 Activities

        • if 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-app to ON). 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 appId with 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

PES (Product Engagement Score)

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 up

  • the 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 app

    • there'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 ExternalId mapped to the Pendo accountId

When you're done mapping, you'll need to "Re-sync all". However, any existing Pendo metric data mapped from more than 90 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.

Troubleshooting

How can I migrate from Pendo v1 to v2 without losing my existing metric history?

  1. Export your existing Custom Metrics (generated by the Pendo v1 integration), and download a Custom Metric (Dimension Data) import Excel sheet

  2. Delete the existing Custom Metrics

  3. Turn off the Pendo v1 connection

  4. Activate the Pendo v2 connection and configure it using these steps

  5. Map all the metrics you want following the steps in this article above

  6. Copy and Paste your historical Excel metric data from the export into the Excel import template

  7. Remove the most recent 90 days of data for each metric in the import Excel sheets (so you ensure you're not overwriting the latest sync from V2)

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

  9. Click "Rebuild Metric" to ensure the historical data is processed

Did this answer your question?