Implementing Forecast Accuracy Tracking Dashboards with MAPE and Weighted Error Metrics

What This Guide Covers

You will build a production-grade dashboard in Genesys Cloud CX that tracks forecast accuracy using Mean Absolute Percentage Error (MAPE) and Weighted Absolute Percentage Error (WAPE). You will configure the necessary reporting data sources, define the custom metrics via SQL or calculated fields, and construct a visualization layer that isolates true forecasting performance from operational noise.

Prerequisites, Roles & Licensing

• Licensing: Genesys Cloud CX 3 (or higher) with the Workforce Management (WFM) add-on.
• Roles: Workforce Management > Administrator or Workforce Management > Analyst.
• Permissions:
  • Reporting > Report > Create
  • Reporting > Dashboard > Create
  • Reporting > Data Source > Edit
• Dependencies:
  • Historical scheduling data must be populated in the WFM module.
  • A minimum of 4-8 weeks of historical actuals versus forecast data.
  • Access to Genesys Cloud Reporting API if automating dashboard creation via Terraform or PowerShell.

The Implementation Deep-Dive

1. Understanding the Data Model and Metric Definitions

Before configuring the dashboard, you must understand how Genesys Cloud stores WFM data. The platform does not store MAPE or WAPE as native, pre-calculated fields in the standard reporting widgets. You must derive these from the Schedule and Actuals data.

The Trap: Using Agent-Level Granularity for MAPE

The most common error in forecast accuracy tracking is calculating MAPE at the individual agent level. Agent-level data is highly volatile due to individual attendance issues, specific skill gaps, or localized breaks. Aggregating agent-level MAPE produces a noisy metric that obscures the true accuracy of the workforce plan.

Architectural Decision: Always calculate forecast accuracy at the Group or Department level. This aggregates out individual anomalies and reflects the accuracy of the plan, not the performance of the person.

Metric Definitions

• MAPE (Mean Absolute Percentage Error): Measures the average magnitude of error in percentage terms. It is sensitive to low-volume periods.

  MAPE = (1/n) * SUM(|(Actual - Forecast) / Forecast|) * 100
  

• WAPE (Weighted Absolute Percentage Error): Weighted by the volume. This prevents low-volume periods from skewing the overall accuracy score.

  WAPE = SUM(|Actual - Forecast|) / SUM(Actual) * 100
  

2. Configuring the Custom Report Data Source

You cannot use the out-of-the-box “Schedule vs Actuals” report directly for MAPE because it lacks the necessary calculated fields. You must create a custom report using the Reporting API or the Reporting UI with custom SQL logic if your tenant supports advanced reporting features. For this guide, we will use the Genesys Cloud Reporting UI with Calculated Fields.

Step 2.1: Create the Base Report

1. Navigate to Admin > Reporting > Reports.
2. Click Create Report.
3. Select Workforce Management as the category.
4. Choose Schedule vs Actuals as the base report type.
5. Name the report WFM_Forecast_Accuracy_Base.

Step 2.2: Define Grouping and Filters

• Group By: Group Name (or Department Name depending on your hierarchy).
• Time Interval: Hour (for granular accuracy) or Day (for daily planning accuracy).
• Filters:
  • Status = Published (Ensure you are only looking at finalized schedules).
  • Date Range = Last 8 Weeks (Adjust based on your business cycle).

Step 2.3: Add Calculated Fields for Error Metrics

Genesys Cloud allows you to add custom fields in the report builder. However, complex mathematical aggregations like MAPE often require the Reporting API to push custom SQL or to use Tableau/PowerBI connectors. For a native Genesys dashboard, we will use a workaround: creating a Custom Field that calculates the absolute difference, then aggregating it in the dashboard.

1. In the report builder, click Add Field.
2. Search for Actual Contacts and Forecasted Contacts.
3. Create a new Calculated Field:
   • Name: Absolute_Error
   • Formula: ABS([Actual Contacts] - [Forecasted Contacts])
4. Create another Calculated Field:
   • Name: Percentage_Error
   • Formula: IF([Forecasted Contacts] > 0, ABS([Actual Contacts] - [Forecasted Contacts]) / [Forecasted Contacts], 0)
   • Format: Percentage

The Trap: Division by Zero
If a forecasted value is zero, the percentage error calculation will throw a division by zero error, breaking the report. The IF condition above mitigates this. Always handle zero-forecast scenarios by treating them as 100% error if actuals > 0, or 0% error if actuals = 0.

3. Building the Native Genesys Dashboard

Now that you have the base report with the necessary fields, you will construct the dashboard.

Step 3.1: Create the Dashboard

1. Navigate to Admin > Reporting > Dashboards.
2. Click Create Dashboard.
3. Name it WFM_Forecast_Accuracy_Tracking.
4. Select the WFM_Forecast_Accuracy_Base report as the data source.

Step 3.2: Configure the MAPE Widget

1. Add a Table widget.
2. Configure the columns:
   • Group Name
   • Average Percentage_Error (Use the AVG aggregation function on the Percentage_Error field).
3. Sort by Average Percentage_Error descending.
4. Rename the widget to Group MAPE Ranking.

