Implementing Automated Coaching Assignment Pipelines Triggered by Evaluation Score Thresholds

How-To-Articles
1

Implementing Automated Coaching Assignment Pipelines Triggered by Evaluation Score Thresholds

What This Guide Covers

This guide details the architecture for connecting Genesys Cloud Quality evaluations to external Learning Management Systems (LMS) or internal coaching workflows. You will build a pipeline that triggers when an evaluation score falls below a defined threshold, aggregates historical performance data, and automatically assigns targeted coaching modules or manager follow-up tasks via the Genesys Cloud API. The end result is a closed-loop system that reduces manual administrative overhead and ensures consistent, data-driven coaching interventions without agent intervention.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 2 or CX 3 (required for Quality Management and API access).
  • Permissions:
    • quality:evaluation:view and quality:evaluation:update
    • user:read and user:write (for updating agent profiles or notes)
    • task:read and task:write (if using Genesys Tasks for coaching assignments)
    • integration:read and integration:write (for creating the outbound webhook)
  • OAuth Scopes: quality:read, quality:write, user:read, task:write.
  • External Dependencies: An accessible LMS API (e.g., Cornerstone, SAP SuccessFactors, or a custom internal tool) or a Genesys Task queue configured for coaching workflows.
  • Technical Prerequisites: Familiarity with Genesys Cloud Architect flows, REST API pagination, and JSON payload construction.

The Implementation Deep-Dive

1. Establishing the Evaluation Data Contract and Threshold Logic

Before configuring triggers, you must define the data contract between the Quality module and your downstream system. The most common failure in these architectures is attempting to trigger on the raw evaluation score immediately upon submission. This approach fails because evaluations are often submitted in batches, or agents may submit self-evaluations that require manager approval. Triggering on the draft state creates noise and false positives.

You must configure the pipeline to listen only for evaluations with a status of approved or published. Furthermore, you must normalize the score. Genesys Cloud allows weighted sections in evaluations. A raw sum of points is meaningless if Section A is worth 10 points and Section B is worth 50. You must calculate the percentage score based on the total possible points.

The Trap: Relying solely on the score field in the evaluation webhook payload. The score field often represents the raw point total, not the percentage. If your threshold is set to 80, and the evaluation is out of 100 points, an agent with 80/100 passes. But if the evaluation is out of 50 points, an agent with 40/50 (80%) will trigger a “fail” event if you compare the raw score 40 against the threshold 80. This results in a 100% false-positive rate for evaluations with different point scales.

Architectural Reasoning:
To avoid this, you must implement a normalization layer. In your outbound webhook or integration flow, you must retrieve the full evaluation object to access the totalPoints and score fields. Calculate the percentage as (score / totalPoints) * 100. Only proceed if this calculated percentage is less than your defined threshold (e.g., < 75%).

Implementation Steps:

  1. Navigate to Admin > Integrations > Outbound Webhooks.
  2. Create a new webhook named QC_Evaluation_Score_Threshold_Trigger.
  3. Set the Event to quality.evaluation.updated.
  4. Define the Filter to ensure only approved evaluations are processed:
    {
  "status": "approved",
  "evaluationTemplateId": "YOUR_TEMPLATE_ID"
}
  5. In the Payload configuration, select Include full event payload. This ensures you receive the score and totalPoints fields.

2. Building the Normalization and Threshold Logic Flow

The outbound webhook sends data to a middleware or a Genesys Cloud Architect flow. For this guide, we assume an Architect flow is used as the entry point via an HTTP Request block, or a serverless function (AWS Lambda/Azure Function) processes the webhook. Using an Architect flow is preferred for environments that wish to keep logic within Genesys Cloud, but it requires careful handling of synchronous API calls.

The Trap: Making synchronous API calls to Genesys Cloud from an Architect flow that is triggered by a webhook. If the API call to fetch the evaluation details fails or times out, the flow execution halts, and the coaching assignment is never created. More critically, if you process this in a loop for multiple evaluations, you can hit Genesys Cloud API rate limits (1,000 requests per minute per org for standard APIs, higher for bulk). A spike in evaluation submissions can exhaust your API quota, causing other critical systems (like CTI or CRM updates) to fail.

