Implementing Custom Shrinkage Metrics for Off-Queue Training Modules
What This Guide Covers
Configure Genesys Cloud WFM to track, calculate, and report shrinkage for specialized training sessions that operate outside standard queue routing. You will establish custom status mappings, ingest training module metadata via the WFM API, and build adherence calculations that isolate off-queue training time from standard shrinkage pools.
Prerequisites, Roles & Licensing
- Licensing Tier: Genesys Cloud CX WFM Advanced or WFM Professional. Standard WFM does not support custom attribute ingestion or adherence rule customization.
- Role-Based Permissions:
wfm:customattributes:editwfm:adherence:editwfm:schedules:editanalytics:reports:viewuser:customattributes:view
- OAuth Scopes:
wfm:customattributes,wfm:adherence,wfm:schedules,wfm:timecards,analytics:reports - External Dependencies: Learning Management System (LMS) with REST/webhook capability, middleware service for event transformation (Node.js, Python, or Azure Function), and a shared timezone reference (UTC recommended for all internal processing).
The Implementation Deep-Dive
1. Design the Custom Status & Shrinkage Taxonomy
The WFM adherence engine evaluates agent availability against scheduled blocks by mapping status codes to shrinkage categories. Default Genesys statuses such as Training or Not Ready collapse all non-routable time into a single shrinkage bucket. This aggregation destroys reporting fidelity when leadership requires module-level shrinkage attribution. You must isolate off-queue training into a dedicated status taxonomy that the adherence engine can parse deterministically.
Create a custom agent status in Genesys Cloud Admin under Telephony > Statuses. Name it OFF_QUEUE_TRAINING and assign it a unique statusId. Disable queue routing for this status. This ensures agents cannot receive inbound or outbound interactions while the status is active. The adherence engine treats this status as a shrinkage candidate only when explicitly mapped in the shrinkage configuration matrix.
The Trap: Naming the custom status Training_Module_X and creating a separate status for each course. The Genesys status engine has a hard limit of 50 custom statuses per organization. Exhausting this limit blocks other critical telephony configurations. Furthermore, the adherence engine cannot dynamically parse status names for calculation logic. It requires a single canonical status paired with metadata.
Architectural Reasoning: We use a single canonical status (OFF_QUEUE_TRAINING) to preserve status slot capacity and maintain deterministic adherence evaluation. Granularity is achieved through WFM Custom Attributes attached to the agent record during the training session. The adherence engine evaluates the status for shrinkage eligibility, while the custom attributes provide the dimensional breakdown for reporting. This separation of concerns prevents adherence rule explosion and keeps the telephony layer decoupled from WFM reporting logic.
Configure the shrinkage mapping in WFM > Settings > Shrinkage. Add OFF_QUEUE_TRAINING to the Planned Shrinkage category. Set the default shrinkage percentage to 100% because the agent is completely unavailable for customer contact. Do not apply partial shrinkage percentages at this stage. Partial shrinkage applies to meetings where agents handle overflow calls. Off-queue training requires full shrinkage attribution.
2. Provision Custom Attributes & API Ingestion Pipeline
Custom attributes store the training module identifier, expected duration, and completion state. The WFM API exposes a custom attribute schema that binds to user IDs and persists across timecard generation cycles. You must define these attributes before ingesting LMS events.
Execute the following API call to register the custom attribute schema. Replace {orgId} with your Genesys Cloud organization identifier.
POST /api/v2/wfm/customattributes
Authorization: Bearer {access_token}
Content-Type: application/json
{
"name": "training_module_id",
"type": "string",
"description": "LMS course identifier for off-queue training shrinkage attribution",
"isSystem": false,
"defaultValue": "",
"isDeleted": false
}
Repeat this call for training_expected_duration_minutes (type: integer) and training_completion_state (type: string). Record the returned id values. These identifiers drive all subsequent API payloads.
Build an ingestion pipeline that listens for LMS course start events. The middleware service must transform the LMS payload into a Genesys Cloud custom attribute update. Use the PUT endpoint to attach the attribute to the agent’s user record. The adherence engine reads custom attributes at the time of timecard aggregation. Delayed attribute updates result in orphaned shrinkage records.
PUT /api/v2/wfm/customattributes/user/{userId}/training_module_id
Authorization: Bearer {access_token}
Content-Type: application/json
{
"value": "CRM_ADV_ONBOARDING_V2",
"updatedBy": "lms-integration-service",
"updatedDate": "2024-06-15T14:30:00.000Z"
}
The Trap: Updating custom attributes after the training session concludes. The WFM timecard generator runs on a rolling 15-minute window. If the attribute update arrives after the window closes, the adherence engine classifies the time as Unplanned Absence or Unknown Shrinkage. This creates false compliance violations and requires manual timecard overrides.
Architectural Reasoning: We push the custom attribute update immediately upon LMS course initiation. The middleware service issues the PUT request with an idempotency key derived from {userId}_{courseId}_{timestamp}. Idempotency prevents duplicate attribute writes during webhook retry storms. The WFM engine snapshots the attribute state at the start of each adherence evaluation cycle. Immediate provisioning guarantees the shrinkage calculation attaches to the correct time block. We also implement a fallback cron job that scans for unattributed OFF_QUEUE_TRAINING status blocks older than 45 minutes and queries the LMS API directly to reconcile missing attributes.
3. Configure WFM Adherence Rules & Shrinkage Calculations
The adherence engine requires explicit rules to recognize off-queue training as valid shrinkage. Without rule configuration, the engine treats any deviation from scheduled queue availability as a violation, regardless of status mapping. You must define an adherence rule that correlates the OFF_QUEUE_TRAINING status with the custom attribute presence.
Navigate to WFM > Adherence > Rules. Create a new rule with the following configuration parameters:
- Rule Name:
Off-Queue Training Shrinkage Validation - Trigger:
Status Change - Condition:
Status == OFF_QUEUE_TRAINING AND training_module_id != null - Action:
Mark as Planned Shrinkage - Shrinkage Category:
Training - Override Threshold:
0 minutes
Export the rule definition via the API to verify the JSON structure. The adherence engine evaluates rules sequentially. Place this rule above generic Not Ready shrinkage rules to prevent rule shadowing.
POST /api/v2/wfm/adherence/rules
Authorization: Bearer {access_token}
Content-Type: application/json
{
"name": "Off-Queue Training Shrinkage Validation",
"enabled": true,
"priority": 10,
"conditions": [
{
"field": "statusId",
"operator": "EQUALS",
"value": "OFF_QUEUE_TRAINING"
},
{
"field": "customAttributes.training_module_id",
"operator": "IS_NOT_NULL",
"value": null
}
],
"actions": [
{
"type": "SET_SHRINKAGE",
"category": "Training",
"percentage": 100,
"overrideUnplanned": true
}
],
"evaluationScope": "AGENT_STATUS"
}
Configure the WFM schedule template to include explicit training blocks. The schedule block must match the LMS expected duration. Use the scheduleBlock API to provision recurring training slots. The adherence engine compares actual status history against these blocks. If the actual OFF_QUEUE_TRAINING duration exceeds the scheduled block by more than the configured grace period, the engine flags the overflow as unplanned shrinkage.
The Trap: Setting the grace period to 0 minutes for training blocks. Network latency, LMS login friction, and agent status transition delays routinely create 2-5 minute variances. A zero-grace configuration generates false adherence violations on 60-80% of training sessions. Leadership then loses trust in the reporting pipeline.
Architectural Reasoning: We apply a 5-minute grace period to training schedule blocks. This accommodates status transition latency without masking genuine attendance issues. The adherence engine calculates adherence as (Actual Duration - Grace Period) / Scheduled Duration. We also enable overrideUnplanned: true in the rule action. This prevents the engine from double-counting shrinkage when the status transitions slightly outside the scheduled window. The rule explicitly whitelists the status-attribute combination, ensuring the shrinkage pool remains accurate even when schedule alignment drifts.
Validation, Edge Cases & Troubleshooting
Edge Case 1: Timestamp Drift Between LMS and WFM Timecards
The failure condition: Training shrinkage reports show negative duration or zero attribution despite agents logging the correct status.
The root cause: The LMS emits course start timestamps in local timezone, while the WFM timecard engine ingests UTC. A 6-hour timezone offset causes the adherence engine to evaluate the status block against a schedule window that has already passed. The engine discards the mismatched block and routes it to the Unaccounted Time bucket.
The solution: Normalize all LMS webhook payloads to UTC before ingestion. Configure the middleware service to parse the X-Forwarded-Timezone header or append a timezone conversion step using IANA timezone database mappings. Validate the timestamp format matches ISO 8601 with explicit Z suffix. Implement a reconciliation job that cross-references WFM timecard start times with LMS completion logs. Flag any variance exceeding 90 seconds for manual review.
Edge Case 2: Overlapping Status Transitions During Queue Handoffs
The failure condition: Agents receive adherence violations for OFF_QUEUE_TRAINING blocks that immediately follow queue wrap-up periods.
The root cause: The Genesys telephony layer requires a mandatory Available or Not Ready state between queue wrap-up and custom status transitions. Agents clicking OFF_QUEUE_TRAINING directly from a wrap-up screen trigger a status collision. The WFM engine records the transition time as the wrap-up end time, splitting the shrinkage block across two adherence evaluation windows.
The solution: Enforce a status transition sequence in the Architect flow or desktop client configuration. Insert a 10-second Not Ready buffer between queue wrap-up and custom status selection. Update the adherence rule to ignore status blocks shorter than 120 seconds. Configure the WFM timecard generator to merge adjacent shrinkage blocks with identical custom attribute values. This consolidation prevents artificial fragmentation of training shrinkage metrics.
Edge Case 3: Custom Attribute Persistence Across Schedule Resets
The failure condition: Training shrinkage attributes persist into the next business day, causing false shrinkage attribution during off-hours.
The root cause: WFM custom attributes do not auto-expire. If the LMS completion webhook fails or the middleware service drops the update, the training_module_id remains attached to the user record. The adherence engine applies the training shrinkage rule to any subsequent OFF_QUEUE_TRAINING status event, even if the agent is simply taking an extended break.
The solution: Implement an attribute lifecycle manager. The middleware service must issue a DELETE or value: null update to the custom attribute upon receiving the LMS completion event. Add a scheduled cleanup job that runs daily at 00:00 UTC. The job queries all user records with non-null training attributes and clears them if no corresponding timecard entry exists within the past 24 hours. This prevents attribute bleed across schedule boundaries.