Implementing Comparative Period Reporting for Week-Over-Week and Month-Over-Month Analysis

How-To-Articles
1

Implementing Comparative Period Reporting for Week-Over-Week and Month-Over-Month Analysis

What This Guide Covers

This guide details the architectural implementation of comparative period reporting for week-over-week and month-over-month analysis using Genesys Cloud CX. You will configure time-series aligned data extractions, deploy server-side comparative filtering via the Reporting API, and construct dashboards that render YoY deltas without client-side calculation overhead. The end result is a production-grade reporting pipeline that delivers consistent, timezone-normalized comparative metrics across operational and executive views.

Prerequisites, Roles & Licensing

  • Licensing Tier: CX 3 or higher. Data Warehouse (DWD) add-on required for historical baseline storage and custom SQL/BI tool integration.
  • User Permissions:
    • Analytics > Analytics Report > View
    • Analytics > Analytics Report > Edit
    • Analytics > Analytics Dashboard > View
    • Analytics > Analytics Dashboard > Edit
    • Data Warehouse > Data Warehouse > View (if leveraging DWD for archival)
  • OAuth Scopes: analytics:reports:view, analytics:reports:edit, datawarehouse:read, dashboards:view
  • External Dependencies: None required for native implementation. If routing to an external BI layer (Tableau, Power BI, Looker), you will need a scheduled DWD extraction pipeline or a middleware service capable of handling OAuth 2.0 client credentials flow.

The Implementation Deep-Dive

1. Data Warehouse Baseline Alignment and Time-Series Normalization

Comparative reporting fails when historical buckets and current buckets use different alignment rules. Genesys Cloud stores raw interaction timestamps in UTC, but operational reporting requires localized time buckets. You must normalize time-series data before applying comparative filters.

Configure your baseline extraction to pull from the interaction or queue_stats DWD tables. The queue_stats table is optimized for aggregated time-series metrics and contains pre-bucketed intervals. You will use the time_bucket column as your primary join key for comparative calculations.

Create a scheduled extraction that exports data to your cloud storage (AWS S3, Azure Blob, or Google Cloud Storage). Schedule the extraction to run daily at 02:00 UTC to capture the previous calendar day before timezone boundary shifts occur. Use the following extraction configuration payload when invoking the DWD API:

POST /api/v2/datawarehouse/extractions
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "name": "Queue_Stats_Comparative_Baseline",
  "description": "Daily extraction for MoM/WoW time-series alignment",
  "view": {
    "name": "queue_stats",
    "columns": [
      { "name": "time_bucket", "type": "string" },
      { "name": "queue_id", "type": "string" },
      { "name": "queue_name", "type": "string" },
      { "name": "offer_count", "type": "integer" },
      { "name": "answer_count", "type": "integer" },
      { "name": "abandon_count", "type": "integer" },
      { "name": "service_level", "type": "double" },
      { "name": "average_handle_time", "type": "double" }
    ],
    "timeColumn": "time_bucket",
    "groupBys": ["queue_id", "queue_name"]
  },
  "schedule": {
    "cron": "0 2 * * *",
    "timezone": "UTC"
  },
  "destination": {
    "type": "s3",
    "bucket": "genesys-dwd-prod",
    "path": "queue_stats/daily/",
    "format": "parquet"
  }
}

The Trap: Aligning comparative periods using calendar dates instead of fixed duration buckets. Calendar months vary in length (28 to 31 days), which distorts month-over-month averages when traffic volume scales linearly with days. Week-over-week comparisons also break when crossing fiscal boundaries or holiday shifts.

Architectural Reasoning: You must anchor comparative calculations to fixed-duration time buckets (P7D or P30D) and explicitly map them to calendar periods only at the presentation layer. Server-side aggregation using fixed intervals guarantees deterministic bucket sizes. This prevents denominator inflation when comparing a 28-day February against a 31-day March. You will store the raw UTC time_bucket values and apply timezone localization exclusively during dashboard rendering or BI transformation.

2. Reporting API Configuration with Relative Date Filtering

