Real-Time Queues View Programmability

You can customize the Real-Time Queues View to display the queue statistics that you want to monitor in your contact center.

In Flex UI 2.4.0 and later, you can use the Edit view option to filter your view to just the queues and metrics that you want to monitor.

The Edit view panel opens automatically when you access the Real-Time Queues View page for the first time.

Once you've selected your view settings, they're saved in your web browser. Your settings remain saved even if you close the browser, log out, or delete cookies or browser history. However, if you use a different web browser, you must select your settings again in that browser.

In Flex UI 2.5.0 and later, you can choose which summary metrics to highlight in the cards that appear above the table.

On the Edit view > Card tab, select the cards that you want to see. To avoid horizontal scrolling, select 6 or fewer cards. To change the display order, click the 6-dots icon on the right side of the metric category name and drag it up or down the list.

Expand image

View using RealTimeQueues to learn more about using the QueuesStatsView component programmatically.

To filter your queues, navigate to Edit view > Queues and select the queues that you want to see on this page. Use the search field to quickly find queues. When you're done, click Apply to save your changes.

• Select 20 or fewer queues to avoid performance or latency issues.

  • If you have 20 or fewer queues in your account, they're all selected by default.
  • If you have more than 20 queues, the first 20 are selected automatically.

• Only active queues are shown.

Expand image

On the Edit view > Metrics tab, select the metrics that you want to view and monitor. When you're done, click Apply to save your changes.

• Select 8 or fewer metrics. This best practice helps your users avoid horizontal scrolling.

• To see a description of a metric, click the arrow next to the metric name.

  Expand image

• Change the order in which the metrics display by clicking the 6-dots move icon and dragging it up or down the list. The metrics table automatically updates to match the order of the metrics in the Edit view list.

• If you upgraded to Flex UI 2.4.x or later from an earlier version, the new metrics will appear on the dashboard after your Flex account receives at least one call, SMS, or chat task post-upgrade.

The Real-Time Queues View is rendered by the QueuesStatsView component. This programmable Flex UI component contains the following child components:

• QueuesStats.AggregatedQueuesDataTiles (key: tiles)
• QueuesStats.QueuesDataTable (key: table)

You can modify QueuesStatsView with the Content property:

1
// Add your own component
2
QueuesStatsView.Content.add(<CustomTiles key="custom-tiles" />, {
3
  sortOrder: 0
4
});
5

You can also use the QueueStatsView component to programatically remove a tile.

To remove a tile:

1
flex.QueuesStats.AggregatedQueuesDataTiles.defaultProps.dataTileFilter = (id => {
2
  if (id === 'agents-by-activity-chart-tile') {
3
    return false; // false means the card will be hidden
4
  }
5
  return true; // true means the card will be shown
6
});

The default tiles for this component are agents-by-activity-chart-tile and all. Note that built in channel-specific tiles use the task channel SID.

The child component QueuesStats.QueuesDataTable lets you add columns in the QueuesDataTable. Out of the box, the QueuesDataTable has the following columns:

• Queues (key: friendly-name)
• Active (key: active-tasks)
• Waiting (key: waiting-tasks)
• Longest (key: longest-wait-time)
• Agents (key: agents)

To add a column, add a ColumnDefinition component to QueuesStats.QueuesDataTable. If you want custom formatting on a default column, remove the original column and create a new one.

You can click on the header of a predefined column to sort the QueuesDataTable by those values. By default, the table is sorted by queue name.

To change the column the table is sorted by, set the following property to the key of the column that you want to use:

QueuesStats.QueuesDataTable.defaultProps.defaultSortColumn = "column-key"

When adding a custom column, you can specify the parameter sortingFn: (a, b) => number, which works the same way as the compareFunction parameter in JavaScript's Array.sort().

The default order of sorting is descending. To change the direction to ascending, use the sortDirection property on the ColumnDefinition component.

In this example, you display a new column with pending tasks and allow sorting by the values in this column:

1
Flex.QueuesStats.QueuesDataTable.Content.add(
2
  <ColumnDefinition
3
    key="pending-tasks"
4
    header="Pending tasks"
5
    content={(queue: Flex.QueuesStats.WorkerQueue) =>
6
      queue.tasks_by_status.pending
7
    }
8
    sortingFn={(
9
      a: Flex.QueuesStats.WorkerQueue,
10
      b: Flex.QueuesStats.WorkerQueue
11
    ) => a.tasks_by_status.pending - b.tasks_by_status.pending}
12
    sortDirection="asc"
13
  />
14
);
15

Out of the box, all of your queues display in the Flex UI. If you want to hide queues or only show specific queues, you can apply a filter:

1
QueuesStats.setFilter((queue: Flex.QueuesStats.WorkerQueue) =>
2
  queue.friendly_name !== "Invisible Queue"
3
);

The setFilter takes a single parameter, a filter function with a signature of (queue: WorkerQueue) => boolean. This function will be evaluated for each queue and added to the view if the return value is true.

For larger contact centers with a large number of queues, it may be more adequate to use the setSubscriptionFilter that is available in @twilio/flex-ui@1.24.0 with the SLA feature enabled. Unlike setFilter, this filter will stop the UI from subscribing to updates from hidden queues, which results in improved performance of the page.

The setSubscriptionFilter lets you filter queues only by name or SID:

1
const visibleQueues = ["Everyone", "Sales"];
2

3
QueuesStats.setSubscriptionFilter((queue: { friendly_name: string; sid: string }) =>
4
  visibleQueues.includes(queue.friendly_name)
5
);

