Menu

Using 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!

This feature is in pilot and requires version 1.18 or greater of the Flex UI. You can enable team view filters on the pre-release features page within Flex Admin.

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:

Flex.TeamsView.defaultProps.filters = [
    Flex.TeamsView.activitiesFilter,
    // ... custom filters here
];

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:

interface FilterDefinition {
   id: string;
   title: React.ReactChild;
   fieldName: string;
   type?: FiltersListItemType;
   options?: Array;
   customStructure?: CustomFilterItemStructure;
   condition?: string;
}
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.

interface FilterDefinitionOption {
   value: string;
   label: string;
   default?: boolean;
}
Field Description
value

Value of the filter option.

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.

interface CustomFilterItemStructure {
   field: React.ReactElement;
   label: React.ReactElement;
}

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. A FilterDefinitionFactory is a simple function which returns 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 readding the default activity filter as the first item of the array.

Flex.TeamsView.defaultProps.filters = [
   Flex.TeamsView.activitiesFilter,
   yourFilterDefinitionHere,
   your2ndFilterDefinitionHere,
   your3rdFilterDefinitionHere,
];

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.

Custom Input Fields

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

        
        
        
        

        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.

              
              
              
              

              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.

                    
                    
                    
                    

                    Enable your new filter

                    Once you've configured your filter(s), you can enable them in Flex manager from within the base Plugin file. In this example, the extendFilters function is imported and passed to the Flex Manager.

                          
                          
                          
                          

                          Self-Hosted Flex

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

                                
                                
                                
                                
                                      
                                      
                                      
                                      
                                            
                                            
                                            
                                            
                                                  
                                                  
                                                  
                                                  

                                                  The hidden filter feature is only available in @twilio/flex-ui@1.21.0 and later.

                                                  You can programmatically apply a filter that is hidden from the user, i.e. the user cannot disable it. You could use this feature to restrict supervisors to seeing only their team members on the page. However, note that this is not a security feature. Supervisors still have access to all agent activity using the underlying APIs.

                                                  In the following example, we set up Team View to only show agents with a specific team_name attribute (you can set user attributes via your SSO provider):

                                                  const filter = {
                                                    name: "data.attributes.team_name",
                                                    condition: FilterConditions.CONTAINS,
                                                    values: "sales"
                                                  }
                                                  
                                                  Flex.TeamsView.defaultProps.hiddenFilter = filter
                                                  

                                                  A hidden filter definition has the following properties:

                                                  name Required. A string representing the subject of your query. For example, "data.attributes.roles", "data.attributes.full_name" or "data.activity_name".
                                                  condition

                                                  Required. A parameter that represents the query comparison operator such as IN, NOT_IN, CONTAINS. See Query Operators to learn about other possible condition values.

                                                  values

                                                  Required. A string representing the object of the query.

                                                  If you require a more elaborate hidden filter, you can also pass an array of filters or form your own live query and pass it as a string, e.g.:

                                                  Flex.TeamsView.defaultProps.hiddenFilter = '(data.attributes.roles CONTAINS "agent-sales") AND (data.activity_name IN ["Available"])'
                                                  

                                                  Rate this page:

                                                  Thanks for rating this page!

                                                  We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                                                  Need some help?

                                                  We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.