Implementing Skill and Queue Taxonomy Mapping Tables for Cross-Platform Agent Portability

How-To-Articles
1

Implementing Skill and Queue Taxonomy Mapping Tables for Cross-Platform Agent Portability

What This Guide Covers

This guide details the architecture and implementation of a canonical skill and queue taxonomy with mapping tables that enable agent portability between Genesys Cloud CX and NICE CXone. You will construct a versioned mapping structure, implement lookup logic in Genesys Cloud Architect and CXone Studio, and orchestrate provisioning APIs to transfer agent routing profiles without losing context or violating business rules. The end result is a resilient routing abstraction layer where agents can be provisioned, de-provisioned, or migrated across platforms while maintaining correct skill alignment and queue access.

Prerequisites, Roles & Licensing

Genesys Cloud CX

  • Licensing: CX 3 tier required for advanced routing capabilities, Data Table API access, and Architect HTTP Request blocks.
  • Permissions:
    • routing:skill:read, routing:skill:write
    • routing:queue:read, routing:queue:write
    • user:read, user:write
    • analytics:datatable:read, analytics:datatable:write
    • architect:flow:read, architect:flow:write
  • OAuth Scopes: agent, routing:skill, routing:queue, user, analytics:datatable.

NICE CXone

  • Licensing: Premium tier required for Studio JSON Router advanced logic and User API skill mapping.
  • Permissions:
    • Routing:Skill:Read, Routing:Skill:Write
    • Routing:Queue:Read, Routing:Queue:Write
    • User:Read, User:Write
  • OAuth Scopes: routing:skill, routing:queue, user.

External Dependencies

  • Middleware: An integration layer (e.g., MuleSoft, Boomi, or custom Node.js/Python service) capable of hosting the canonical taxonomy, performing bidirectional lookups, and executing provisioning APIs.
  • Data Store: A relational database or document store supporting versioned JSON documents for the mapping tables.

The Implementation Deep-Dive

1. Canonical Taxonomy Design and Normalization

Cross-platform portability fails when platforms rely on display names or platform-specific IDs as the source of truth. Genesys Cloud uses UUIDs for skills and queues, while CXone uses integer IDs or string keys. Furthermore, structural differences exist: Genesys Cloud separates Skills from Skill Groups, whereas CXone often bundles skills within Routers or Teams.

We define a Canonical Taxonomy Identifier (CTID) that exists outside both platforms. The CTID represents the business concept, not the technical implementation.

The Canonical Schema:

{
  "ctid": "TAX_PAYMENTS_CC_001",
  "business_name": "Payments_Credit_Card",
  "description": "Agent capability for credit card payment processing",
  "effective_date": "2023-01-01T00:00:00Z",
  "expiry_date": null,
  "attributes": {
    "pci_required": true,
    "region": "US_EAST"
  }
}

The Trap: Structural Cardinality Mismatches

A common architectural error is assuming a 1:1 mapping between Genesys Skills and CXone Skills. In complex deployments, a single Genesys Skill (e.g., Support_Tier2) may map to multiple CXone Skills (e.g., Support_Tech, Support_Billing) depending on the agent’s specialization. Conversely, a CXone Skill may aggregate multiple Genesys Skills for a generic routing purpose.

The mapping table must support N:M cardinality. If you force a 1:1 mapping, you will either over-provision agents in the target platform (granting skills they do not possess) or under-provision them (blocking valid routing). The mapping structure must explicitly define cardinality and normalization rules.

2. Mapping Table Architecture and Versioning

The mapping table acts as the translation layer. It resides in your middleware data store and is consumed by both platforms via API or loaded into platform-native caches (Genesys Data Tables, CXone Studio JSON).

Mapping Table Structure:

{
  "version": "2023-10-25.01",
  "updated_at": "2023-10-25T14:30:00Z",
  "mappings": [
    {
      "ctid": "TAX_PAYMENTS_CC_001",
      "genesys": {
        "skill_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "queue_ids": ["q1x2y3z4-..."],
        "routing_type": "SKILL"
      },
      "cxone": {
        "skill_id": "SKILL_998877",
        "queue_ids": ["QUEUE_554433"],
        "routing_type": "SKILL"
      },
      "portability_rules": {
        "direction": "BIDIRECTIONAL",
        "fallback_ctid": "TAX_PAYMENTS_GENERIC",
        "validation_check": "PCI_CERTIFIED"
      }
    }
  ]
}

