Filters

The filter is used to limit the set of records to be displayed in the list (for example, in the related list, or the dictionary). The filter sets certain conditions for the record to meet to be in the list. Filters can be configured with the condition builder.

For example, you need to filter users living in Moscow. In SQL, we use the WHERE operator to filter records.

tip

You can add a filter with all necessary conditions in your Favorites in the navigation menu. To do so, drag the breadcrumbs to the Favorites navigation tab.

Filter instruments

---

Filters consist of the following instruments:

1. Condition builder (and the breadcrumbs as its integral part).
2. Search and sorting:
   1. Input field at the top of every column is used for searching.
   2. Click on the column title to sort the search results.
3. Filter Out/Show Matching (this item can be found in the context menu, to open it, right-click the list cell).

All these components form the condition string that is sent in the request as a GET parameter. The filtered list of records is returned and displayed.

The difference between the condition builder on lists and the regular condition builder is that breadcrumbs and sorting functionality are added.

The breadcrumbs allow assessing the filter visually. Also, they allow for quick filter editing by navigation to the condition specified.

The sorting allows you to add its conditions (ascending or descending) on one or more list fields.

How filters work

---

For example, you need to find John Doe's registered requests with the Low or Moderate priority, sorted by priority.

To do so, create the following filter for the Request (itsm_request) table:

After that, the condition string can be found in the condition GET parameter. The browser adds %3D, %5E, %E to encode special symbols.

GET

/list/task?condition=(state%3D-2%5Epriority<3%5Eassigned_user%3D160114171110151)%5EORDERBYDESCpriority

Element	Description
state%3D-2	State is Registered
priority<3	The set of records with Priority value less than 3 will be displayed (Moderate and Low)
assigned_user%3D160114171110151	The record ID of the user.
ORDERBYDESCpriority	The records will be sorted by the Priority field in descending order.

The filtering for the fields of the Reference, List, Choice, Record Class, and Field Name types has some specifics. It is related to the value and display_value fields correlation:

1. The filtering is performed by the value of the value field. For example, the filter condition is field_name = value, the displayed condition will be field_title = display_value.
2. The column search is performed by the value of the display_value field; either the filter or the breadcrumbs above it are filled with the condition field_name = value; at the same time, the condition displayed is field_title = display_value.
3. Auto-suggest is performed using the values of the value or display_value fields.

The table below explains the features of filtering when selecting the fields of the above types.

Column type	Operator	Search field
Reference	LIKE / NOTLIKE / STARTSWITH / ENDSWITH	display_value
List	LIKE / NOTLIKE	display_value
Choice	LIKE / NOTLIKE / STARTSWITH / ENDSWITH	title
Record Class	LIKE / NOTLIKE / STARTSWITH / ENDSWITH	title

See the Condition Operators article to obtain the full list of filter operators.

Dynamic filters

---

Dynamic filters extend the filters by executing JavaScript scripts. This ability is available in the list condition builder and in the dynamic reference qualifier condition builder.

In the condition builder, dynamic filters are available when selecting the reference field and the 'is (dynamic)' or similar operator. After this, the list of available dynamic filters appears.

Dynamic filter scripts return a value that is used in place of the dynamic filter when filtering.

To create a new dynamic filter, complete the following steps:

1. Navigate to System Settings → Dynamic Filter Options.
2. Click New and fill in the fields.
3. Click Save or Save and exit to apply the changes.

As a result, a new record is created in the Dynamic Filter Options (sys_filter_option_dynamic) table.

note

You can also create dynamic filters for table ID fields. To do so, specify the dynamic filter form fields in the following way:

1. In the Column type, select Big Integer from the list.
2. In the Reference table, specify the table to apply this filter on.
3. Select the Active checkbox.
4. Select the Available for filter checkbox.
5. Enter the script, complete filling in the form and click Save.

To apply the dynamic filter created, specify the ID table column and the is (dynamic) operator in the condition builder.

Dynamic filters form fields

Field	Mandatory	Description
Title	Y	Specify the filter title.
Column type	N	Specify the column type used in this filter. This field references the Columns dictionary.
Referenced table	Y	Select the table to apply this filter on.
Available for filter	N	Select this checkbox to make this filter available in the filters list.
Available for reference qualifier	N	Select this checkbox to make this filter available for a dynamic reference qualifier.
Active	N	Select this checkbox to make the filter active.
Order	N	Enter the number to set the list output order.
Script	Y	Enter the script that the dynamic filter runs. You can use all methods of server-side API classes here. The current object is available for already existing and newly created record forms and contains entered field values. To use the current object, select the Available for reference qualifier checkbox. After executing, the script should return the record ID or array of IDs. There is a feature for JavaScript that the ID must be a string, since the ID is a large number.