Define a Genesys Cloud Queue with Skills in Terraform Using the CX as Code Provider

How-To-Articles
1

Define a Genesys Cloud Queue with Skills in Terraform Using the CX as Code Provider

What You Will Build

  • You will provision a Genesys Cloud queue with specific skill requirements using Infrastructure as Code.
  • This tutorial utilizes the genesyscloud Terraform provider (formerly CX as Code).
  • The implementation uses Terraform HCL (HashiCorp Configuration Language) to define the resource.

Prerequisites

  • Terraform Version: 1.5.0 or higher.
  • Genesys Cloud Provider Version: 2.0.0 or higher.
  • OAuth Client Credentials: A Genesys Cloud OAuth client with the following scopes:
    • routing:queue:write
    • routing:skill
    • routing:skillgroup (if assigning skill groups)
    • routing:wrapupcode (if assigning wrap-up codes)
  • Environment Variables: GENESYS_CLOUD_REGION (e.g., us-east-1) and credentials (GENESYS_CLOUD_CLIENT_ID, GENESYS_CLOUD_CLIENT_SECRET, or GENESYS_CLOUD_USERNAME/GENESYS_CLOUD_PASSWORD).

Authentication Setup

The Genesys Cloud Terraform provider handles OAuth token acquisition automatically when valid credentials are provided. You must configure the provider block in your root module. The provider supports multiple authentication methods; client credentials flow is recommended for CI/CD pipelines.

terraform {
  required_providers {
    genesyscloud = {
      source  = "mypurecloud/genesyscloud"
      version = "~> 2.0"
    }
  }
}

provider "genesyscloud" {
  # Option 1: Client Credentials (Recommended for CI/CD)
  # Ensure GENESYS_CLOUD_CLIENT_ID and GENESYS_CLOUD_CLIENT_SECRET are set in environment
  # Option 2: Username/Password (For local development)
  # username = var.genesys_username
  # password = var.genesys_password
  
  # Region is required if not set in environment variable GENESYS_CLOUD_REGION
  # region   = "us-east-1"
}

This configuration initializes the PureCloudPlatformClientV2 SDK internally. If authentication fails, Terraform will throw an error during the init or plan phase, typically indicating an invalid grant or missing scope.

Implementation

Step 1: Define the Queue Resource

The core resource is genesyscloud_routing_queue. This resource maps directly to the /api/v2/routing/queues endpoint. You must define the name, description, and enabled status.

resource "genesyscloud_routing_queue" "support_queue" {
  name        = "Customer Support - Tier 1"
  description = "Primary queue for inbound customer support inquiries."
  enabled     = true

  # Outbound settings (optional but recommended for completeness)
  outbound_enabled = false
  outbound_type    = "DISABLED"

  # Default wrap-up code (optional)
  default_wrapup_code_id = genesyscloud_routing_wrapupcode.default.id

  # Queue flow association (optional)
  # queue_flow_id = data.genesyscloud_flow.queue_flow.id
}

Expected Response Behavior:
When this resource is applied, the provider sends a POST request to /api/v2/routing/queues. The API returns a 201 Created status with the queue ID. The provider stores this ID in the state file. If the queue already exists with the same name, the provider may update it depending on the name uniqueness constraint and provider version behavior.

Error Handling:
If the name is already taken, the API returns a 409 Conflict. The Terraform provider logs this error. Ensure queue names are unique within your Genesys Cloud organization.

Step 2: Define Skills and Assign to Queue

Skills are defined via genesyscloud_routing_skill. A queue requires skills if you intend to route based on agent proficiency. You must first create the skill, then reference it in the queue’s skill_requirements.

# 1. Define the Skill
resource "genesyscloud_routing_skill" "english_skill" {
  name = "English - Fluent"
}

resource "genesyscloud_routing_skill" "technical_skill" {
  name = "Technical Support - Level 1"
}

# 2. Reference Skills in the Queue
resource "genesyscloud_routing_queue" "support_queue" {
  name        = "Customer Support - Tier 1"
  description = "Primary queue for inbound customer support inquiries."
  enabled     = true

  outbound_enabled = false
  outbound_type    = "DISABLED"

  # Skill Requirements Configuration
  skill_requirements {
    # Reference the skill resource created above
    skill_id = genesyscloud_routing_skill.english_skill.id
    
    # Priority: 1 is highest priority, 999 is lowest
    priority = 1
    
    # Required: Whether this skill is mandatory for the agent to be eligible
    required = true
  }

  skill_requirements {
    skill_id = genesyscloud_routing_skill.technical_skill.id
    priority = 2
    required = false # Optional skill
  }
}

Non-Obvious Parameters:

  • priority: This integer determines the order in which skills are evaluated by the routing engine. Lower numbers are evaluated first.
  • required: If set to true, an agent without this skill will not be considered for the conversation. If false, the skill is used for ranking but not as a hard filter.

Edge Cases:
If you delete a skill referenced in a queue, the queue update will fail with a 400 Bad Request because the skill_id no longer exists. You must remove the skill_requirements block from the queue before deleting the skill.

