Customize Date Filters in KPI Dashboards

Contents:

You can customize the date filter by updating the JSON structure of the date filter metadata (MD) object via API. You can:

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=1
  • For an already created dashboard:
    https://secure.gooddata.com/gdc/md/<workspace_ID>/obj/<KPI_dashboard_ID>

    For the list of KPI Dashboards, go to https://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 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
Floating rangerelativeForm
Predefined periodsrelativePresets
* The static period you set is added to the relativePresests section of the JSON structure.

Edit granularities in the floating range

The floating range includes granularities that can be days, months, quarters, and years in the following format:

"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 floating range 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 floating range.

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, months, quarters, and years in the following format:

    "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.monthFour months 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

    If 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.

  • visible that specifies if the filter is available in the dashboard

The code below shows a new preset that filters to last 10 days.

{
                        "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 "Floating range " renamed to "Set a floating filter".

"relativeForm" : {
                     "granularities" : [
                        "GDC.time.month",
                        "GDC.time.year",
                        "GDC.time.quarter",
                        "GDC.time.date"
                     ],
                     "localIdentifier" : "relativeForm",
                     "name" : "Set a floating 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. Static filter and floating range 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.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" : false
                     },
                     {
                        "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.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"
               }

After the update, your date filter options will look like this: