When you connect a third party system to Gtmhub, the information you choose to synchronize might be too vast for the specific report you need for your weekly/ monthly meetings. Therefore, Gtmhub gives you the option to create custom parameters that are used to filter the data in an insightboard. In order to do that there are two steps you need to take:
- Define a filter which we could use in multiple insights
- Add this filter in the SQL of an insight and it appears on the insightboard where we have included this insight
In this article we will explore how to execute step one (here you can find a thorough explanation of step two). The insighboard parameters can be found in the configuration panel, which is only available for admins and custom roles with Manage Configuration permission. Navigate to Configuration panel -> 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. To create a new parameter, navigate to “Add new parameter” box and you will see this screen:
The Title section is what will be displayed on your insightboard as a filter name and is a required field.
The 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 underscore, so no blank spaces.
In the Selector section you define the type of filter you would like to use. Currently, you have the following choice:
- 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.
- 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:
- 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.
- 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.
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:
- 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.