Real-Time Queues View Programmability

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

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

You can modify QueuesStatsView via the Content property:

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

1
import * as Flex from "@twilio/flex-ui";
2
import { connect } from "react-redux";
3

4
// Connect to Flex's redux store and display the number of wrapping tasks
5
const WrappingTasksTile = connect((state: Flex.FlexState) => {
6
  const queues = Object.values(state.flex.realtimeQueues.queuesList);
7
  const wrappingTasks = queues.reduce((sum, q) => sum + q.tasks_by_status.wrapping, 0);
8

9
  return {
10
    wrappingTasks: wrappingTasks.toString(),
11
  };
12
})(({ wrappingTasks }) => (
13
  <Flex.AggregatedDataTile title="Wrapping Tasks" content={wrappingTasks} />
14
));
15

16

17
// Add the WrappingTasksTile to the view
18
Flex.QueuesStats.AggregatedQueuesDataTiles.Content.add(
19
  <WrappingTasksTile key="wrapping-tasks-tile" />,
20
  { sortOrder: -1 }
21
);

To add custom tiles or remove existing tiles, modify QueuesStats.AggregatedQueuesDataTiles. Out of the box, this child component contains the following aggregated data tiles:

• Active Tasks (key: active-tasks-tile )
• Waiting Tasks (key: waiting-tasks-tile )
• Longest Wait (key: longest-wait-time-tile )
• Agents (key: agents-by-activity-chart-tile )

1
import { ColumnDefinition } from '@twilio/flex-ui';
2

3
// Remove the original column
4
Flex.QueuesStats.QueuesDataTable.Content.remove("waiting-tasks");
5

6
// Create a new column with custom formatting
7
Flex.QueuesStats.QueuesDataTable.Content.add(
8
  <ColumnDefinition
9
    key="my-waiting-tasks"
10
    header="Waiting tasks"
11
    content={(queue: Flex.QueuesStats.WorkerQueue) => {
12
      // Calculate number of waiting tasks by adding pending and reserved
13
      const { pending, reserved } = queue.tasks_by_status;
14
      const waitingTasks = pending + reserved;
15

16
      // Set the style to color: red if # of waiting tasks is > 10
17
      const spanStyle = waitingTasks > 10 ? { color: "red" } : {};
18

19
      // Return the element to render
20
      return <span style={spanStyle}>{waitingTasks}</span>;
21
    }}
22
  />,
23
  { sortOrder: 1 } // Put this after the second column
24
);

The child component QueuesStats.QueuesDataTable lets you add or remove 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 via 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