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.

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=1

  • For an already created dashboard:  https://secure.gooddata.com/gdc/md/workspace_ID/obj/KPI_dashboard_ID

Each filter, or part of a filter, is identified by:

  • localIdentifier - a unique identifier of a filter within the JSON structure
  • name - 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 nameJSON name
All timeallTime
Static periodrelativePresets *
Relative periodrelativeForm
Predefined periodsrelativePresets
* 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
                  },

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:

  • granularity 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"

  • from and to that 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:

    FromToGranularityNotes
    -20GDC.time.dateLast 3 days
    03GDC.time.week_usFour weeks ahead
    -21GDC.time.monthTwo months ago to 1 month ahead
    -1-1GDC.time.quarterLast quarter
    00GDC.time.yearThis year
  • localIdentifier that is a unique name within the date filter MD object

  • name of the filter that displays in the KPI Dashboard

  • visible that 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
                  },

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"

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"
               }
            }
         }