Architecting Campaign Result Code Analysis Dashboards for Disposition Trend Monitoring

How-To-Articles
1

Architecting Campaign Result Code Analysis Dashboards for Disposition Trend Monitoring

What This Guide Covers

This guide details the architectural configuration required to build robust dashboards that monitor disposition trend analysis within Genesys Cloud CX Campaigns. It covers the mapping of raw result codes to actionable metrics, the construction of historical reporting jobs, and the integration patterns for external Business Intelligence tools. Upon completion, you will possess a production-ready architecture capable of tracking result code drift, identifying data quality anomalies, and visualizing campaign performance trends with sub-hourly latency.

Prerequisites, Roles & Licensing

Before proceeding, ensure the following environmental conditions are met to avoid runtime failures during deployment.

  • Licensing Tier: Genesys Cloud CX Enterprise license is required. The Campaigns Add-on must be active for all users participating in outbound dialing. Standard CCaaS licenses do not include the Campaign Contact analytics entity required for deep disposition analysis.
  • Granular Permissions: The user account performing configuration requires the following permission sets:
    • Analytics > Reports > View: Required to read existing report jobs.
    • Analytics > Reports > Create: Required to provision new historical report jobs via API or UI.
    • Campaigns > Results > Edit: Required to modify result code definitions and mappings.
    • Data > Data Management > Export: Required if exporting raw contact records for external processing.
  • OAuth Scopes: For programmatic dashboarding via the Reporting API, the integration application must request the following scopes:
    • analytics.reporting.read
    • analytics.reporting.write
    • campaigns.contacts.read
  • External Dependencies: If utilizing external visualization (Tableau, PowerBI, Looker), ensure the ETL pipeline is configured to poll the Genesys Reporting API endpoints. For real-time monitoring, WebSocket connections must be established with sufficient bandwidth for concurrent report job streaming.

The Implementation Deep-Dive

1. Result Code Definition and Schema Normalization

The foundation of any disposition trend analysis is the consistency of data entry at the source. In Genesys Cloud Campaigns, result codes are not static dropdown lists; they are dynamic entities defined within the Campaign Contact Flow or via the Results API.

Architectural Reasoning:
You must distinguish between System Result Codes (predefined by Genesys) and Custom Result Codes (defined by the organization). Trend analysis fails when agents select synonymous codes for identical outcomes (e.g., “Busy” vs. “Line Busy”). This creates data fragmentation that skews trend aggregation.

Configuration Steps:

  1. Navigate to Campaigns > Settings > Results.
  2. Review existing result codes. Ensure every code has a unique result_code_id and a standardized label.
  3. Define a mapping layer in your analytics logic. Do not rely on the UI label for aggregation; use the system ID.

The Trap:
A common misconfiguration occurs when administrators create duplicate result codes during peak staffing periods to accommodate specific agent requests without validation. For example, creating “No Answer - Home” and “No Answer - Mobile” separately instead of using a single No Answer code with a qualifier field.

  • Catastrophic Downstream Effect: Your trend dashboard will show two separate trends for the same behavior. If you query WHERE result_code_id = '123', you miss 40% of the data that landed in result_code_id = '124'. This leads to incorrect ROI calculations and false negative performance alerts.
  • Mitigation: Implement a validation script prior to campaign launch that scans for semantic similarity in result code labels. Reject any new result code creation if it duplicates an existing semantic meaning without a distinct business outcome (e.g., different disposition logic is required).

JSON Payload Example (Creating a Result Code via API):
To ensure programmatic consistency, define result codes via the POST /api/v2/campaigns/results endpoint rather than the UI.

{
  "name": "Customer Unavailable",
  "description": "Contact was reached but could not be completed during the current interaction window",
  "resultCodeType": "CUSTOMER_UNAVAILABLE",
  "isDefault": false,
  "colorHex": "#FF5733"
}

2. Historical Reporting Job Architecture for Trend Analysis

Standard UI reports provide a snapshot, but trend monitoring requires historical report jobs that aggregate data over time intervals. The Genesys Cloud Analytics reporting engine operates on a batch model where report jobs are queued and processed asynchronously.

Architectural Reasoning:
You must select the correct granularity for your trend analysis. Granularities such as minute provide high resolution but generate excessive API load and latency. Granularities such as day smooth out noise but obscure short-term campaign adjustments. For disposition monitoring, a hybrid approach is required: aggregate by hour for operational dashboards and day for executive summaries.

Configuration Steps:

  1. Initialize a Report Job targeting the Campaign Contact entity.
  2. Apply filters to isolate specific result codes or groups of codes.
  3. Configure the time granularity and time range based on your monitoring SLA.
  4. Set up polling logic to retrieve the job status.

The Trap:
Engineers often configure report jobs with a granularity of minute for trend analysis spanning multiple weeks.

  • Catastrophic Downstream Effect: The report size explodes, leading to timeout errors in the Reporting API and excessive data transfer costs if exporting to external storage. Furthermore, minute-level data introduces noise that obscures true trends caused by agent behavior or script changes.
  • Mitigation: Enforce a policy where trend analysis never exceeds hour granularity for periods longer than 7 days. Use the aggregationType parameter to group results appropriately.

API Payload Example (Creating a Trend Report Job):
Use the Reporting API to create a job that aggregates disposition data by hour over a 30-day window.

