Example: Creating a tag filter and using it to filter the output of insights

Overview

Tags allow you to easily filter OKRs throughout Gtmhub and categorize your OKRs. But you can also take advantage of them to dynamically narrow down the displayed data in an insight.

This article explains how to create the tag filter as an insightboard parameter, incorporate it in your insight SQL and how to apply the filter to narrow down the data displayed by your insights based on the tag filter.

Prerequisites

To be able to create and manage insightboard parameters, you must be an administrator or have permissions to manage the account settings.

For more information, see Create filters for insightboards.
To be able to apply a filter to an insightboard, you must have Update permissions for this insightboard.

Create the filter as an insightboard parameter

To create the tag insightboard parameter, perform the following:

In the bottom of the navigation panel, click Settings.
Within the Configuration tab, click Insightboard parameters.
Click on ADD NEW PARAMETER.
In Title, enter a name for the filter, f.ex. Tags.
This is the name that will be displayed in the UI of the insightboard.
In Key, enter the key that will be used to incorporate the filter in the insight algorithm.
It will be used in your SQL placeholder syntax.

NOTE: You can enter only lowercase Latin letters and underscore.
In the Selector dropdown box, select the type of selector that will be used for the filter. Generally, you can select one of the following: Free text field, Date picker, Date-range picker, List, Multi-select dropdown.

However, since with the Tags filter most often we want to directly expose the field that you want to use as a filter the most appropriate types for the Tags filter are List and Multi-select dropdown.

Tags filter List and Multi-select dropdown

You can select only one tag from the List and multiple tags from the Multi-select dropdown.

After choosing either of the selector, perform the following:

Select the type of the entity which values will be available to choose from: for the Tags filter its QuantiveResultsGoalTags
In Title field select the field which will be displayed as the parameter title in the selector in the UI: for the Tags filter its best to use Tag Name
In Value field select the name of the field from this entity that you want to use as parameters for the filter: again for the Tags filter choose Tag Name
The values of this field will be passed as the parameters for the filter in the SQL syntax.

You can now save your filter by clicking on "Save insightboard parameter". Your Tags filter is ready to be incorporated in insights.

Include the filter in the insight SQL

After you created your Tags insightboard parameter, you can add it to your insightboards.

To add it, perform the following:

In the navigation panel, expand Insights and click Insightboards.
Open the insightboard where the insight that you want to filter is located.
In the upper-left corner next to the insightboard's title, expand the menu.
Click Re-arrange.
Click </> (Edit insight) of the insight that you want to apply a filter to.

Edit the SQL query of the insight to include the Tags filter.
You do this by using the WHERE clause and the parameter key.
For more information about the parameter key, see Create filters for insightboards.
The syntax for getting the filter’s value is ‘%%param_key%%
For more information, see Sample filter syntax.

Tags filter examples:
List

CASE WHEN '%%tags%%' <> ''
                THEN (quantiveresultsgoals.id IN (SELECT goal_id FROM quantiveresultsgoaltags 
                WHERE name = '%%tags%%'))
            ELSE true END

Multi-select dropdown

CASE WHEN '%%tags%%' <> ''
                THEN (quantiveresultsgoals.id IN (SELECT goal_id FROM quantiveresultsgoaltags
                WHERE name IN (SELECT(UNNEST(string_to_array('%%tag%%', ','))))))
            ELSE true END

To check whether the syntax is correct, click Execute.
Click Save and leave.

Filter the insightboard data by tag

To filter an insightboard by the tag filter, perform the following:

In the navigation panel, expand Insights and click Insightboards.
Click on the desired insightboard. Insightboards automatically display all filters that exist in the SQL of all the insights in this board.

When you open an insightboard, if your filter does not have a predefined value, the filter displays None selected under the parameter title.
Select a value from the tag filter and click Apply selection. The output of the insightboards that contain the tag filter will change accordingly.

NOTE: When you select a value from the tag filter, it is applied to all insights in the insightboard that contain this filter.
To save the selection, click Save filters.

NOTE: The filters that you apply without clicking on Save filters are not saved automatically.
To clear the filter, click the filter again and click Remove selection > Save filters.