Step 3: Assign Agents to the Queue via Skill Groups

While agents can be added directly to a queue, best practice in Genesys Cloud is to use Skill Groups. This decouples agent management from queue configuration.

# 1. Create a Skill Group
resource "genesyscloud_routing_skillgroup" "support_agents" {
  name        = "Support Agents - English"
  description = "Agents proficient in English support."
  enabled     = true

  # Add the skill to the skill group
  skill_ids = [genesyscloud_routing_skill.english_skill.id]
}

# 2. Add Agents to the Skill Group (Example with one agent)
# Note: In production, use a for_each loop with a data source of agents
resource "genesyscloud_routing_skillgroup_member" "agent_member" {
  skill_group_id = genesyscloud_routing_skillgroup.support_agents.id
  agent_id       = var.agent_id # Pass agent ID from variable
}

# 3. Link Skill Group to Queue
resource "genesyscloud_routing_queue" "support_queue" {
  # ... previous configuration ...

  # Add the skill group to the queue
  skill_group_ids = [genesyscloud_routing_skillgroup.support_agents.id]
}

Pagination and Limits:
The Genesys Cloud API has limits on the number of members in a skill group. If you are adding hundreds of agents, the Terraform provider handles batching internally. However, plan execution may take longer.

Complete Working Example

This example combines queue creation, skill definition, skill group creation, and association into a single module.

terraform {
  required_providers {
    genesyscloud = {
      source  = "mypurecloud/genesyscloud"
      version = "~> 2.0"
    }
  }
}

provider "genesyscloud" {
  # Credentials handled via environment variables
}

variable "agent_id" {
  description = "ID of the agent to add to the support skill group"
  type        = string
}

variable "region" {
  description = "Genesys Cloud region"
  type        = string
  default     = "us-east-1"
}

# 1. Define Skills
resource "genesyscloud_routing_skill" "skill_en" {
  name = "Language-English"
}

resource "genesyscloud_routing_skill" "skill_tech" {
  name = "Domain-Technical"
}

# 2. Define Skill Group
resource "genesyscloud_routing_skillgroup" "sg_support" {
  name        = "Support Team EN"
  description = "English speaking support agents"
  enabled     = true
  skill_ids   = [genesyscloud_routing_skill.skill_en.id]
}

# 3. Assign Agent to Skill Group
resource "genesyscloud_routing_skillgroup_member" "member_support" {
  skill_group_id = genesyscloud_routing_skillgroup.sg_support.id
  agent_id       = var.agent_id
}

# 4. Define Queue with Skills and Skill Groups
resource "genesyscloud_routing_queue" "queue_support" {
  name        = "Support Queue EN"
  description = "Queue for English support requests"
  enabled     = true

  outbound_enabled = false
  outbound_type    = "DISABLED"

  # Skill Requirements
  skill_requirements {
    skill_id = genesyscloud_routing_skill.skill_en.id
    priority = 1
    required = true
  }

  skill_requirements {
    skill_id = genesyscloud_routing_skill.skill_tech.id
    priority = 2
    required = false
  }

  # Associated Skill Groups
  skill_group_ids = [genesyscloud_routing_skillgroup.sg_support.id]

  # Optional: Default Wrap-up Code
  # default_wrapup_code_id = genesyscloud_routing_wrapupcode.default.id
}

output "queue_id" {
  value = genesyscloud_routing_queue.queue_support.id
}

output "queue_name" {
  value = genesyscloud_routing_queue.queue_support.name
}

To run this example:

  1. Save as main.tf.
  2. Run terraform init.
  3. Run terraform plan -var="agent_id=<ACTUAL_AGENT_ID>".
  4. Run terraform apply -var="agent_id=<ACTUAL_AGENT_ID>".

Common Errors & Debugging

Error: 409 Conflict on Queue Name

What causes it:
Genesys Cloud enforces unique queue names within an organization. If you attempt to create a queue with a name that already exists, the API returns a 409.

How to fix it:
Ensure the name attribute in genesyscloud_routing_queue is unique. If you are reusing code across environments, include the environment name in the queue name (e.g., "Support Queue - Dev").

Code showing the fix:

resource "genesyscloud_routing_queue" "support_queue" {
  name = "${var.environment}-Customer Support"
  # ...
}

Error: 400 Bad Request on Skill ID

What causes it:
The skill_id referenced in skill_requirements does not exist or has been deleted.

How to fix it:
Verify that the genesyscloud_routing_skill resource is created before the queue. Terraform dependency management usually handles this, but if you import existing resources, ensure the skill exists.

Code showing the fix:
Check the terraform state list to ensure the skill resource is tracked.

terraform state list genesyscloud_routing_skill.skill_en

Error: Provider Panics on Missing Region

What causes it:
The GENESYS_CLOUD_REGION environment variable is not set, and the region is not specified in the provider block.

How to fix it:
Set the environment variable or add the region to the provider block.

Code showing the fix:

provider "genesyscloud" {
  region = "us-east-1"
}

Official References