Dynamically Initializing Dropdown or a Slicer Filter in Embed Tokens

Introduction

It may be desired to fix a filter to certain values so that the dashboard shows only that specific data when opening it. This customization is facilitated through the Access Control Layer's Embed Tokens, enabling dynamic filter initialization based on user-specific criteria. Setting this up via the token allows you to set a different selection based on the specific user looking at the dashboard. This may be particularly interesting when the values available are different per user.

Initializing Filters through Embed Tokens

You can specify the initialization filter in the authorization request and use the received authorization key and token to embed a template dashboard that has a user-specific initialization of a Dropdown or Slicer filter in it!

This Developer documentation guide shows the complete authorization request needed to initialize a certain widget.

Initializing with Datetime values

For filters that operate on datetime values, use the expression "? between ?" to define time ranges. This setup is ideal for multiselect filters, like the default setting for Slicer filters, allowing you to select multiple time ranges simultaneously.

Example for Multiselect Filters:

The first example of an initialization filter is valid for multiselect filters (i.e. default setting for Slicer filters). An array or arrays is required in order to define the start and end of the multiple time ranges.

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "? between ?",
  "value": [
	  // selecting range 1, 2017
	  [
		  "2017-01-01T00:00:00.000Z", // start of range 1
		  "2018-01-01T00:00:00.000Z"  // end of range 1
	  ],
	  // selecting range 2, 2019
	  [
		  "2019-01-01T00:00:00.000Z", // start of range 2
		  "2020-01-01T00:00:00.000Z"  // end of range 2
	  ]
  ]
}

Example for Single-Select Filters:

For single-select Dropdown filters (default setting for Dropdown filters) you can specify only one range in the value property, esentially using a single aray inside the base array.

{
   "clause":"where",
   "chart_id":"< chart id of a filter object contained in the dashboard >",
   "expression":"? between ?",
   "value":[
      [
         "2023-11-01T00:00:00.000Z", // start of range
         "2023-12-01T00:00:00.000Z" // end of range
      ]
   ]
}

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

Initializing with Hierarchy values

For filters based on hierarchy values, such as categories or groups, use the expression "? in ?".

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "? in ?",
  "value": [
	  "online payment"
  ]
}

Initializing with Numeric values

Numeric filters can also be initialized through Embed Tokens, using the "? in ?" expression to set the filter to specific numbers.

{
  "clause": "where",
  "chart_id": "< chart id of a filter object contained in the dashboard >",
  "expression": "? in ?",
  "value": [
	  3
  ]
}

Clearing initialization filter

Sometimes, it may be necessary to clear a filter that was previously defined in the dashboard editor. This can be done through the Embed Token by specifying the filter's chart_id and setting the origin to "clear".

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

Conclusion

Embed Tokens not only facilitate secure access to Luzmo's dashboards but also enable a high degree of customization through dynamic filter initialization. By leveraging this feature, you can ensure that each user is greeted with a dashboard view that's directly relevant to their needs, enhancing their interaction with your application's data visualizations.

For more detailed guidance on setting up Embed Tokens and initializing filters, please refer to the Luzmo Developer Documentation.