Customize Date Filters in KPI Dashboards
You can customize the date filter by updating the JSON structure of the date filter metadata (MD) object via API. You can:
- Add, edit, and remove granularities in the relative period
- Add, edit, and remove filters in predefined periods
- Rename filters
- Set a default filter for new KPI Dashboards
For the default JSON structure, see the section Default date filter JSON structure at the end of this article.
Any change to the date filter affects only newly created KPI Dashboards in the workspace.
To edit an already created dashboard, edit the date filter MD object of this specific dashboard.
Date filter metadata object
You can find the date filter MD objects at:
For the whole workspace:
https://secure.gooddata.com/gdc/md/workspace_ID/objects/query?category=dateFilterConfig&limit=1For an already created dashboard:
https://secure.gooddata.com/gdc/md/workspace_ID/obj/KPI_dashboard_IDFor the list of KPI Dashboards, go tohttps://secure.gooddata.com/gdc/md/workspace_ID/query/analyticaldashboard
Each filter, or part of a filter, is identified by:
localIdentifier- a unique identifier of a filter within the JSON structurename- the name of the filter that displays in the KPI Dashboard If you leave the name empty, the dashboard creates the name. If you add your own name, update the localized versions as well. For details see Metadata Localization.
The type of the filters correspond with the following JSON names:
| KPI Dashboard name | JSON name |
|---|---|
| All time | allTime |
| Static period | relativePresets * |
| Relative period | relativeForm |
| Predefined periods | relativePresets |
* The static period you set is added to the relativePresests section of the JSON structure. | |
Edit granularities in the relative period
The relative period includes granularities that can be days, weeks, months, quarters, and years in the following format:
"GDC.time.week_us", “GDC.time.month”, “GDC.time.year”, “GDC.time.quarter”, “GDC.time.date”
If you want to remove any granularity, delete the item from the relativeForm section. The code below shows the relative period with only months and years.
"relativeForm" : {
"granularities" : [
"GDC.time.month",
"GDC.time.year"
],
"localIdentifier" : "relativeForm",
"name" : "relativeForm",
"visible" : true
},
The first item in the list of granularities will be selected when switching to the relative period.
Add predefined periods
In the relativePresets section of the JSON structure, you edit the predefined periods of the date filter.
Each predefined period consists of the following:
granularitythat can be days, weeks, months, quarters, and years in the following format:"GDC.time.week_us", "GDC.time.month", "GDC.time.year", "GDC.time.quarter", "GDC.time.date"fromandtothat specifies the length of the period based on the granularity and relative to today Based on the granularity, the number specifies the distance from today (which is always zero). Here are some examples:From To Granularity Notes -2 0 GDC.time.dateLast 3 days 0 3 GDC.time.week_usFour weeks ahead -2 1 GDC.time.monthTwo months ago to 1 month ahead -1 -1 GDC.time.quarterLast quarter 0 0 GDC.time.yearThis year localIdentifierthat is a unique name within the date filter MD objectnameof the filter that displays in the KPI DashboardIf you leave the name empty, the default name is used instead. If you display GoodData portal in several languages, update the languages as well. For details see Metadata Localization.visiblethat specifies if the filter is available in the dashboard
The code below shows a new preset that filters to last 10 days and is visible on the dashboard.
{
"from" : -9,
"granularity" : "GDC.time.date",
"localIdentifier" : "last_10_days",
"name" : "Last 10 days",
"to" : 0,
"visible" : true
},
Rename filters
To rename a date filter or part of the date filter, edit the name parameter for this filter. If you leave the name empty, the will be created automatically.
The code below shows the “Relative period " renamed to “Set a relative filter”.
"relativeForm" : {
"granularities" : [
"GDC.time.month",
"GDC.time.year",
"GDC.time.quarter",
"GDC.time.date"
],
"localIdentifier" : "relativeForm",
"name" : "Set a relative filter",
"visible" : true
},
If you display GoodData portal in several languages, update the languages after renaming as well. For details, see Metadata Localization.
To rename a filter on an already created KPI Dashboard, hide or delete the filter and create a new one with your preferred name.
Change the default filter for new dashboards
The selectedOption parameter determines which date filter shows as default for newly created KPI dashboards.
By default, all new KPI Dashboards are filtered to This month.
To change the default filter, add its localIdentifier to the selectedOption parameter.
"selectedOption" : "relative_last_7_days"
Filters included in the selectedOption parameter must be visible. If the filter in the selectedOption parameter is deleted or not visible, KPI Dashboards will use the workspace default date filter instead.
Static filter and relative period cannot be set as selectedOption.
Default date filter JSON structure
The JSON structure for the date filter consists of the definition of individual filters.
You can use the following default JSON structure as a reference or to update your date filter.
{
"dateFilterConfig" : {
"content" : {
"absoluteForm" : {
"localIdentifier" : "absoluteForm",
"name" : "absoluteForm",
"visible" : true
},
"allTime" : {
"localIdentifier" : "allTime",
"name" : "allTime",
"visible" : true
},
"relativeForm" : {
"granularities" : [
"GDC.time.week_us",
"GDC.time.month",
"GDC.time.year",
"GDC.time.quarter",
"GDC.time.date"
],
"localIdentifier" : "relativeForm",
"name" : "relativeForm",
"visible" : true
},
"relativePresets" : [
{
"from" : -6,
"granularity" : "GDC.time.date",
"localIdentifier" : "relative_last_7_days",
"name" : "Last 7 days",
"to" : 0,
"visible" : true
},
{
"from" : -29,
"granularity" : "GDC.time.date",
"localIdentifier" : "relative_last_30_days",
"name" : "Last 30 days",
"to" : 0,
"visible" : true
},
{
"from" : -89,
"granularity" : "GDC.time.date",
"localIdentifier" : "relative_last_90_days",
"name" : "Last 90 days",
"to" : 0,
"visible" : true
},
{
"from" : 0,
"granularity" : "GDC.time.week_us",
"localIdentifier" : "relative_this_week",
"name" : "This week",
"to" : 0,
"visible" : true
},
{
"from" : -1,
"granularity" : "GDC.time.week_us",
"localIdentifier" : "relative_last_week",
"name" : "Last week",
"to" : -1,
"visible" : true
},
{
"from" : -1,
"granularity" : "GDC.time.week_us",
"localIdentifier" : "relative_last_two_weeks",
"name" : "Last two weeks",
"to" : 0,
"visible" : true
},
{
"from" : 0,
"granularity" : "GDC.time.month",
"localIdentifier" : "relative_this_month",
"name" : "This month",
"to" : 0,
"visible" : true
},
{
"from" : -1,
"granularity" : "GDC.time.month",
"localIdentifier" : "relative_last_month",
"name" : "Last month",
"to" : -1,
"visible" : true
},
{
"from" : -11,
"granularity" : "GDC.time.month",
"localIdentifier" : "relative_last_12_months",
"name" : "Last 12 months",
"to" : 0,
"visible" : true
},
{
"from" : 0,
"granularity" : "GDC.time.quarter",
"localIdentifier" : "relative_this_quarter",
"name" : "This quarter",
"to" : 0,
"visible" : true
},
{
"from" : -1,
"granularity" : "GDC.time.quarter",
"localIdentifier" : "relative_last_quarter",
"name" : "Last quarter",
"to" : -1,
"visible" : true
},
{
"from" : -3,
"granularity" : "GDC.time.quarter",
"localIdentifier" : "relative_last_4_quarters",
"name" : "Last 4 quarters",
"to" : 0,
"visible" : true
},
{
"from" : 0,
"granularity" : "GDC.time.year",
"localIdentifier" : "relative_this_year",
"name" : "This year",
"to" : 0,
"visible" : true
},
{
"from" : -1,
"granularity" : "GDC.time.year",
"localIdentifier" : "relative_last_year",
"name" : "Last year",
"to" : -1,
"visible" : true
}
],
"selectedOption" : "relative_this_month"
}
}
}