Implementing Supervisor Dashboard Widgets for Team-Level Quality Score Distribution Views

How-To-Articles
1

Implementing Supervisor Dashboard Widgets for Team-Level Quality Score Distribution Views

What This Guide Covers

This guide details the architecture and configuration required to build custom Supervisor Dashboard widgets in Genesys Cloud that visualize Quality Management (QM) score distributions at the team level. You will learn how to construct the underlying SQL-based queries within the Analytics framework, handle the specific limitations of QM data granularity, and render these datasets as actionable distribution charts or tables for supervisors. The end result is a production-ready dashboard component that allows supervisors to identify outliers and trends in agent quality scores without exporting raw data to external BI tools.

Prerequisites, Roles & Licensing

Licensing Requirements

  • Genesys Cloud CX Platform: Base license required.
  • Quality Management Add-on: Required to access QM data.
  • Workforce Engagement Management (WEM): Optional, but recommended if correlating quality scores with adherence or shrinkage metrics.
  • Analytics Add-on: Required for advanced SQL queries and custom report creation if utilizing the legacy reporting engine, though modern Dashboards utilize the embedded Analytics service.

Permissions & Roles

The user configuring the dashboard must possess the following permissions:

  • Dashboard > View
  • Dashboard > Edit (to create or modify widgets)
  • Analytics > Query > View
  • Analytics > Query > Edit (if creating new data sources)
  • Quality > View (to understand the metric definitions)

The end-users (Supervisors) viewing the dashboard require:

  • Dashboard > View
  • Quality > View

Technical Dependencies

  • Genesys Cloud Architect: For any potential integration with IVR or other systems if quality data triggers real-time actions (advanced use case).
  • Genesys Cloud Dashboard Editor: The primary interface for widget configuration.
  • SQL Knowledge: Basic understanding of SQL syntax for custom queries, specifically GROUP BY and aggregation functions.

The Implementation Deep-Dive

1. Understanding the QM Data Model and Granularity Constraints

Before configuring any widget, you must understand the data structure of Quality Management in Genesys Cloud. QM data is not stored in a flat, denormalized table suitable for direct visualization. It resides in the quality domain within the Genesys Cloud data warehouse.

The critical architectural decision here is determining the granularity of your view. Genesys Cloud QM scores are calculated at the interaction level (a specific call, chat, or email) and then aggregated at the agent level and team level.

The Trap: Attempting to visualize “Team Quality Score” by averaging individual agent scores in the dashboard widget layer. This is a common misconfiguration. If you average the averages, you introduce statistical bias, especially if team members have vastly different volumes of interactions. A senior engineer always aggregates at the lowest possible level before summarizing. We must aggregate at the interaction level or use the pre-aggregated team metrics provided by the platform to ensure accuracy.

Architectural Reasoning:
Genesys Cloud provides pre-calculated metrics for QM. Using these pre-aggregated fields is significantly more performant than writing a custom SQL query to join interaction tables with quality tables. For team-level distribution views, we rely on the quality dataset’s team-level aggregates. However, “distribution” implies seeing the spread (e.g., how many agents scored 90-100, 80-89, etc.), not just the mean. This requires a specific approach to data visualization that standard “Average Score” widgets do not support.

2. Configuring the Data Source via Custom Analytics Query

To achieve a distribution view (histogram or binned table), we cannot use the standard “Quality Score” widget, which only displays a single aggregated value. We must create a custom data source using the Genesys Cloud Analytics Query Builder or SQL interface.

Step 2.1: Create the SQL Query

Navigate to Analytics > Queries and create a new SQL query.

The Trap: Selecting the wrong date range granularity. QM scores are often calculated asynchronously after the interaction ends. If you query for “Today,” you may miss scores that are still processing. Always use a look-back window or ensure your query handles null values for incomplete assessments.

SQL Payload Example:
This query retrieves agent-level quality scores within a specific team and bins them for distribution analysis. Note the use of CASE statements to create bins.