The Genesys Cloud Reporting API supports native comparative period filtering via the comparePeriod parameter. This eliminates the need for dual API calls and client-side delta calculation. You will configure the API to return current period data alongside the comparative baseline in a single response.

Use the GET /api/v2/analytics/report/queue/stats endpoint. The request must include explicit dateFrom and dateTo boundaries, a groupBys array for queue segmentation, and a comparePeriod value that matches your analysis window.

GET /api/v2/analytics/report/queue/stats?dateFrom=2024-11-01T00:00:00.000Z&dateTo=2024-11-30T23:59:59.999Z&groupBys=queueId&comparePeriod=P30D&metrics=offerCount,answerCount,abandonCount,serviceLevel,averageHandleTime&interval=P1D
Content-Type: application/json
Authorization: Bearer <access_token>

The response structure returns a data array containing the current period, and a compareData array containing the historical baseline. Each object includes the timeBucket, groupBy values, and metric arrays. You will parse the compareData array to calculate percentage deltas.

Pagination is mandatory for month-over-month extractions. The API returns a maximum of 500 rows per page. You must iterate through the nextPage token until it returns null. Implement exponential backoff for rate limit handling. The Reporting API enforces a 10 requests per second limit per tenant. Burst traffic will trigger HTTP 429 responses.