{
  "entityId": "campaign",
  "metric": "count",
  "dimension": [
    {
      "type": "resultCode",
      "id": "all"
    },
    {
      "type": "time",
      "granularity": "hour"
    }
  ],
  "filters": {
    "and": [
      {
        "metric": "campaignId",
        "operator": "eq",
        "values": [ "your-campaign-id-here" ]
      },
      {
        "metric": "contactResultStatus",
        "operator": "in",
        "values": [ "completed", "notCompleted" ]
      }
    ]
  },
  "timeRange": {
    "type": "relative",
    "durationMinutes": 43200
  }
}

3. Integration Patterns for External Visualization

For advanced trend monitoring, relying solely on the native Genesys Analytics UI is insufficient. You must integrate with external Business Intelligence (BI) tools to visualize correlations between result codes and other variables, such as script version or agent skill level.

Architectural Reasoning:
Direct database access to the analytics stream is not supported due to security and performance constraints. The only supported method for extracting historical data is via the Reporting API. You must implement a polling mechanism that retrieves completed report jobs and pushes them to your visualization layer.

Implementation Strategy:

  1. Trigger: Create a scheduled Report Job using the payload in Section 2.
  2. Polling: Monitor the status field of the job. It transitions from queued to processing to completed or failed.
  3. Extraction: Once completed, retrieve the data via the GET /analytics/reportjobs/{jobId} endpoint.
  4. Transformation: Normalize the JSON response into a flat schema suitable for your BI tool (e.g., converting nested dimension objects into columns).

The Trap:
Developers frequently attempt to stream real-time data from the Reporting API as if it were the Streaming API (/api/v2/analytics/realtime).

  • Catastrophic Downstream Effect: The Reporting API is not designed for sub-minute streaming. Attempting to poll a report job every 60 seconds will result in rate limiting errors and incomplete data sets because historical aggregations require time to finalize.
  • Mitigation: Implement exponential backoff logic when polling the report job status. Only fetch data once the status is completed. For true real-time dashboards, utilize the /analytics/v1/realtime endpoint instead of the Reporting API.

Code Snippet (Polling Logic in Python):

import time
import requests

def get_report_data(job_id, auth_token):
    url = "https://instance.genesys.cloud/api/v2/analytics/reportjobs/" + job_id
    headers = {
        "Authorization": "Bearer " + auth_token,
        "Content-Type": "application/json"
    }
    
    max_retries = 10
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        data = response.json()
        
        if data['status'] == 'completed':
            return data['data']
        elif data['status'] == 'failed':
            raise Exception("Report job failed with status: " + data['error']['message'])
        
        wait_time = 2 ** attempt
        time.sleep(wait_time)
    
    raise TimeoutError("Report job polling timed out after max retries")

4. Data Quality and Drift Detection

Trend monitoring is useless if the underlying data quality is compromised. A critical component of this architecture is detecting when result code distribution shifts unexpectedly, which often indicates a script update issue or agent training gap.

Architectural Reasoning:
You must establish a baseline for expected result code distribution. If Customer Unavailable codes suddenly jump from 5% to 20% over a single shift, this is an anomaly that requires immediate investigation rather than just a visual trend line.

Implementation Strategy:

  1. Calculate the rolling average of result code percentages over the last 30 days.
  2. Set threshold alerts for deviations exceeding 2 standard deviations from the mean.
  3. Log these anomalies to a separate monitoring stream (e.g., Splunk, Datadog) rather than just displaying them in the dashboard.

The Trap:
Teams often set static thresholds (e.g., “Alert if No Answer > 10%”).

  • Catastrophic Downstream Effect: Campaigns naturally have higher No Answer rates during off-hours or weekends. A static threshold generates false positives, leading to alert fatigue and ignored warnings.
  • Mitigation: Use dynamic baselines based on time-of-day and day-of-week patterns. Configure your trend analysis logic to compare current hour performance against the same hour in previous weeks.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Analytics Processing Latency

The Failure Condition: A report job completes successfully, but the data does not appear in the dashboard for 30 minutes or more.
The Root Cause: The Genesys Cloud Analytics engine processes historical data with a latency window depending on the granularity and volume. For hour granularity, there is typically a 5 to 15 minute delay before data is finalized and available via the API.
The Solution: Do not configure your dashboard polling interval to be shorter than the maximum processing latency plus buffer time. If you poll every 5 minutes for hourly data, you will see repeated “partial” jobs. Increase the polling interval to 15 minutes for hour granularity and add a validation step that checks if the completedAt timestamp is within the last hour before rendering.

Edge Case 2: Result Code ID Drift

The Failure Condition: A previously working dashboard stops displaying data or throws null values when querying specific result codes.
The Root Cause: Genesys Cloud allows administrators to rename or disable result codes. While the name changes, the underlying id usually persists. However, if a new campaign is created and imports result codes differently, or if a custom script updates the mapping dynamically via API, the ID-to-Label association can break in legacy reports.
The Solution: Never hardcode result code labels in your visualization logic. Always query the current state of the Result Code definitions via GET /api/v2/campaigns/results and map the IDs to labels dynamically at runtime. Store the mapping in a configuration file or database that is updated weekly, not daily.

Edge Case 3: GDPR/PII Masking in Results

The Failure Condition: A trend dashboard inadvertently displays PII because a result code description was updated to include sensitive information (e.g., “No Answer - Account Holder Name Redacted”).
The Root Cause: Result codes are metadata, but if the description or name fields are used for reporting and contain free-text updates by agents or admins, compliance violations occur.
The Solution: Restrict write access to the Result Code definition UI to a single security group (e.g., Campaign Administrators). Implement a pre-flight validation check on the API endpoint that scans for regex patterns matching PII (SSN, Credit Card) in result code names or descriptions before allowing the creation. Ensure all dashboards strip these fields from the output payload.

Official References