Architectural Reasoning:
You must implement exponential backoff and rate-limiting checks in your logic. If using an external serverless function, you should queue the evaluation ID in a message queue (e.g., AWS SQS) and process them asynchronously. If staying within Genesys Cloud Architect, you must use the System > Set Delay block to space out API calls, ensuring you do not exceed 10 requests per second per user token.

Implementation Steps:

  1. Create an Architect Flow: Name it Flow_Coaching_Assignment_Pipeline.
  2. Entry Point: Add an HTTP Request block. Configure it to accept POST requests with a JSON body.
  3. Extract Data: Use a System > Set Data block to parse the incoming JSON.
    • evaluationId: {{request.body.id}}
    • agentId: {{request.body.agentId}}
    • score: {{request.body.score}}
    • totalPoints: {{request.body.totalPoints}}
  4. Calculate Percentage: Use a Math > Calculate block.
    • Formula: ({{score}} / {{totalPoints}}) * 100
    • Store result in calculatedPercentage.
  5. Threshold Check: Add a Decision block.
    • Condition: {{calculatedPercentage}} < 75
    • If True: Proceed to coaching assignment.
    • If False: End flow.

3. Aggregating Historical Context for Targeted Coaching

Assigning a generic “Improve Skills” task is ineffective. Modern coaching requires context. You must determine why the score was low. Did the agent fail the “Empathy” section, or the “Compliance” section? You must retrieve the detailed evaluation results to identify the weakest section.

The Trap: Assuming the webhook payload contains the section-level scores. It does not. The quality.evaluation.updated event payload is lightweight. It contains the aggregate score, but not the breakdown of points per section. If you do not fetch the full evaluation details, you cannot assign targeted coaching. Fetching the full evaluation details requires a GET /api/v2/quality/evaluations/{id} call.

Architectural Reasoning:
You must perform a secondary API call to retrieve the evaluation details. This call returns an array of sections, each containing questions and scores. You must iterate through this array to find the section with the lowest percentage score. This lowest-scoring section determines the coaching module ID.

Implementation Steps:

  1. API Call: In the Architect flow, add an API > Get Evaluation block.
    • Method: GET
    • Endpoint: /api/v2/quality/evaluations/{{evaluationId}}
    • Authentication: Use a Service Account token with quality:read scope.
  2. Parse Sections: Use a System > Set Data block to extract the sections array.
    • sectionsArray: {{evaluationResponse.sections}}
  3. Find Weakest Section: Use a Loop block to iterate through sectionsArray.
    • Inside the loop, calculate the section percentage: (section.score / section.totalPoints) * 100.
    • Use a Decision block to compare the current section percentage with a lowestSectionPercentage variable.
    • If the current section is lower, update lowestSectionId and lowestSectionName.
  4. Map Section to Coaching Module: Use a Decision block or a Data Lookup (if using a Genesys Data Source) to map the lowestSectionId to a specific LMS course ID or Task Template ID.
    • Example: If lowestSectionId is empathy-section, assign Task_Template_Empathy_Training.

4. Executing the Coaching Assignment via API

Once the targeted coaching module is identified, you must create the assignment. This can be done via two methods: creating a Genesys Cloud Task (if using Genesys WEM/Task Management) or calling an external LMS API. This guide focuses on the Genesys Task method, as it is fully contained within the platform and easier to debug.

The Trap: Assigning tasks to agents who are already overloaded. If you create a task without checking the agent’s current task load, you risk burning out the agent. Furthermore, if you do not set a due date based on the evaluation date, the task may sit in the queue indefinitely.

Architectural Reasoning:
You must calculate a due date that is reasonable relative to the evaluation date. A standard practice is to assign coaching within 5 business days of the evaluation. You must also check if a similar coaching task already exists for this agent and section to avoid duplicate assignments. This requires a POST /api/v2/tasks/query call to search for existing tasks.