The Trap: Stale Mapping Versions During Migration Windows

During a cutover or active portability event, the mapping table may change (e.g., a skill is deprecated in Genesys but still active in CXone). If the platforms cache the mapping table without strict version checking, agents may be provisioned with obsolete skills.

We implement a mandatory version check. Every lookup request from Genesys Architect or CXone Studio must include the version header or query parameter. The middleware returns a 412 Precondition Failed if the cached version is stale, forcing an immediate cache invalidation. This prevents silent failures where routing logic relies on decommissioned CTIDs.

3. Genesys Cloud Implementation: Data Tables and Architect Logic

In Genesys Cloud, we use Data Tables to cache the mapping table for low-latency lookups within Architect flows. The Data Table is populated via the Analytics Data Table API during mapping updates.

Loading the Mapping Table:

PUT /api/v2/analytics/datatable/bulk
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "name": "CrossPlatform_SkillMapping",
  "key": "ctid",
  "items": [
    {
      "key": "TAX_PAYMENTS_CC_001",
      "genesys_skill_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "cxone_skill_id": "SKILL_998877",
      "cxone_queue_ids": ["QUEUE_554433"],
      "version": "2023-10-25.01"
    }
  ]
}

Architect Lookup Flow:

When an agent is being ported or a call requires cross-platform context resolution, the Architect flow performs a lookup against the Data Table.

  1. Get Data Block: Retrieve agent’s current Genesys skill profile.
  2. Split Block: Iterate over skills.
  3. Get Data (Data Table): Lookup ctid using the Genesys skill ID reverse map (or use CTID if passed via context).
  4. Set Data: Store cxone_skill_id and cxone_queue_ids in the interaction context.
  5. HTTP Request: Send context to middleware for provisioning validation.

The Trap: Data Table Key Collisions and Performance Degradation

Genesys Data Tables are optimized for key-based lookups. If you attempt to load the entire mapping table with a composite key or without a unique key, lookups degrade to linear scans, causing Architect flow timeouts under load.

Always define a single, immutable key (the ctid). If you need to lookup by Genesys Skill ID, maintain a separate reverse-lookup Data Table or use a “Get Data” block with a filter expression that references the ctid primary key. Do not store arrays directly in Data Table items if the array size exceeds 50 elements; Genesys imposes serialization limits. For large queue mappings, store a reference ID and fetch the array via a secondary middleware call.

4. CXone Implementation: Studio JSON and Routing Context

In CXone, we implement the mapping logic using Studio JSON Snippets. CXone Studio allows direct JSON manipulation, which we use to resolve CTIDs and prepare provisioning payloads.

Studio Snippet for Mapping Resolution:

{
  "type": "snippet",
  "id": "resolve_cross_platform_mapping",
  "label": "Resolve CTID to CXone Skill",
  "inputs": [
    {
      "name": "genesys_skill_id",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "name": "cxone_skill_id",
      "type": "string"
    },
    {
      "name": "mapped_queue_ids",
      "type": "array"
    }
  ],
  "actions": [
    {
      "type": "http_get",
      "url": "https://middleware.internal/mapping/lookup?genesys_skill_id={{genesys_skill_id}}",
      "headers": {
        "X-Version": "{{env.mapping_version}}"
      },
      "success": {
        "set": {
          "cxone_skill_id": "{{response.cxone_skill_id}}",
          "mapped_queue_ids": "{{response.cxone_queue_ids}}"
        }
      },
      "failure": {
        "set": {
          "cxone_skill_id": "FALLBACK_GENERIC",
          "error_code": "MAPPING_NOT_FOUND"
        }
      }
    }
  ]
}

The Trap: CXone Skill Name Collisions and ID Stability

CXone allows skills to be renamed without changing the underlying ID, but some legacy integrations or misconfigured routers rely on skill names. If your mapping table uses skill names instead of skill_id, a rename operation in CXone breaks the portability logic immediately.

Ensure the mapping table references the immutable skill_id. In CXone Studio, always use {{skills.id}} references rather than {{skills.name}}. When provisioning agents via API, use the skill_id in the payload. The skill_id in CXone is stable across renames and reorganizations, whereas names are volatile.

5. Portability Orchestration and Provisioning APIs

