Skip to main content
Gainsight Inc.

Instrument Your Product Using Product Mapper

This article explains how to use the Product Mapper modeling & instrumentation tool.


The Product Mapper feature allows you to model your product using a simple and powerful hierarchical tree structure that is designed to help you quickly and effectively map your product’s features and associate the tracked user events into the corresponding features and modules with zero coding.

Modeling can be modified anytime time using a simple drag-and-drop!


Gainsight PX tracking code must be configured in your application. Refer to this 3-minute video on how to insert Gainsight PX code in your application.

Anatomy of Product Mapper

The Gainsight PX Product Mapper is made up of three elements:

  • Module
  • Feature
  • Rules


A Module in Product Mapper represents a module in your product which can be a section, tab, or window of your application. While modeling your product use modules and sub-modules driven by the way you describe your product and the way the UI is built. You can always modify it. For example, the following image shows the Gainsight NXT product structure with Home, Timeline, Cockpit, Survey, Journey Orchestrator, and Administration modules.

GS_NXT app.gif

You can model this as a tree structure within Product Mapper. You can create a Module for each section in the application (like Home, Timeline, Cockpit, and so on). The Home Module represents the Home section of the application, the Timeline Module represents the Timeline section of the application, and so on. All the modules together form a product tree of your application.


A Feature represents a feature in your product. Features consist of rules that are mapped to events from your application. There are three types of rules you can use in a feature:

  • URL Rule: A URL rule is used to track the pageview event. In single page application, Gainsight PX will generate a pageview event on URL change even if the page is not reloaded.
  • Tag UI Element Rule: This rule tracks clickable elements in the UI by matching against the DOM element using a unique CSS selector.
  • UI Text Element Rule: This rule tracks clickable elements in the UI with the additional match against the element's label (such as button label or text label), to identify elements when there are multiple UI elements with similar CSS.
  • Custom Event: This rule tracks events fired via API. For more information refer to the Use Custom Event API article from the Additional Resources section.

Automatic Instrumentation with Instant Mapper

The Instant Mapper helps you by suggesting a list of features and modules to be included in your product tree. Currently, Instant Mapper suggests only URL rule features to be included in your product tree based on pages visited by your users. The suggested features will automatically map to the feature hierarchy in your product while giving you the ability to accept the suggestion, modify its place by dragging and dropping, or choose to ignore the suggested features.

To view feature suggestions:

  1. Click the Use Suggestion Mode button.
  2. (Optional) Click Configure Domain Filters to add domain specific filters in case your product has multiple domains.
  3. In the Suggestion Mode screen, click Get Started. PX automatically scans your application and displays a summary of the suggestions.
  4. Click Preview Product Tree to view a list of features suggested, along with the modules.

All the clickable elements with <a> tag on a product page are mapped automatically. These elements can be added to the respective features in the Product Tree.

To add a feature or module to the product tree, click Add to Tree.


  • When you choose to add a suggested module to the product tree, all the features suggested under the selected module are also added to the product tree. 
  • When you choose to add only a single feature from a module, the other components of the module are not added to the product tree and only the selected feature and the module to which it belongs, are added to the product tree.

Manual Instrumentation in Product Mapper

This section explains the process of creating Modules and Features in Product Mapper to instrument features in your application. In this tutorial, the Gainsight NXT application is used to demonstrate the process of identifying Modules and Features. Gainsight PX recommends to apply the same process to your application.

Floating Mapper 

Gainsight PX helps you to adjust the position of the pane of the Product Mapper while mapping the UI elements. The floating mapper provides you with the flexibility to place the mapping pane on the top or bottom of your application so that it does not obstruct your view or interfere with the application. The Product Tree structure of the in-app mapper aims at making the mapping easier and more streamlined.

To use this enhancement, admins need to navigate to Administration SDK Settings and turn ON the Enabling Floating Editor Mode option.

Dock Mapper.jpg

Create Modules

