Resources »

Guides »

Dashboards »

Configure dashboard filters

Introduction

As of 9.0.4, user-editable custom filters can be added to the top of workspace dashboards. These filters automatically apply to all of the dashboard’s widgets. Previously, each widget had to be filtered individually.

Each dashboard filter is associated with a new placeholder that can be used when configuring queries widgets (e.g. search queries, data queries).

For example, a reporting dashboard can provide filters for a date range, date grouping (e.g. year/month/day), and a specific list of workers. Its various charts and worklists will adapt in real-time to changes in those filters from a single place.

The current state of a dashboard’s filters is remembered per worker between pages (and sessions). The owner of the dashboard configures the initial defaults for each filter.

Configuring dashboard filters

Dashboard filters are configured on a dashboard by clicking the Edit Dashboard button.

They are defined by using a very simple text-based format known as YAML1:



---
placeholder: input_date_range
label: "Date range:"
type: date_range
default: first day of this month -12 months
---
placeholder: input_date_subtotal_by
label: "By:"
type: picklist
default: month
params:
  options: [day, week, month, year]
--- 
placeholder: input_groups
label: "Groups:"
type: chooser
default:
params:
  context: group
  single: false


This is a collection of key: value pairs, with each record starting with --- on its own line.

Each filter may have the following keys:

  • placeholder: The name of this dashboard filter when used in queries on widgets. This should be a lowercase string containing only letters, numbers, and underscores (_).

  • label: The human-friendly name of this filter.

  • type: The type of the filter. This is covered in more detail below.

  • default: The default value of this filter when the dashboard is viewed for the first time by a worker.

  • params: An optional list of parameters based on the filter type. This is another set of key: value pairs indented with two leading spaces.

Filter types

chooser

When filtering with a chooser, the user selects one or more records using a helper popup.



--- 
placeholder: input_groups
label: "Groups:"
type: chooser
default:
params:
  context: group
  single: false


The available params: are:

  • context: a record type alias.

  • single: true for single record selection, false (default) for multiple.

The value of the placeholder is a comma-separated list of record IDs. You’d use it in a query like:



type:worklist.subtotals
of:tickets
by:[created@month,group]
query:(
	created:"-1 year to now"
	{% if input_groups %}
	group.id:[{{input_groups}}]
	{% endif %}
)
format:timeseries


date_range

When filtering with a date range, the user enters a start and end date (inclusive). One-click presets are provided for common ranges (e.g. past day/month/year). The dates can be absolute (e.g. 2019-12-31, Jan 1 2019) or relative (e.g. -1 year, today, now, next Friday, first day of this month -1 year).



---
placeholder: input_date_range
label: "Date range:"
type: date_range
default: first day of this month -12 months


This filter doesn’t currently have any configurable parameters.

The value of the placeholder is a text string with format "date1 to date2". This is suitable for passing directly to any date-based filters. Be sure you wrap it in quotes (" ").



type:worklist.subtotals
of:tickets
by:[created@month,group~10]
query:(
	created:"{{input_date_range}}"
)
format:timeseries


picklist

When filtering by picklist, the user selects one item from a pre-defined list of options.



---
placeholder: input_date_subtotal_by
label: "By:"
type: picklist
default: month
params:
  multiple: false
  options: [day, week, month, year]


The available params: are:

  • multiple: true if multiple selection is enabled, false (default) otherwise.

  • options: a list of possible values for the picklist.

      
    	
      params:
        options: [day, week, month, year]
    	
      
      
      
    	
      params:
        options:
          - day
          - week
          - month
          - year
    	
      
      

    As of 9.1.3 you can also provide a map of labels and values:

      
    	
      params:
        options:
            "Open": o
            "Waiting": w
            "Closed": c
            "Deleted": d
    	
      
      

In single selection mode (multiple: false), the value of the placeholder is the selected option:



type:worklist.subtotals
of:tickets
by:[created@{{input_date_subtotal_by}},group~10]
query:(
	created:"first day of this month -1 year to now"
)
format:timeseries


In multiple selection mode (multiple: true), the value of the placeholder is an array of selected options:



type:worklist.subtotals
of:tickets
by:[created@day,group~10]
query:(
	created:"first day of this month -1 year to now"
	{% if input_statuses %}
	status:[{{input_statuses|join(',')}}]
	{% endif %}
	status:[]
)
format:timeseries


References