Implementing Automated Quality Evaluation Form Distribution Based on Interaction Sampling Rules

How-To-Articles
1

Implementing Automated Quality Evaluation Form Distribution Based on Interaction Sampling Rules

What This Guide Covers

This guide details the architectural implementation of automated Quality Evaluation (QE) assignment workflows using Genesys Cloud CX. You will configure Interaction Sampling Rules to filter interactions based on metadata and outcome, and link those rules to specific Evaluation Forms. The end result is a deterministic, rule-based system that automatically assigns evaluations to agents without manual intervention, ensuring consistent coverage across high-priority interaction types.

Prerequisites, Roles & Licensing

Licensing Requirements

  • Contact Center Virtual Agent or Contact Center IVR licenses are not sufficient. You require Contact Center CX 1, CX 2, or CX 3 licenses.
  • Workforce Engagement Management (WEM) Add-on is strictly required for Quality Management features. Without the WEM add-on, the Quality menu items will not appear, and the underlying APIs will return 403 Forbidden errors.
  • Evaluation Forms require no additional license beyond WEM, but Speech Analytics integration requires the Speech Analytics add-on if you intend to use transcription data within the evaluation criteria.

Permissions & Roles

  • Administrator Role: Admin:Quality or a custom role with the following permissions:
    • Quality > Evaluation Form > Create/Edit/View
    • Quality > Sampling Rule > Create/Edit/View
    • Quality > Evaluation > Create/Edit/View
    • Telephony > Call Recording > View
    • Interaction > Interaction > View
  • API Access: If automating via the Developer Portal, your OAuth application requires the scope: quality:evaluation:write, quality:samplingrule:write, and interaction:interaction:view.

External Dependencies

  • Telephony Trunks: Must be configured with recording enabled. Sampling rules for voice interactions depend on the existence of a recording URI in the interaction metadata.
  • Architect Flows: If using custom metadata (e.g., interaction.priority), your Architect flows must populate these fields before the interaction terminates.

The Implementation Deep-Dive

1. Designing the Evaluation Form Schema

Before defining sampling rules, you must define the target Evaluation Form. The sampling engine does not evaluate content; it only routes interactions to a form. Therefore, the form structure must align with the business logic of the sampled interaction.

Architectural Reasoning:
You should design forms with modular sections. A monolithic form for all interactions creates maintenance debt. Instead, create a “Base Compliance” section (applicable to all) and “Transaction Specific” sections (applicable only to specific queues or outcomes).

The Trap:
Creating a single Evaluation Form with conditional logic (show/hide fields based on tags) is a common anti-pattern. While Genesys Cloud supports conditional visibility in forms, relying on this for complex branching leads to “cognitive load” for evaluators. If an evaluator sees 40 fields but only 5 are relevant, compliance drops.
Solution: Create distinct forms for distinct interaction types (e.g., Form_Sales_Closed, Form_Support_Tech). This allows Sampling Rules to be precise.

Configuration Steps:

  1. Navigate to Admin > Quality > Evaluation Forms.
  2. Click Add Evaluation Form.
  3. Define the Form Name and Description.
  4. Add Sections. For each section, define Questions.
  5. Set Scoring Type (Numeric, Multiple Choice, Yes/No).
  6. Critical Step: Enable Auto-Score if the evaluation relies on objective data (e.g., “Did the agent ask for the account number?”). This requires integration with Speech Analytics or Screen Pop metadata.
  7. Save the Form. Note the formId from the URL or API response. You will need this for the Sampling Rule.
// Example API Payload for Creating an Evaluation Form
POST /api/v2/quality/evaluationforms
{
  "name": "Sales_Closed_Win",
  "description": "Evaluation for sales calls that resulted in a win",
  "sections": [
    {
      "name": "Compliance",
      "questions": [
        {
          "name": "Read Disclosures",
          "type": "YES_NO",
          "scoringType": "PERCENTAGE",
          "weight": 1.0
        }
      ]
    }
  ]
}