This subsection explains the process of creating Modules in Gainsight PX.

To create Modules:

  1. Click the Product Mapper icon from the left pane.
  2. Click +New and select Module from the menu. This Module will represent the Dashboard section of the application.
    You can also use the icons in the right corner to create a new module or feature.

Product Mapper - New Module1.jpg

  1. Type the module name in the text box that appears and press the enter key. A new Module is created.
  2. To created nested Modules, right-click the parent module and select Module from the Add New menu options.

Mapper - Nested Module.jpg

  1. Repeat steps 2 and 3 to identify create all the modules that form a product tree of your application on the left pane.

Product Mapper - Product Tree.jpg

You can now see that the application is modeled into a product tree. This product tree has many modules; Home, Timeline, Cockpit, Surveys, Journey Orchestrator, Administration, and so on. Collectively the modules form the product tree of the application.

Identify Features

Once you identify Modules to represent your product structure, you need to add Features for each module to track various metrics on your web page. This section explains the process of creating features in Product mapper.

Create URL Rule

This section describes how to create URL rules that track the number of page views.

To create a URL rule feature:

  1. Right-click the Module for which the Feature must be created and select Feature.
  2. Type a name for the Feature in the text box and press the enter key.

Product Mapper - New feature.jpg

This feature will track the number of times the Dashboard page has been visited.

  1. Right-click the Feature and select URL rule. An URL rule is used to track the number of times a page was visited.

Product Mapper - URL Rule.jpg

  1. In the Scope window, enter the URL of the page to be tracked. In this example, the URL of the Dashboard webpage is entered. This tracks the number of pageviews for the Dashboard page.

Product Mapper URL Rule GS 1.jpg

In this case, whenever a user opens the above URL (accesses the Home page), the rule is matched and the count of the number of Dashboard views is incremented by one.

You can use a Wildcard (*) to match multiple instances of a URL

You can also use wildcards to match a rule. Consider a scenario in which you have multiple URLs for the Home page (say Home/v1, Home/v2, Home/v3 etc), but all three URLs redirect you to the same Home page. In such cases, you can use the asterisk (*) wildcard to match all instances of the Dashboard URL, as shown below.

Product Mapper URL Rule GS.jpg

In this case, the Home page view is incremented, irrespective of the URL was used to access the page.

You can also use the wildcard at the beginning of the URL as shown below:

Product Mapper URL rule wildcard.jpg

  1. (Optional) Click + Add to add multiple URLs. In this case, pageview is tracked only when user visits all the pages mentioned added in the above rule.
  2. Click Save.

Once a rule is created, the Feature icon color changes to blue from grey.


You can visit the page being tracked and then navigate to the Audience Explorer page to ensure that the newly identified feature is being tracked.

Recent Activity Page Views.jpg

If two or more UI elements of your application have the same name, you must instrument your strategy to hold the full path of the UI element. This process must be performed carefully as any typographical error in the name of any element in the hierarchical structure can prevent the tracking of your element.

Product Mapper Create CTA.jpg

When you map elements in a hierarchical structure, Gainsight PX Analytics automatically rolls up the data from lower levels to higher levels.

In the above image, Survey List URL Rule and Add Survey features are part of the Survey List Module. You can view that the sum of their total events (476 + 160) is automatically rolled up and displayed as Total Events of the module (636).

Tag and Create Feature 

Use the Tag & Create Feature button to tag UI elements and create features in Product Mapper. This brings a unified rule creation capability for CSS selectors and texts.

  1. Click Start Mapping.
  2. Enter the URL of the page on which the UI element is located. 
  3. Click Launch. You are navigated to the URL. You can see that Product Mapper is now embedded on top of the target web page.
  4. Click Tag & Create Feature.
  5. Click on the desired UI element to be mapped. A New Feature window displays.
  6. Configure the Scope and Selector details of the feature, if you want to modify the default settings.
  7. Click Save. The element is mapped as a feature in Product Mapper.

