Dynamically initializing a Date filter in the Authorization request

Initializing a Date filter in the Authorization request and integrating the dashboard with the received key and token enables you to have prefiltered template dashboard(s) to a certain date range but still allowing your user to alter the range.

Depending on whether you'd like to initialize it to a predefined range (e.g. "Today", "This month", "Previous year", "Last 90 days", etc.) or to a custom range, you'd need to specify a different initialization filter in the Authorization request.

All authorization intialization filter possibilities for the Date filter are shown below!

More information on the date filter and its settings can be found in this Academy article, this Developer documentation guide shows the complete authorization request needed to initialize a certain widget.

Initialize to a predefined range

The image below shows some examples of such predefined date ranges, but you can add/change/remove any range you'd like to provide to your end-users.

The "unit" values in the code snippets below all represent date levels, where a unit of 1 is equal to year and a unit of 9 is equal to millisecond level.

Today

{
  "clause": "where",
   "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "last_now",
  "value": {
    "unit": 5,  // 5 = day
    "quantity": 0
  }
}

Yesterday

{
  "clause": "where",
   "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "ago",
  "value": {
    "unit": 5,  // 5 = day
    "quantity": 1
  }
}

Tomorrow

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "next_full",
  "value": {
    "unit": 5,  // 5 = day
    "quantity": 1
  }
}

This year/quarter/month/week

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "last_now",
  "value": {
    "unit": 1,  // 1 - 4 = year - week
    "quantity": 0
  }
}

Previous year/quarter/month/week

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "last_completed",
  "value": {
    "unit": 1,  // 1 - 4 = year - week
    "quantity": 1
  }
}

Next year/quarter/month/week

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "next_full",
  "value": {
    "unit": 1,  // 1 - 4 = year - week
    "quantity": 1
  }
}

Last (x) periods

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "last_now",
  "value": {
    "unit": 4,   // 4 = week
    "quantity": 3 // Number of units - 1 (first unit is "quantity": 0)
  }
}

Next (x) periods

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "next_now",
  "value": {
    "unit": 4,   // 4 = week
    "quantity": 3 // Number of units - 1 (first unit is "quantity": 0)
  }
}

Initialize to a custom range

If you'd like to initialize the Date filter with a custom range (as shown below), you should specify two initialization filters in the authorization request, where one uses the "? >= ?" expression where you can define the lower threshold and the other uses the "? <= ?" expression to define the upper threshold.

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "? >= ?",
  "value": "2020-01-01T00:00:00.000Z"
},
{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "? <= ?",
  "value": "2020-12-31T23:59:59.999Z"
}

Clearing initialization filter specified in the dashboard editor

{
  "origin": "clear",
  "chart_id": "<chart_id_of_filter_widget_to_be_cleared>"
}

Important note: As you will be specifying the time in the Zulu format, please ensure that the time on the token is offset to match the one in the dashboard. For example, if the time in your dashboard is set to "UTC+2", you will need to subtract 2 hours from the time you want to set on the dashboard, specifying "2024-30-01T22:00:00.000Z" instead of "2024-31-01T00:00:00.000+02:00".