Architectural Reasoning: Using a table allows you to identify which specific groups are driving inaccuracy. A high overall MAPE might be masked by a single under-performing group. This table provides the drill-down capability.

Step 3.3: Configure the WAPE Widget

WAPE requires a ratio of sums, which is not directly available as a single aggregated field in the basic dashboard builder. You have two options:

Option A: Native Approximation (Limited Accuracy)

1. Add a KPI widget.
2. Set the metric to Sum Absolute_Error.
3. Add a second KPI widget for Sum Actual Contacts.
4. Manually calculate WAPE in a spreadsheet or use a custom visualization if available.

Option B: Advanced Reporting API (Recommended for Precision)
For precise WAPE, you should use the Reporting API to generate a custom data source that calculates WAPE directly.

1. Use the POST /api/v2/reporting/queries endpoint to create a query that calculates WAPE.
2. Example JSON Payload:

   {
     "reportId": "your-report-id",
     "dateRange": {
       "startDate": "2023-10-01T00:00:00.000Z",
       "endDate": "2023-10-31T23:59:59.999Z"
     },
     "groupings": ["GroupName"],
     "metrics": [
       {
         "id": "Absolute_Error",
         "aggregation": "SUM"
       },
       {
         "id": "Actual_Contacts",
         "aggregation": "SUM"
       }
     ],
     "filter": {
       "type": "or",
       "clauses": []
     }
   }
   

3. In the response, calculate WAPE as SUM(Absolute_Error) / SUM(Actual_Contacts).
4. Push this calculated WAPE value back into a Custom Field or use it in an external BI tool.

The Trap: Ignoring Shrinkage
Forecast accuracy should be based on Planned Hours versus Actual Productive Hours, not just contacts. If you only track contacts, you ignore the impact of shrinkage (absences, breaks, training) on the overall service level. Ensure your Forecasted Contacts metric includes the shrinkage factor applied during the scheduling process.

4. Automating the Dashboard with Terraform

For enterprise deployments, manual dashboard creation is not sustainable. You should use Terraform to manage the dashboard state.

Step 4.1: Define the Terraform Configuration

resource "genesyscloud_report" "wfm_forecast_accuracy" {
  name        = "WFM_Forecast_Accuracy_Base"
  description = "Base report for MAPE and WAPE calculations"
  type        = "SCHEDULE_VS_ACTUALS"

  query {
    report_type_id = "SCHEDULE_VS_ACTUALS"
    
    groupings = [
      "GroupName"
    ]

    metrics = [
      "ActualContacts",
      "ForecastedContacts"
    ]

    filters = {
      type = "and"
      clauses = [
        {
          type = "string"
          field = "Status"
          operator = "eq"
          values = ["Published"]
        }
      ]
    }
  }
}

resource "genesyscloud_dashboard" "wfm_accuracy_dashboard" {
  name        = "WFM_Forecast_Accuracy_Tracking"
  description = "Tracks MAPE and WAPE for workforce planning"

  widgets {
    type = "table"
    name = "Group MAPE Ranking"
    report_id = genesyscloud_report.wfm_forecast_accuracy.id
    
    columns = [
      {
        name = "GroupName"
        type = "STRING"
      },
      {
        name = "Average Percentage_Error"
        type = "DOUBLE"
        aggregation = "AVG"
      }
    ]
  }
}

Architectural Reasoning: Using Terraform ensures that the dashboard configuration is version-controlled, reproducible, and consistent across multiple environments (Dev, Test, Prod). It also allows for automated testing of the dashboard structure.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Zero-Forecast Periods

• The Failure Condition: The MAPE calculation returns Infinity or NaN for periods where the forecast was zero but actuals were non-zero.
• The Root Cause: Division by zero in the percentage error formula.
• The Solution: Implement a conditional check in the calculated field. If Forecasted Contacts is 0, set Percentage_Error to 1.0 (100%) if Actual Contacts > 0, otherwise 0. This ensures the error is captured without breaking the aggregation.

Edge Case 2: Shrinkage Mismatch

• The Failure Condition: The forecast accuracy appears poor despite accurate contact volume predictions.
• The Root Cause: The forecast includes shrinkage assumptions (e.g., 15% absence) that did not materialize, or actual shrinkage was higher than planned.
• The Solution: Segment your accuracy tracking into two metrics: Contact Volume Accuracy and Staffing Accuracy. Contact Volume Accuracy tracks Forecasted Contacts vs Actual Contacts. Staffing Accuracy tracks Planned Hours vs Actual Productive Hours. This separation helps identify whether the issue is with the forecasting model or the attendance management.

Edge Case 3: Time Zone Discrepancies

• The Failure Condition: Accuracy metrics are skewed for global contact centers.
• The Root Cause: The report is using the tenant’s default time zone instead of the local time zone of the contact center group.
• The Solution: Ensure that the Schedule vs Actuals report is configured to use the Local Time Zone of the group. In the reporting UI, check the Time Zone settings for the report. If using the API, specify the timeZone parameter in the query.

Official References

• Genesys Cloud Reporting API Documentation
• Workforce Management Reporting Guide
• Understanding Forecast Accuracy Metrics
• Terraform Genesys Cloud Provider