Implementation Steps:

  1. Check for Existing Tasks: Add an API > Query Tasks block.
    • Endpoint: /api/v2/tasks/query
    • Body:
      {
  "query": "assignee.id eq '{{agentId}}' and customField.coachingSection eq '{{lowestSectionName}}' and status eq 'open'"
}
    • Note: You must have a custom field coachingSection on your Task template for this to work.
  2. Decision Block: Check the taskCount from the query response.
    • If taskCount > 0: End flow (coaching already assigned).
    • If taskCount == 0: Proceed to create task.
  3. Create Task: Add an API > Create Task block.
    • Method: POST
    • Endpoint: /api/v2/tasks
    • Body:
      {
  "type": "default",
  "priority": "high",
  "status": "open",
  "assignee": {
    "id": "{{agentId}}"
  },
  "dueDate": "{{evaluationDate + 5 days}}",
  "customFields": {
    "coachingSection": "{{lowestSectionName}}",
    "evaluationId": "{{evaluationId}}",
    "score": "{{calculatedPercentage}}"
  },
  "title": "Coaching Required: {{lowestSectionName}}",
  "description": "Your recent evaluation score for {{lowestSectionName}} was below threshold. Please complete the assigned training module."
}
  4. Notify Agent: Optionally, add a System > Send Email block to notify the agent’s manager about the assignment for oversight.

Validation, Edge Cases & Troubleshooting

Edge Case 1: The “Batch Submission” Race Condition

  • The Failure Condition: Multiple evaluations for the same agent are submitted within seconds. The pipeline processes them sequentially, but the API calls to check for existing tasks race against each other.
  • The Root Cause: The check-for-existing-tasks step is not atomic. Task A checks, finds none, and starts creating. Task B checks, finds none (because Task A hasn’t finished creating), and starts creating. Both tasks are created.
  • The Solution: Implement idempotency keys in your Task creation. Use the evaluationId as a unique identifier in the Task’s externalId field (if supported) or in a custom field. Before creating the task, ensure the query includes the specific evaluationId. Alternatively, use a distributed lock (e.g., Redis) in your middleware to ensure only one process handles a specific agentId + section combination at a time.

Edge Case 2: The “Zero-Division” Error in Custom Evaluations

  • The Failure Condition: An evaluation template is configured with sections that have no questions, or all questions are disabled. The totalPoints is 0.
  • The Root Cause: The calculation (score / totalPoints) * 100 results in a division by zero error, causing the Architect flow to fail silently or throw an unhandled exception.
  • The Solution: Add a Decision block before the calculation. If totalPoints == 0, skip the evaluation or log an error. Do not attempt to calculate the percentage. This is a data integrity issue in the Quality template, but your pipeline must be resilient to it.

Edge Case 3: API Rate Limit Exhaustion During Peak Hours

  • The Failure Condition: During end-of-month performance reviews, hundreds of evaluations are approved simultaneously. The outbound webhooks fire rapidly, overwhelming the API gateway.
  • The Root Cause: Genesys Cloud enforces rate limits on API calls. The GET /api/v2/quality/evaluations/{id} and POST /api/v2/tasks calls are subject to these limits.
  • The Solution: Implement exponential backoff in your API calls. If you receive a 429 Too Many Requests response, wait for Retry-After seconds before retrying. In Architect, use the System > Set Delay block to introduce a random jitter (e.g., 1-3 seconds) between processing each evaluation. For high-volume environments, move the logic to an external serverless function with a message queue (SQS) to decouple the trigger from the processing.

Edge Case 4: The “Ghost” Assignment for Terminated Agents

  • The Failure Condition: An agent is terminated, but their final evaluations are still being processed. The pipeline attempts to assign a task to an inactive user.
  • The Root Cause: The API call to create a task fails if the assigneeId refers to an inactive user.
  • The Solution: Before creating the task, verify the agent’s status. Add an API > Get User block to check {{agentResponse.status}}. If the status is inactive or terminated, log the event and do not create the task. Instead, create a task for the agent’s manager to archive the coaching record.

Official References