When you connect a third party system to Gtmhub, you usually synchronize big amounts of data. Building insights that cover all this data is a great way to stay on top of things, but you often need to drill down and focus on a specific area. Whether you need to review data for a specific time period, business unit, region, or maybe the tasks under a Jira Epic, Gtmhub enables you to dynamically filter your insightboards data by definition insightboard parameters. In this article, you'll learn more about the concept of insightboard parameters and how to define them. To learn more about how to use the filters in your insightboards see Using insights with a filter.
Manage existing insightboard parameters
The insightboard parameters can be found in the configuration panel.
NOTE: Only Administrators and users that have custom roles with Manage Configuration permission can manage the account configurations.
Follow these steps to manage existing parameters:
- Navigate to Settings -> Insightboard Parameters.
- Initially, you will see three predefined parameters – date range, teams, and session. Date range is out of the box for most of the built-in insights and you can find more information about it in this article.
Create a new insightboard parameter
To create a new parameter, follow these steps:
- Navigate to Settings -> Insightboard Parameters
- Click on the “Add new parameter” box
- Fill in the necessary details:
- Title - this is what will be displayed on your insightboard as a filter name and is a required field.
- Key is what will be used in your SQL placeholder syntax. Both can have any values you decide (not necessarily the same), but keep in mind that the Key needs to be only in lowercase Latin letters and the words need to be separated with an underscore, so no blank spaces.
- In the Selector section, define the type of filter you would like to use. Currently, you have the following choices:
a) Free text field – this value set will create a filter which you can apply to a string entity field. The values will not appear as a list so the person would have to type in manually what he/she is looking for in the insightboard filter. E.g. you would like to track the completed stories in Jira marked with a certain label. This is how your insightboard parameter could look like:
Click on create a parameter definition to save and use your filter.
Every filter type can have a default value. If you decide to use it, you can either leave the predefined value for each filter type or select one yourself. Your data in the insightboard will be automatically filtered on it.
b) Date picker – as the name suggests - allows you to filter data based on a specific date. E.g. you would like to track all your due projects on May 17th, 2020. Note that the date will be displayed at 00:00:00 GMT at your current time zone. The default value is today's date. Here is how your filter could look like for this use case:
c) Date-range picker – apart from the default Date Range filter (which has predefined values), you have the option to create a filter with unspecified time periods. The default value for this filter type is next month, with starting day today. The UI is similar to the date picker parameter.
d) List – this filter type will provide you with a list of values and you are allowed to choose only one of them in your filter. Respectively, your default value can only be one. With the list you have two options:
- Have predefined values or,
- Use dynamic values from one of your connected entities from the external data sources.
In case 1 the list will consist of the values you predefined in the parameter. If those are not present, a text input will appear in your insightboard filter and you need to write manually the value you are filtering on. Here is how your filter could look like:
In case 2 - dynamic values, you will have to select couple of more options.
The first field is the Entity type. Here you will have to select from a list of all the entities from all connectors you have synced in Gtmhub.
NOTE: If your entity does not directly expose the field you want to use as a filter, you can use Virtual Data Sources to create a filter.
The second field is the Title field, where you need to select an entity field from the entity you selected above. Its values will be displayed in the UI of your list filter (just as the predefined values in case 1).
The last section is the Value field, for which you also need to select an entity field (from the same entity) and its values will be passed to the insight as parameter. Here is an example of list filter with dynamic values:
d) Multi-select dropdown – this type of filter has the same setup as the list. The two main differences are as follows:
- This filter allows you to select multiple values from your dropdown list, meaning you can select more than one value as default
- The SQL syntax is different than the list. You can see how in this article
The Insightboard parameters are a useful way to filter data in various ways. The biggest benefit being the ability to create only one insight and filtering the information in it to get specific information based on time period, owner, region, etc.
If you need support with creating insightboard parameters, figuring out how to use them for your specific use case or how to include them in your insights, do not hesitate to contact our Sales Engineering team and we will be more than happy to assist you.