Skip to content Skip to navigation Skip to topbar

On this page

Advanced Team View Filters

Team View Filters allow supervisors to search or filter their agents by name or activity. You can also use custom, programmatically defined filter criteria, like teams or skills. This page describes the main concepts involved in customizing Team View Filters, and includes some sample code you can use to get started with the feature. For more information about using Team View Filters, check out the End User Guide!

(warning)

Warning

This feature is in pilot between version 1.18 and version 1.26.3 of the Flex UI. You can enable team view filters on the pre-release features page within Flex Admin. This feature is enabled by default for version 1.27.0 and upper.

Key Concepts

Flex uses the following objects and components to generate Team View Filters:

TeamFiltersPanel

The portion of the Flex UI that shows the Team Filters. It is a child component of the Supervisor UI. By default, Flex allows you to filter by agent Activity, but you can add custom filters to the panel by modifying the defaultProps, like so:

1Flex.TeamsView.defaultProps.filters = [
2    Flex.TeamsView.activitiesFilter,
3    // ... custom filters here
4];
5

FilterDefinition

A FilterDefinition is a structure that tells Flex how to render the new filter label and field, and what to query the field value against. Each field will add a new condition to the Sync query that will render the agents (or workers) list to the UI. A FilterDefinition has the following structure:

1interface FilterDefinition {
2   id: string;
3   title: React.ReactChild;
4   fieldName: string;
5   type?: FiltersListItemType;
6   options?: Array;
7   customStructure?: CustomFilterItemStructure;
8   condition?: string;
9}
10

Field	Description
`id`	Required. A string representing the subject of your query. This identifies the values to filter for in the Flex app state based on your specified attribute or field. For example, "data.attributes.full_name" or "data.activity_name".
`title`	Required. A string that is rendered as the filter display name on the Filters side panel. For example, "Names".
`fieldName`	Required. A string representing the input name passed to the predefined filters. For example, "full_name".
`type`	Required if `customStructure` isn't defined. Currently only supports "multiValue". This renders a list of checkboxes for each option you provide.
`options`	Required if type is "multiValue". An array of filter definition options used for rendering the checkbox fields, their values, their labels, and whether they are selected by default.
`customStructure`	Required if `type` isn't set. An object of type CustomFilterItemStructure used for rendering custom fields. This lets you add your own custom fields.
`condition`	An optional parameter that represents the query comparison operator such as `IN`, `NOT_IN`, `CONTAINS`. See Query Operators to learn about other possible condition values. This represents the condition to be used in building the query. For instance, `data.activity_name IN ["available"]` or `data.attributes.full_name CONTAINS "John"`. In the latter example, "data.attributes.full_name" is the `id`, "CONTAINS" is the `condition`, and "John" is the value to filter for.

FilterDefinitionOption

Describes the available options which can be used as a filter. For example, if you wanted to filter by agent languages, you could create an option for each language spoken in your contact center.

1interface FilterDefinitionOption {
2   value: string;
3   label: string;
4   default?: boolean;
5}

Field	Description
`value`	Value of the filter option. When using `IN` or `NOT_IN` to build your query and you are providing an array of options, you need to omit the first and the last instances of double quotes in your string. See example in Add a multivalue field
`label`	Friendly name of the option.
`default`	A Boolean value indicating whether the filter option should be selected by default.

CustomFilterItemStructure

To add a custom field and label to a filter, you'll need an object with a select field or an input field passed to the CustomFilterItemStructure.

1interface CustomFilterItemStructure {
2   field: React.ReactElement;
3   label: React.ReactElement;
4}
5

field is a React element that should render an input usable by the final customer. It inherits a few custom props from Flex.

Field	Description
name	The field name set in the FilterDefinition.
`handleChange`	A function that gets invoked on this custom field change event. It requires the new value of the filter to be passed as an argument, either as an array of strings or a string.
`options`	The same options passed in the FilterDefinition, if provided.
`currentValue`	The current value of the filter. It can either be an array of strings or a string, depending on what the `props.handleChange` function receives once invoked.