2. Configuring Interaction Sampling Rules

Sampling Rules are the engine that drives automation. They evaluate metadata associated with an interaction and determine if an evaluation should be created.

Architectural Reasoning:
Sampling Rules are evaluated in order of priority (lowest number = highest priority). If an interaction matches multiple rules, only the highest priority rule applies. This is crucial for handling overlaps. For example, a “VIP Customer” rule should have a higher priority (lower number) than a “Random Sample” rule to ensure VIPs are always evaluated.

The Trap:
Configuring a Sampling Rule with a 100% Sample Rate on a high-volume queue.
Downstream Effect: This creates a massive spike in the Evaluation queue, overwhelming evaluators and causing SLA breaches for evaluation completion. It also increases database write operations, potentially impacting platform performance during peak hours.
Solution: Use Stratified Sampling. Define rules that sample based on outcome (e.g., 100% of “Lost Sales” and 5% of “Won Sales”). This provides high coverage for critical failure points without drowning evaluators in successful interactions.

Configuration Steps:

  1. Navigate to Admin > Quality > Sampling Rules.
  2. Click Add Sampling Rule.
  3. Rule Name: Use a descriptive naming convention, e.g., SAMPLE_Sales_Win_10pct.
  4. Priority: Assign a numeric value. Lower numbers are evaluated first.
  5. Status: Set to Active.
  6. Sampling Type: Select Interaction.
  7. Form: Select the Evaluation Form created in Step 1.
  8. Sampling Rate: Enter the percentage (e.g., 10 for 10%).
  9. Filters: This is the core logic. You must define conditions that the interaction must meet.
    • Interaction Type: CALL
    • Queue Name: Sales Team
    • Disposition Code: Sale Closed
    • Agent Name: Any (or specific agents for targeted coaching)
    • Custom Metadata: If your Architect flow sets interaction.tags.priority = "High", add a filter for Metadata Key: priority equals High.
// Example API Payload for Creating a Sampling Rule
POST /api/v2/quality/samplingrules
{
  "name": "SAMPLE_Support_HighPriority",
  "description": "Evaluates 100% of high-priority support calls",
  "priority": 10,
  "status": "ACTIVE",
  "samplingType": "INTERACTION",
  "formId": "12345678-1234-1234-1234-123456789012", // Replace with actual Form ID
  "samplingRate": 100,
  "filters": [
    {
      "name": "interactionType",
      "type": "EQUALS",
      "values": ["CALL"]
    },
    {
      "name": "queueName",
      "type": "EQUALS",
      "values": ["Support_Tier_2"]
    },
    {
      "name": "metadata.priority",
      "type": "EQUALS",
      "values": ["High"]
    }
  ]
}

3. Linking Metadata from Architect to Sampling

Sampling rules rely on metadata present in the interaction record at the time of completion. If the metadata is not present, the rule will not match.

Architectural Reasoning:
Metadata must be set before the interaction ends. If you set metadata in a “Post-Interaction” flow that runs asynchronously, the Sampling Rule engine may have already processed the interaction and missed the rule.

The Trap:
Relying on Disposition Codes alone. Disposition codes are often selected by agents post-call. If an agent forgets to set the disposition, or selects the wrong one, the sampling rule fails.
Solution: Use System-Generated Metadata. In Architect, use the Set Interaction Metadata block to tag interactions based on objective data (e.g., if (callDuration > 600) set metadata.longCall = true). This removes human error from the sampling criteria.

Configuration Steps in Architect:

  1. Open your Architect Flow.
  2. Locate the point where the interaction outcome is determined (e.g., after a database lookup or form submission).
  3. Add a Set Interaction Metadata block.
  4. Define the key-value pair (e.g., Key: outcome, Value: SalesWin).
  5. Ensure this block executes before the End Interaction block.
  6. Publish the flow.

4. Managing Evaluator Workloads via Assignment Rules