The SLA metrics feature adds the following columns to Flex.QueuesStats.QueuesDataTable:

• SLA 30 min (key: sla-30min)
• SLA Today (key: sla-today)
• Handled 30 min (key: handled-tasks-30min)
• Handled Today (key: handled-tasks-today
• Abandoned 30 min (key: abandoned-tasks-30min)
• Abandoned Today (key: abandoned-tasks-today)

SLA metrics are calculated by both the last 30 minute floating window and the current business day.

After the feature is enabled, you can remove any of the default columns listed above or add additional columns with SLA metrics. See the full list of available metrics.

1
const RenderShortAbandoned30Min = (workerQueue: Flex.QueuesStats.WorkerQueue) =>
2
  // QueuesDataTableCell component helps us render additional expandable rows with channel specific data
3
  <Flex.QueuesStats.QueuesDataTableCell
4
    // Pass the queue data down
5
    queue={workerQueue}
6
    // Render the queue level value
7
    renderQueueData={(queue) => queue.sla_30_min.short_abandoned_tasks_count}
8
    // Render a value for each active channel in the queue
9
    renderChannelData={(channel, queue) => channel.sla_30_min.short_abandoned_tasks_count}
10
  />
11

12
const RenderShortAbandonedToday = (workerQueue: Flex.QueuesStats.WorkerQueue) =>
13
  <Flex.QueuesStats.QueuesDataTableCell
14
    queue={workerQueue}
15
    renderQueueData={(queue) => queue.sla_today.short_abandoned_tasks_count}
16
    renderChannelData={(channel, queue) => channel.sla_today.short_abandoned_tasks_count}
17
  />
18

19

20
Flex.QueuesStats.QueuesDataTable.Content.add(
21
  <Flex.ColumnDefinition
22
    key="short-abandoned-30min"
23
    header="Short Abandoned"
24
    // Since our columns have the same header, we can set
25
    // the same headerColSpanKey on both to merge their headers.
26
    headerColSpanKey="short-abandoned"
27
    subHeader="30 min"
28
    content={RenderShortAbandoned30Min}
29
  />
30
);
31

32
Flex.QueuesStats.QueuesDataTable.Content.add(
33
  <Flex.ColumnDefinition
34
    key="short-abandoned-today"
35
    header="Short Abandoned"
36
    headerColSpanKey="short-abandoned"
37
    subHeader="Today"
38
    content={RenderShortAbandonedToday}
39
  />
40
);

In this snippet, Flex adds two columns to QueuesDataTable that show the number of short abandoned tasks in the last 30 minutes and for the day. You can use the QueuesDataTableCell in the content render function to add additional expandable rows of channel-specific data.

You can configure the time a new business day starts and all SLA threshold values in the admin plugin or with the Flex Configuration API. There are three levels of SLA configurations:

• default
• queue_configurations
• queue_channel_configurations

Each lower level overrides the one above it. For example, a queue_configurations object has priority over the default configuration and a queue_channel_configurations object has priority over the default configuration and matching queue_configurations object.

The request body is validated by the Flex Configuration API and must adhere to the following requirements:

• Each request must include the default configuration, even if you set queue_configurations and/or queue_channel_configurations in the same request.

• Each configuration object included in the request must contain all required properties. The required properties for each configuration object type are as follows:

  • default

    • service_level_threshold
    • short_abandoned_threshold
    • reset_timezone
    • reset_time

  • queue_configurations

    • queue_sid
    • reset_timezone
    • reset_time

  • queue_channel_configurations

    • queue_sid
    • channel_sid
    • service_level_threshold
    • short_abandoned_threshold

After you submit a configuration change, your changes are not applied until the next time a task is received. Consider creating a test task to ensure that your changes are applied right away.

The WorkerQueue data object is extended with the sla_30_min and sla_today keys. These keys are both of the type WorkerQueueSLA, which contains all available SLA metrics for queues:

• total_tasks_count
• handled_tasks_count
• handled_tasks_within_sl_threshold_count
• handled_tasks_within_sl_threshold_percentage
• short_abandoned_tasks_count
• short_abandoned_tasks_percentage
• abandoned_tasks_count
• abandoned_tasks_percentage
• flow_out_tasks_count
• flow_out_tasks_percentage
• sla_percentage

If a queue handles multiple channels, the SLA data is also available per channel. The channels key on the WorkerQueue contains an array of WorkerQueueChannel, which has the following keys:

• sid
• unique_name
• friendly_name
• sla_30_min (WorkerQueueSLA)
• sla_today (WorkerQueueSLA)

workerQueue.channels[0].sla_30_min.total_tasks_count

1
Flex.QueuesStats.QueuesDataTable.Content.add(
2
  <Flex.ColumnDefinition
3
    key="custom-column-1"
4
    header="My Column"
5
    headerColSpanKey="my-column"
6
    subHeader="Foo"
7
    content={YourContentRenderer1}
8
  />
9
);
10

11
Flex.QueuesStats.QueuesDataTable.Content.add(
12
  <Flex.ColumnDefinition
13
    key="custom-column-2"
14
    header="My Column"
15
    headerColSpanKey="my-column"
16
    subHeader="Bar"
17
    content={YourContentRenderer2}
18
  />
19
);

You can add subheaders to columns using a subHeader property on ColumnDefinition.

If adjacent columns have the same header and you want to merge these table header cells, set the same headerColSpanKey on these columns.

To display queue statistics on a TV or a monitor, use the full screen view by clicking the small button in the bottom-right corner.

The button is hidden by default. To enable the button, set the following property:

QueuesStatsView.fullscreen.enabled = true