label is another React element that serves as the label of the filter. It should indicate the content of the filter when the accordion item is closed. It receives the following properties:

Field	Description
`currentValue`	The current value of the filter.
`activeOption`	is the options array that is provided and returns the entire selected option. It will contain `currentValue` as value.

FilterDefinitionFactory

The filters array also accepts FiltersDefinitionFactories, which are functions that return a FilterDefinition. You can write a FilterDefinitionFactory that fetches data from the app state and dynamically renders values or options of a field.

Your factory must accept two arguments:

Argument	Description
appState	The entire Flex Redux state. Use this to access information about activities, session, and more details about the current state of your Flex instance.
ownProps	The props received by the TeamFiltersPanel.

Customizing your Filters

The TeamFiltersPanel includes activitiesFilter by default. To add a new filter to the TeamsFiltersPanel, you can overwrite the defaultProps.filters property with a new array of filter definitions before rendering your Flex instance.

This array can contain both FilterDefinitions and FilterDefinition factories. In this example, we are reading the default activity filter as the first item of the array.

1Flex.TeamsView.defaultProps.filters = [
2   Flex.TeamsView.activitiesFilter,
3   yourFilterDefinitionHere,
4   your2ndFilterDefinitionHere,
5   your3rdFilterDefinitionHere,
6];
7

Add a custom input field

Initially, the FilterDefinition has one predefined type, which will output checkboxes: MultiValue. With custom input fields, you can add a different type of input, like a custom text input field.

An example of a custom input field, name, where you can type and filter by names based on the condition that you specify

The following file describes the HTML for your custom field, as well as the JavaScript associated with its behavior. In this sample, the filter functionality is extended in the extendFilters function

Add a multivalue field

The following example will filter by agents located in any of the options specified in the value field:

1import React from "react";
2import { TeamsView } from "@twilio/flex-ui";
3import { FiltersListItemType } from "@twilio/flex-ui";
4
5// Define a new filter that uses the custom field
6
7const teamFilter = {
8    fieldName: "team_location",
9    title: 'Team',
10    id: 'data.attributes.squad',
11    type: FiltersListItemType.multiValue,
12    options: [
13        { label: 'Canada', value: 'CAN-1", "CAN-2", "ARC'}
14    ],
15    condition: 'IN',
16};
17
18// Export a function to be invoked in plugin's main entry-point
19export const extendFilter = (manager) => {
20    manager.updateConfig({
21        componentProps: {
22            TeamsView: {
23                filters: [
24                    TeamsView.activitiesFilter,
25                    teamFilter,
26                ]
27            }
28        }
29    })
30};

Use a filter definition factory

You can use a filter definition factory to dynamically render the options of the predefined checkboxes fields. For example, you could render the activities that are currently available on in the Flex Redux store.

Create a Filter Definition Factory Function

1import React from "react";
2
3import { FiltersListItemType } from "@twilio/flex-ui";
4
5const customActivityFilter = (appState, teamFiltersPanelProps) => {
6    const activitiesArray = Array.from(appState.worker.activities.values());
7
8    const activities = (activitiesArray).map((activity) => ({
9        value: activity.name,
10        label: activity.name,
11        default: !!activity.available,
12    }));
13
14    return {
15        id: "data.activity_name",
16        fieldName: "custom_activity_name",
17        type: FiltersListItemType.multiValue,
18        title: "Activities",
19        options: activities
20    };
21};
22
23// Export a function to be invoked in plugin's main entry-point
24export const extendFilter = (manager) => {
25    manager.updateConfig({
26        componentProps: {
27            TeamsView: {
28                filters: [
29                    customActivityFilter,
30                ]
31            }
32        }
33    })
34};

Use a custom filter structure with a filter definition factory