SB Admin Angular 4 BS4 - Google Chrome 2021-09-02 at 4.43.28 PM.jpeg

Create Features with Only Text Matches

You can use the Match Text option that can create features with text match only. This helps in preventing applications with dynamic UI elements from experiencing CSS selector match issues and provides flexibility to map the unique elements faster.

Note: Features created using this option cannot be backfilled.

Mapper Text Match.png

Create Tag UI Element Rule

This subsection describes how to create Tag UI Element rules. UI Element rules track the number of times a UI element (button) is clicked.

To create URL rule:

  1. Right-click the required module and select Add Feature.
  2. Enter a name for the feature in the text box and press the enter key. This event will count the number of times the Export button (on the Home page) is clicked. You can analyze the number of times the specific page has been exported by users.
  3. Follow steps 1 and 2 to identify multiple features under the Audience Explorer Module or any other Modules.
  4. Click the Home Page Export count feature.
  5. Click Start Mapping.
  6. Enter the URL of the page on which the required button is located. (Here URL of Gainsight NXT application’s Home page).
  7. Click Launch.

Homepage Export Count.jpg

You are navigated to the URL. Here the target URL is Gainsight NXT’s Home feature. Hence, you are navigated to the Home page. You can see that Product Mapper is now embedded on top of the Home page. You can configure UI Element rules from the application.

Prod Mapper URL redirect.png

  1. From the Select feature drop-down menu, select the Home Page Export count feature. You must select the feature which you created in Step 2.
  2. Click Tag UI Element as feature.
  3. Select the EXPORT button. The Event window is displayed. The Scope page displays the URL of the page on which the button is located. It is very important to add the wildcard (*) on the Scope tab. The Selector tab displays the path used to reach the selected element.
  4. Click Save.

Create UI Element Rule Manually

You can also create UI Element Rules manually, by copying the CSS element code of the button.

To create UI Element rules manually:

  1. Right-click the required feature and select Tag UI Element.
  2. Enter the URL of the page on which the UI element tab is located.
  1. Navigate to the page on which the button is located.
  2. Right-click the required button and select Inspect.
  3. Identify the code block which contains the code for your button.
  4. Right-click the code block and select Copy > Copy Selector.
  5. Return to the Gainsight PX site and paste the code (Ctrl + V).
  6. Click Save.

Mapping Menus

If you have sub-menus and drop-down lists in your application, you can map them with the “Tag UI Element” rule. When mapping a sub-element, you must temporarily turn off the mapping to reach the required element. Once you select the “Tag UI Element” button, press ctrl+alt+m to disable mapping. Once you reach the desired location on UI, you can again press ctrl+alt+m to enable mapping.

Advanced DOM Tracking

You can configure the tracking code to use DOM elements present in your application. For more information, refer to the Advanced Instrumentation article from the Additional Resources section.

Create UI Text Element Rule

This subsection describes how to create UI Element Text Match rules. Text match rules against the element's label (such as button label or text label), to identify an element when there are multiple UI elements with similar CSS.

To create the UI Text Element rule:

  1. Click the Product Mapper icon from the left pane.
  2. On the Product Feature Tree ® page, click on the feature.
  3. Click Start Mapping.
    Note: Alternatively, you can also click on the UI Text Element button on the top right corner to define the URL and element text rule from the PX application.  
  4. Enter the URL of the page on which the required UI element exists.
  5. Click Launch. You are navigated to the target page and the in-app Product Mapper options are displayed on top of the page.
  6. From the Select feature drop-down menu, select the feature.
  7. Click on the UI Text Element rule icon.
  8. Click on the UI element that must be tracked when clicked. The Event window is displayed. 


  • The Scope tab displays the URL of the page. Add the wildcard (*) to the URL.
  • The Text Element tab displays the path to the selected element.
  1. Click Save.
  2. Click Exit to navigate to the PX application.