{
  "data": [
    {
      "timeBucket": "2024-11-01T00:00:00.000Z",
      "groupBy": { "queueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
      "metrics": {
        "offerCount": { "value": 1250 },
        "answerCount": { "value": 1100 },
        "abandonCount": { "value": 150 },
        "serviceLevel": { "value": 85.2 },
        "averageHandleTime": { "value": 245.5 }
      }
    }
  ],
  "compareData": [
    {
      "timeBucket": "2024-10-01T00:00:00.000Z",
      "groupBy": { "queueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
      "metrics": {
        "offerCount": { "value": 1180 },
        "answerCount": { "value": 1050 },
        "abandonCount": { "value": 130 },
        "serviceLevel": { "value": 82.1 },
        "averageHandleTime": { "value": 258.3 }
      }
    }
  ],
  "nextPage": "/api/v2/analytics/report/queue/stats?dateFrom=...&page=2"
}

The Trap: Using comparePeriod alongside dynamic groupBys that introduce new entities mid-period. If a queue is created or decommissioned between the current and comparative period, the API returns sparse data for missing buckets. Client-side join operations will fail or produce null deltas.

Architectural Reasoning: You must filter groupBys to stable identifiers only. Exclude newly provisioned queues from month-over-month comparisons until they accumulate a full comparative cycle. Implement a data validation layer that drops rows where compareData is null or where metric values fall below a statistical significance threshold. This prevents dashboard rendering errors and ensures executive reports reflect mature operational baselines. You will also cache the API response in Redis or DynamoDB with a 15-minute TTL to absorb peak dashboard load without exhausting API quotas.

3. Dashboard Construction and Comparative Metric Rendering

Dashboard widgets in Genesys Cloud do not natively render percentage deltas between data and compareData arrays. You must construct a calculated metric using the Dashboard API or configure a custom visualization layer. For native dashboard deployment, use the metric widget type with explicit formula configuration.

Create a dashboard widget that pulls from the reporting query defined in Step 2. Configure the widget to display two series: current period and comparative period. Enable the showDelta toggle to render percentage changes.

POST /api/v2/analytics/dashboards
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "name": "Operational WoW/MoM Comparative View",
  "description": "Week and month over month queue performance with delta rendering",
  "widgets": [
    {
      "type": "metric",
      "name": "Service Level WoW Delta",
      "query": {
        "type": "report",
        "reportId": "queue_stats_mom_report_id",
        "metrics": ["serviceLevel"],
        "comparePeriod": "P7D",
        "showDelta": true,
        "deltaFormat": "percentage"
      },
      "layout": {
        "x": 0,
        "y": 0,
        "width": 4,
        "height": 2
      }
    },
    {
      "type": "line",
      "name": "Offer Count MoM Trend",
      "query": {
        "type": "report",
        "reportId": "queue_stats_mom_report_id",
        "metrics": ["offerCount"],
        "comparePeriod": "P30D",
        "interval": "P1D",
        "showCompareSeries": true
      },
      "layout": {
        "x": 4,
        "y": 0,
        "width": 8,
        "height": 4
      }
    }
  ]
}

The showCompareSeries flag instructs the rendering engine to plot the historical baseline as a secondary line. The showDelta flag calculates (current - compare) / compare * 100 server-side. This offloads computation from the browser and guarantees consistency across cached views.

The Trap: Relying on client-side JavaScript to calculate deltas after fetching raw API data. Browser caching inconsistencies, timezone mismatches in local Date objects, and race conditions during widget load cause delta values to fluctuate or render as negative percentages when traffic is stable.

Architectural Reasoning: Server-side delta calculation eliminates client-side variance. Genesys Cloud’s reporting engine computes deltas using the exact same aggregation window and timezone rules applied to the source data. You will enforce server-side calculation for all executive dashboards and restrict client-side calculations to ad-hoc analyst exports. This guarantees that the numbers displayed in the dashboard match the numbers stored in your DWD archive. You will also configure dashboard refresh intervals to 300 seconds to prevent API exhaustion during peak operational hours.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Timezone Boundary Drift in Bucketed Aggregations

The Failure Condition: Month-over-month reports show artificial traffic spikes on the first day of the month and artificial drops on the last day. Comparative deltas fluctuate by 15 to 20 percent without operational changes.
The Root Cause: The reporting engine buckets data using UTC timestamps, but dashboard filters apply local timezone offsets. When a month boundary falls near a timezone offset shift (DST transitions or cross-region deployments), the bucket alignment splits interactions across two calendar days. The comparative period inherits the misalignment, causing denominator mismatch.
The Solution: Force all reporting queries to use timezone=UTC in the API request parameters. Configure dashboard filters to display UTC timestamps and apply timezone conversion exclusively in the BI layer or presentation frontend. Use the interval=P1D parameter with explicit UTC boundaries to guarantee bucket consistency. Validate alignment by comparing total offerCount across the current period against the sum of daily buckets. The totals must match within a 0.1 percent tolerance.

Edge Case 2: Sparse Data and Missing Historical Buckets

The Failure Condition: Comparative widgets render null values or display 100 percent deltas for specific queues. Executive reports show incomplete trend lines.
The Root Cause: Queues provisioned after the comparative period start date lack historical baseline data. The Reporting API returns empty compareData arrays for those entities. Division by zero or null comparison triggers rendering failures.
The Solution: Implement a pre-filter validation step that excludes queues with creationDate newer than the comparative period boundary. Use the Queue API (GET /api/v2/queues) to fetch queue metadata and cross-reference against the reporting query results. Drop sparse buckets before delta calculation. For ad-hoc analysis, replace null comparative values with a statistical placeholder (median of peer queues) and flag the metric with a data quality warning. Never allow raw null propagation into executive dashboards.

Edge Case 3: API Rate Limiting During Bulk Comparative Extraction

The Failure Condition: Dashboard loading times exceed 12 seconds. HTTP 429 responses cascade across concurrent user sessions. Scheduled data pipelines fail to complete.
The Root Cause: Month-over-month extractions with daily intervals and multiple queue groupings generate large result sets. Pagination requests fire synchronously without backoff. Concurrent dashboard refreshes compound the request volume, exceeding the 10 requests per second tenant limit.
The Solution: Implement asynchronous extraction with queue-based request throttling. Use a message broker (SQS, RabbitMQ, or Kafka) to schedule API calls at 0.8 requests per second. Cache paginated responses in Redis with a hierarchical key structure (report:queue:{queueId}:mom:{date}). Pre-warm the cache during off-peak hours using cron-triggered extraction jobs. Configure dashboard widgets to pull from the cached layer instead of direct API calls. Enable HTTP 304 conditional requests to skip payload downloads when data has not changed. This reduces API load by 70 to 85 percent during peak operational windows.

Official References