SELECT
    q.team_id,
    q.team_name,
    q.agent_id,
    q.agent_name,
    q.quality_score,
    -- Create bins for distribution visualization
    CASE
        WHEN q.quality_score >= 90 THEN '90-100'
        WHEN q.quality_score >= 80 THEN '80-89'
        WHEN q.quality_score >= 70 THEN '70-79'
        WHEN q.quality_score >= 60 THEN '60-69'
        ELSE 'Below 60'
    END AS score_bin,
    COUNT(q.interaction_id) AS interaction_count
FROM
    quality.qm_scores q
WHERE
    q.team_id = '{{team_id}}' -- Parameterized for dashboard filtering
    AND q.date_range_start >= '{{start_date}}'
    AND q.date_range_end <= '{{end_date}}'
    AND q.quality_score IS NOT NULL
GROUP BY
    q.team_id,
    q.team_name,
    q.agent_id,
    q.agent_name,
    q.quality_score,
    score_bin
ORDER BY
    q.quality_score DESC

Architectural Reasoning:
We group by agent_id and score_bin to allow the dashboard widget to count how many agents fall into each quality tier. This transforms raw scores into a categorical distribution. The {{team_id}} parameter allows this single query to be reused across multiple dashboard widgets for different teams, promoting reusability and reducing maintenance overhead.

Step 2.2: Validate the Query

Run the query with test parameters. Ensure that:

  1. The score_bin column correctly categorizes scores.
  2. The interaction_count reflects the number of assessed interactions per agent within that bin (or simply count distinct agents if viewing agent distribution).
  3. Performance is acceptable. Queries taking longer than 10 seconds will cause dashboard timeouts. If performance is poor, add an index-friendly filter on date_range_start.

3. Building the Dashboard Widget

With the data source defined, we now construct the visual component.

Step 3.1: Select the Widget Type

Navigate to Dashboards and create a new widget.

  • Widget Type: Select Table or Bar Chart.
    • Table: Best for precise values and drill-down capabilities.
    • Bar Chart: Best for visual distribution (histogram-style).

The Trap: Using a Line Chart for distribution data. Line charts imply time-series continuity. Quality score bins are categorical, not continuous. Using a line chart creates a misleading visual narrative that suggests trends between unrelated categories (e.g., “Below 60” to “60-69”). Always use Bar or Column charts for categorical distributions.

Step 3.2: Configure Data Bindings

Map the SQL query fields to the widget properties:

  • X-Axis (Category): score_bin
  • Y-Axis (Value): interaction_count (or agent_id count if configured in SQL)
  • Filter: team_id (linked to dashboard-level filters)

Architectural Reasoning:
By binding the team_id filter to the dashboard’s global filter context, you enable a unified user experience. When a supervisor selects “Team Alpha” from the dashboard header, the quality distribution widget updates automatically without requiring per-widget configuration. This leverages Genesys Cloud’s reactive dashboard architecture.

Step 3.3: Styling and Thresholds

Configure conditional formatting to highlight critical areas:

  • Red: score_bin = ‘Below 60’
  • Yellow: score_bin = ‘60-69’
  • Green: score_bin = ‘90-100’

The Trap: Over-customizing colors. Using too many distinct colors creates cognitive load. Stick to a standard traffic-light system (Red/Yellow/Green) or a sequential color scale (light to dark) for distribution. This ensures consistency across the organization’s dashboard suite.

4. Implementing Dynamic Team Filtering

To make this widget scalable, it must support dynamic team selection. Hardcoding team IDs in the SQL query is a maintenance nightmare.

Step 4.1: Use Dashboard Filter Context

In the Dashboard Editor, ensure that the Team filter is added to the dashboard header.

  1. Add a Filter widget to the dashboard.
  2. Set the filter type to Team.
  3. Link the custom SQL query’s {{team_id}} parameter to this filter.