Note: Features Mapped using the UI Text Element rule are not eligible for Backfill.

Create Custom Event Rule

A custom event is used to track those parts of your application that are not present on the UI. The steps to create a custom event rule are the same (up to step 8) as in the Create UI Element Rule section of this document.

To create a Custom Event Rule:

  1. Refer to the Create UI Element Rule (initial 8 steps) section above.
  2. From the Select feature drop-down menu, select the required feature (here Home Custom Event). You must select the feature which you created.
  3. Click the Custom Event Rule as Feature.
  4. From the drop-down menu, select the required custom event. The options displayed in the drop-down menu, are created by your developers.
  5. Click Save.

To learn about all frequently asked questions, refer Product Mapper FAQs article from the Additional Resources section.

Create Labels for Features and Modules 

You can create labels to organize product features and modules in Product Mapper. The labels make it easier to select a group of relevant features to create analytics reports or to export feature usage data via integrations.  You can use the labeled features to build queries using Query Builder and to export feature usage data using Data Export.

To create labels:

  1. On the Product Feature Tree ® page, click on the feature/module for which you want to create the label.
  2. Click the Add Labels icon.
  3. Click Create Labels. The Create Label window appears.
  4. Provide the details and click Create. The label is created.

Create Label1.png


  • You can add a maximum of 10 features or modules to a label.
  • You can create a maximum of 20 labels per product.

For more information on creating Data Exports using labels, refer to the Bulk Export Custom Reports from PX article from the Additional Resources section. For more information on building queries using feature labels, refer to the Query Builder article from the Additional Resources section.

View Mapped Features and Product Tree Path

Product Mapper has a Show mapped features option that helps you view the features mapped already in the selected URL of your application. This helps in identifying the features that are yet to be mapped thus avoiding duplicate mapping.

Show Mapped features.png

You can view the full path of feature/module names in the search results dropdown list in Product Mapper. This helps to select the right feature or modules, especially in scenarios where there are similar feature names within different modules.

Product Mapper search.png


Gainsight PX has defined limits to the number of features and modules that can be mapped. The following are the limits:

At the subscription level (across all the products):

  • Features - A maximum of 10000 features and modules can be mapped.
  • Feature Rules - A maximum of 10000 rules can be created.

At the product level:

  • For the Enterprise plan - A maximum of 5000 features can be mapped.
  • For the Essential plan - A maximum of 3000 features can be mapped.


Gainsight PX allows you to perform a Backfill action on any mapped feature. With Backfill, you can choose a feature and execute historical data collection against this feature.

Note: Features Mapped using the UI Text Element rule are not eligible for Backfill.

ProductMapper Backfill.jpg

Important considerations about Backfill:

  • You need to perform Backfill for each feature individually.
  • The backfill process collects up to 365 days of historical data from all the events.
  • Backfill processing starts 15 minutes after the last feature Backfill request of a subscription.
    Each time there is a backfill request, Gainsight PX waits for 15 minutes before starting the actual Backfill process. If there is a new request for another feature of the same subscription during these 15 minutes, then this feature is added to the upcoming backfill processing. Another 15-minute wait window starts now. If no new feature Backfill requests are received during this wait window, then the Backfill processing starts.
  • A single Backfill request can work with multiple product trees.
  • When you click the Start Backfill button for a feature, an orange dot appears for the feature to indicate the ongoing Backfill process.
    Backfill Orange dot.jpg
  • Backfill processing time can vary between 5 - 48 hours, after which the historical data appears in Analytics.
  • For instance, if you need to create a backfill for 10 features, then it is recommended to create Backfill requests for all the 10 features at the same time. 
  • If you edit the URL details of an existing feature in the Mapper and then perform backfill, the process adds the events but does not delete the historic events data. In this case, the best practice is to add a new URL rule event on the same feature as opposed to creating a new feature altogether. You can then delete the historic data if the data is irrelevant or if it overlaps with the new data.