You can use custom filter input components and filter definition factories together. The following code sample dynamically renders the options of a select field from the current Redux store.

Combine Filter Definition Factor and Custom Filters

1import React from "react";
2
3// Create your custom field
4const CustomField = ({ handleChange, currentValue, fieldName, options }) => {
5    const _handleChange = (e) => {
6        e.preventDefault();
7        handleChange(e.target.value);
8    };
9
10    return (
11        <select
12            className="CustomInput"
13            onChange={_handleChange}
14            value={currentValue}
15            name={fieldName}
16        >
17            <option value="" key="default">All activities</option>
18            {options.map(opt => (
19                <option value={opt.value} key={opt.value}>{opt.label}</option>
20            ))}
21        </select>
22    )
23};
24
25// Define the label that will be displayed when filter is active
26const CustomLabel = ({ currentValue }) => (
27    <>{currentValue || "All activities"}</>
28);
29
30// Define the available properties upon which to filter based on application state
31const customActivityFilter = (appState, teamFiltersPanelProps) => {
32
33    const activitiesArray = Array.from(appState.worker.activities.values());
34
35    const activities = (activitiesArray).map((activity) => ({
36        value: activity.name,
37        label: activity.name,
38        default: !!activity.available,
39    }));
40
41    return {
42        id: "data.activity_name",
43        fieldName: "custom_activity_name",
44        title: "Activities",
45        customStructure: {
46            label: <CustomLabel />,
47            field: <CustomField />,
48        },
49        options: activities
50    };
51};
52
53// Add new filter to TeamFiltersPanel in the Flex UI
54export const extendFilter = (manager) => {
55    manager.updateConfig({
56        componentProps: {
57            TeamsView: {
58                filters: [
59                    customActivityFilter,
60                ]
61            }
62        }
63    })
64};

Extend Filters with a Plugin

1import Flex from '@twilio/flex-ui';
2import { FlexPlugin } from 'flex-plugin';
3import { extendFilter } from "./CustomFilters";
4
5const PLUGIN_NAME = 'SamplePlugin';
6
7export default class SamplePlugin extends FlexPlugin {
8  constructor() {
9    super(PLUGIN_NAME);
10  }
11
12  /**
13   *
14   * @param flex
15   * @param {Manager} manager
16   */
17  init(flex, manager) {
18      extendFilter(manager);
19  }
20}

Self-Hosted Flex

The following code samples demonstrate writing and calling the same extendFilters functions, but in the context of self-hosted Flex.

Define a Custom Filter (Self-Hosted)

1import React from "react";
2import Flex from "@twilio/flex-ui";
3
4// Define an Input component; returns a simple input HTML element with logic to handle changes when users enter input
5const Input = ({ handleChange, currentValue = "", fieldName }) => {
6   const _handleChange = (e) => {
7       e.preventDefault();
8       handleChange(e.target.value);
9   };
10
11   return (
12       <input
13           className="CustomInput"
14           type="text"
15           onChange={_handleChange}
16           value={currentValue}
17           name={fieldName}
18       />
19   )
20};
21
22// Define the label that supervisors will see when using our custom filter
23const CustomLabel = ({ currentValue }) => (
24  <>{currentValue && currentValue.length ? `Containing "${currentValue}"` : "Any"}</>
25);
26
27
28// Define a new filter that uses the custom field
29const nameFilter = {
30   id: "data.attributes.full_name",
31   fieldName: "full_name",
32   title: "Names",
33   customStructure: {
34       field: <Input />,
35       label: <CustomLabel />,
36   },
37   condition: "CONTAINS"
38};
39
40// Add the filter to the list of filters in the TeamFiltersPanel
41export const extendFilter = () => {
42   Flex.TeamsView.defaultProps.filters = [
43       Flex.TeamsView.activitiesFilter,
44       nameFilter,
45   ];
46};

Create a Filter Definition Factory (Self-Hosted)