Architectural Reasoning:
This approach decouples the data logic from the presentation layer. The SQL query remains generic and reusable. The dashboard filter acts as the injection point for context. This pattern is essential for multi-team supervisors who need to toggle between different groups without switching dashboards.

Step 4.2: Handle Empty States

Configure the widget’s empty state behavior.

  • Setting: “Show message”
  • Message: “No quality assessments found for the selected team in the current date range.”

The Trap: Leaving the empty state as “Blank.” A blank widget is ambiguous. It could mean an error, no data, or a loading state. Explicit messaging reduces support tickets and clarifies the data status for the end-user.

Validation, Edge Cases & Troubleshooting

Edge Case 1: The “Zero Assessment” Agent Bias

The Failure Condition:
A supervisor notices that the team average quality score is 95%, but they know several agents are underperforming. The distribution widget shows almost all agents in the “90-100” bin.

The Root Cause:
Agents with zero assessments are excluded from the query. If 5 out of 20 agents have no quality scores yet, the widget only visualizes the 15 assessed agents. This creates a skewed, overly optimistic view. The denominator in your mental model is 20, but the data source denominator is 15.

The Solution:
Modify the SQL query to include agents with zero assessments by joining the users table (filtered by team membership) with the quality table using a LEFT JOIN.

-- Revised SQL Snippet for Zero-Assessment Handling
SELECT
    u.team_id,
    u.team_name,
    u.id AS agent_id,
    u.name AS agent_name,
    COALESCE(q.quality_score, 0) AS quality_score,
    CASE
        WHEN q.quality_score IS NULL THEN 'No Assessment'
        WHEN q.quality_score >= 90 THEN '90-100'
        -- ... other bins ...
    END AS score_bin,
    COUNT(q.interaction_id) AS interaction_count
FROM
    users u
LEFT JOIN
    quality.qm_scores q ON u.id = q.agent_id
WHERE
    u.team_id = '{{team_id}}'
    AND u.enabled = true
GROUP BY
    u.team_id,
    u.team_name,
    u.id,
    u.name,
    q.quality_score,
    score_bin

This ensures that agents without scores appear in a distinct “No Assessment” bin, providing a complete picture of team readiness.

Edge Case 2: Timezone Misalignment in Date Ranges

The Failure Condition:
A supervisor in New York views the dashboard at 10:00 AM EST. The quality scores for calls taken at 9:00 AM EST are not appearing. However, an agent in London sees them.

The Root Cause:
Genesys Cloud stores all timestamps in UTC. If the dashboard filter or SQL query uses local time zones without explicit conversion, the date boundaries will be off. For example, date_range_start >= '2023-10-27' interprets this as 2023-10-27 00:00:00 UTC. For an EST user, this is 7:00 PM the previous day. Calls taken between midnight and 7:00 PM EST on Oct 26 are excluded.

The Solution:
Always use UTC-based date filters in SQL queries. If the dashboard filter provides local time, convert it to UTC in the query parameter mapping or use Genesys Cloud’s built-in timezone-aware date functions in the Analytics editor.

Correct Approach:
Use the {{start_date_utc}} and {{end_date_utc}} parameters provided by the dashboard filter context, which are automatically adjusted for the user’s timezone. Do not manually parse dates in SQL.

Edge Case 3: Performance Degradation on Large Teams

The Failure Condition:
The widget takes >30 seconds to load for teams with >100 agents and >10,000 interactions.

The Root Cause:
The COUNT and GROUP BY operations on the raw quality table are computationally expensive when filtering across large date ranges.

The Solution:

  1. Date Range Limitation: Restrict the dashboard filter to a maximum of 90 days. Historical analysis should be done in Power BI or Tableau, not in real-time dashboards.
  2. Pre-aggregation: Use the Genesys Cloud Analytics “Saved Report” feature to pre-calculate daily aggregates, then query the aggregated result set rather than the raw transactional data.
  3. Sampling: For real-time views, consider sampling data if exact precision is not critical (less common for QM, but viable for volume metrics).

Official References