The mapping table drives the actual agent portability. When an agent moves from Genesys to CXone, the middleware consumes the mapped IDs and executes the provisioning sequence.

Genesys to CXone Provisioning Payload:

PATCH /api/v2/users/{userId}
Content-Type: application/json
Authorization: Bearer {cxone_token}

{
  "routing": {
    "skills": [
      {
        "id": "SKILL_998877",
        "level": 80,
        "status": "ACTIVE"
      }
    ],
    "queues": [
      {
        "id": "QUEUE_554433",
        "status": "LOGGED_IN"
      }
    ]
  }
}

CXone to Genesys Provisioning Payload:

PUT /api/v2/users/{userId}/routing/profile
Content-Type: application/json
Authorization: Bearer {genesys_token}

{
  "skills": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "level": 80,
      "status": "ACTIVE"
    }
  ],
  "queues": [
    {
      "id": "q1x2y3z4-...",
      "status": "LOGGED_IN"
    }
  ]
}

The Trap: Asynchronous State Consistency and Agent “Dark” States

Provisioning APIs are asynchronous. When you PATCH a CXone user, the skill update may take seconds to propagate to the routing engine. If you immediately set the agent’s status to LOGGED_IN, the agent may appear online in the UI but remain unroutable in the queue, creating a “dark” state where calls are dropped or abandoned.

We implement a verification loop in the middleware. After the provisioning API returns 200 OK, the middleware polls the target platform’s GET /users/{userId}/routing/profile endpoint until the skill status matches the expected state. Only upon confirmation does the middleware trigger the status change to LOGGED_IN. This adds latency but guarantees routing availability.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Orphaned CTIDs During Taxonomy Refactoring

The Failure Condition:
A business unit retires a product line. The CTID TAX_LEGACY_PROD_001 is removed from the canonical taxonomy. Agents still have this skill in Genesys Cloud. The mapping table no longer contains an entry for this CTID. The portability workflow fails to find a mapping, and the agent is provisioned in CXone with zero skills.

The Root Cause:
The mapping table cleanup is decoupled from the taxonomy retirement process. The middleware deleted the mapping row without checking for active agent associations.

The Solution:
Implement a “Soft Delete” and “Deprecation” lifecycle in the mapping table. When a CTID is retired, set status: DEPRECATED and define a replacement_ctid. The portability logic checks for deprecated CTIDs and automatically remaps to the replacement. For agents with no replacement, the logic routes to a “Review” queue rather than provisioning with empty skills. This prevents silent data loss.

Edge Case 2: Skill Level Normalization Mismatches

The Failure Condition:
Genesys Cloud uses a skill level scale of 0-100. CXone also uses 0-100, but the business logic interprets levels differently. In Genesys, level 50 might mean “Junior,” while in CXone, level 50 means “Senior” due to historical configuration. An agent with level 50 in Genesys is ported to CXone with level 50, but receives high-complexity calls they cannot handle, causing CSAT degradation.

The Root Cause:
The mapping table copies the skill level value verbatim without normalization. The platforms share a numeric range but not a semantic meaning.

The Solution:
Add a level_transform function to the mapping table. The middleware applies the transformation during provisioning.

{
  "ctid": "TAX_SUPPORT_TECH",
  "level_transform": {
    "source": "GENESYS",
    "target": "CXONE",
    "formula": "Math.floor(source_level * 0.8)"
  }
}

This ensures semantic parity. The middleware calculates the target level before sending the provisioning payload.

Edge Case 3: Concurrent Mapping Updates Causing Split-Brain Routing

The Failure Condition:
An administrator updates a skill mapping in the middleware while an active portability request is in flight. The Genesys Architect flow has already fetched the mapping version v1, but the middleware provisioning service fetches version v2. The agent is provisioned with skills from v2, but the Genesys context expects v1. The agent ends up in a queue that does not match their Genesys skill profile, causing reporting discrepancies and potential compliance violations.

The Root Cause:
Lack of transactional consistency across the distributed lookup and provisioning operations.

The Solution:
Use a request-scoped mapping token. The Genesys flow requests a portability_token from the middleware. This token locks the mapping version for the duration of the request. All subsequent API calls within that portability transaction must include the token. The middleware validates the token and ensures the same mapping version is used for lookup, validation, and provisioning. If the mapping version changes, the token becomes invalid, and the transaction aborts with a retryable error.

Official References