1import React from "react";
2import Flex from "@twilio/flex-ui";
3
4const customActivityFilter = (appState, teamFiltersPanelProps) => {
5   const activitiesArray = Array.from(appState.worker.activities.values());
6
7   const activities = (activitiesArray).map((activity) => ({
8       value: activity.name,
9       label: activity.name,
10       default: !!activity.available,
11   }));
12
13   return {
14       id: "data.activity_name",
15       fieldName: "custom_activity_name",
16       type: Flex.FiltersListItemType.multiValue,
17       title: "Activities",
18       options: activities
19   };
20};
21
22
23export const extendFilter = () => {
24    Flex.TeamsView.defaultProps.filters = [
25        customActivityFilter,
26    ];
27};

Combine Filter Definition Factories and Custom Input (Self-Hosted)

1import React from "react";
2import Flex from "@twilio/flex-ui";
3
4// Create your custom field
5const CustomField = ({ handleChange, currentValue, fieldName, options }) => {
6   const _handleChange = (e) => {
7       e.preventDefault();
8       handleChange(e.target.value);
9   };
10
11   return (
12       <select
13           className="CustomInput"
14           onChange={_handleChange}
15           value={currentValue}
16           name={fieldName}
17       >
18           <option value="" key="default">All activities</option>
19           {options.map(opt => (
20               <option value={opt.value} key={opt.value}>{opt.label}</option>
21           ))}
22       </select>
23   )
24};
25
26// Define the label that will be displayed when filter is active
27const CustomLabel = ({ currentValue }) => (
28  <>{currentValue || "All activities"}</>
29);
30
31// Define the available properties upon which to filter based on application state
32const customActivityFilter = (appState, teamFiltersPanelProps) => {
33
34   const activitiesArray = Array.from(appState.worker.activities.values());
35
36   const activities = (activitiesArray).map((activity) => ({
37       value: activity.name,
38       label: activity.name,
39       default: !!activity.available,
40   }));
41
42   return {
43       id: "data.activity_name",
44       fieldName: "custom_activity_name",
45       title: "Activities",
46       customStructure: {
47           label: <CustomLabel />,
48           field: <CustomField />,
49       },
50       options: activities
51   };
52};
53
54// Add new filter to TeamFiltersPanel in the Flex UI
55export const extendFilter = () => {
56   Flex.TeamsView.defaultProps.filters = [
57       customActivityFilter,
58   ];
59};

Extend Filters in Self-Hosted Flex

1import { extendFilter } from "./CustomFilters";
2
3export function run(config) {
4   const container = document.getElementById("container");
5
6   return Flex
7       .progress("#container")
8       .provideLoginInfo(config, "#container")
9       .then(() => Flex.Manager.create(config))
10       .then(manager => {
11
12           // Extending the filter functionality
13           extendFilter();
14
15           ReactDOM.render(
16               <Flex.ContextProvider manager={manager}>
17                   <Flex.RootContainer />
18               </Flex.ContextProvider>,
19               container
20           );
21       })
22       .catch((e) => {
23           console.log("Failed to run Flex", e);
24       });
25}

Advanced Team View Filters

Warning

Key Concepts

TeamFiltersPanel

FilterDefinition

FilterDefinitionOption

CustomFilterItemStructure

FilterDefinitionFactory

Customizing your Filters

Add a custom input field

Add a custom filter

Add a multivalue field

Use a filter definition factory

Create a Filter Definition Factory Function

Use a custom filter structure with a filter definition factory

Combine Filter Definition Factor and Custom Filters

Enable your new filter

Extend Filters with a Plugin

Self-Hosted Flex

Define a Custom Filter (Self-Hosted)

Create a Filter Definition Factory (Self-Hosted)

Combine Filter Definition Factories and Custom Input (Self-Hosted)

Extend Filters in Self-Hosted Flex

Hidden Filter

Warning