While Sampling Rules create evaluations, they do not assign them to specific evaluators by default. By default, evaluations are assigned to the Evaluation Queue or the Agent’s Supervisor.

Architectural Reasoning:
To ensure fairness and expertise, you should use Assignment Rules. These rules direct evaluations to specific users or groups based on criteria such as the agent’s team, the interaction language, or the evaluator’s workload.

The Trap:
Assigning all evaluations to a single “QA Manager” user. This creates a bottleneck and a single point of failure. If that user is on vacation, the QA process halts.
Solution: Use User Groups. Create a group QA_Team_Sales and assign evaluations to this group. Genesys Cloud will distribute evaluations evenly among active members of the group.

Configuration Steps:

  1. Navigate to Admin > Quality > Assignment Rules.
  2. Click Add Assignment Rule.
  3. Rule Name: ASSIGN_Sales_QA_Team.
  4. Priority: Set appropriately.
  5. Assignment Target: Select User Group.
  6. Group: Select QA_Team_Sales.
  7. Filters: Match the filters from your Sampling Rule (e.g., Queue Name: Sales Team).
  8. Status: Set to Active.
// Example API Payload for Creating an Assignment Rule
POST /api/v2/quality/assignmentrules
{
  "name": "ASSIGN_Sales_QA_Team",
  "description": "Assigns Sales evaluations to QA Team",
  "priority": 10,
  "status": "ACTIVE",
  "assignmentTarget": {
    "type": "USER_GROUP",
    "id": "98765432-4321-4321-4321-210987654321" // Replace with actual Group ID
  },
  "filters": [
    {
      "name": "queueName",
      "type": "EQUALS",
      "values": ["Sales Team"]
    }
  ]
}

Validation, Edge Cases & Troubleshooting

Edge Case 1: Missing Metadata in Sampling Rule

The Failure Condition:
Evaluations are not being created for interactions that should match the rule. The Sampling Rule status shows “Active,” but the Evaluation Queue remains empty for the expected volume.

Root Cause:
The metadata key used in the Sampling Rule filter does not exist in the interaction record at the time of evaluation. This often happens if the metadata key name has a typo, or if the Architect flow sets the metadata after the interaction has already been marked as completed in the database.

Solution:

  1. Use the Interaction Search API to inspect a recent interaction that should have been sampled.
  2. Check the metadata field in the JSON response.
  3. Verify the exact key name (case-sensitive).
  4. Ensure the Architect flow sets the metadata before the interaction end block.
  5. Update the Sampling Rule filter to match the exact key name.

Edge Case 2: Sampling Rate Skew

The Failure Condition:
Certain agents are receiving disproportionately more evaluations than others, despite similar call volumes.

Root Cause:
The sampling algorithm is random, but with small sample sizes, statistical variance can cause skew. Additionally, if agents have different shift patterns, and the Sampling Rule is evaluated in real-time, agents working during peak times may be sampled more frequently if the rule is not configured to balance across time windows.

Solution:

  1. Increase the Sample Size to reduce statistical variance.
  2. Use Stratified Sampling by Agent Group to ensure even distribution across teams.
  3. Monitor the Evaluation Distribution Report in Analytics to identify skew.
  4. If necessary, implement a Manual Override process for QA managers to rebalance the queue.

Edge Case 3: Evaluation Form Versioning Conflict

The Failure Condition:
Evaluators report that the Evaluation Form fields do not match the current business requirements. Some evaluations have old fields, while others have new ones.

Root Cause:
The Evaluation Form was edited directly without creating a new version. Existing evaluations linked to the old form version may still be in progress, while new evaluations use the updated form. If the Sampling Rule points to the Form ID, it always uses the latest version, but in-progress evaluations retain the schema they were created with.

Solution:

  1. Never edit a live Evaluation Form directly.
  2. Create a New Version of the form.
  3. Update the Sampling Rule to point to the new Form ID.
  4. Allow a transition period where both forms are active, then deactivate the old form.
  5. Communicate the change to evaluators to ensure they understand the new criteria.

Official References