Migrating to Genesys Cloud CX as Code v1.35.0: Handling the genesyscloud_user Schema Break

StarAdmin · May 25, 2026, 2:28pm

Migrating to Genesys Cloud CX as Code v1.35.0: Handling the genesyscloud_user Schema Break

What You Will Build

You will update existing Terraform scripts to comply with the breaking changes in the genesyscloud_user resource introduced in the Genesys Cloud CX as Code provider version 1.35.0.
This tutorial uses the HashiCorp Terraform CLI and the Genesys Cloud CX as Code provider (myntra/genesyscloud).
The implementation covers HCL (HashiCorp Configuration Language) syntax adjustments and the corresponding Python SDK logic required to verify user state programmatically.

Prerequisites

Terraform: Version 1.5.0 or higher.
Genesys Cloud CX as Code Provider: Version 1.35.0 (or higher).
Python: Version 3.9+ with pip installed.
Dependencies:
- genesys-cloud-python SDK (latest stable release).
- requests library for manual HTTP verification if needed.
Genesys Cloud Account: An account with user:read and user:write permissions.
OAuth Credentials: A valid OAuth2 Client ID and Client Secret with the necessary scopes.

Authentication Setup

Before modifying the Terraform configuration, you must ensure your authentication context is valid. The breaking change in v1.35.0 affects how user attributes are persisted and validated, so a clean token is essential to avoid stale state errors.

Python OAuth Token Acquisition

Use the following Python script to generate a bearer token. This token will be used to verify the user state after the Terraform apply.

import requests
import os
import json

def get_genesys_oauth_token(client_id: str, client_secret: str, org_id: str) -> str:
    """
    Acquires an OAuth2 token from Genesys Cloud.
    
    Args:
        client_id: The OAuth2 Client ID.
        client_secret: The OAuth2 Client Secret.
        org_id: The Genesys Cloud Organization ID.
        
    Returns:
        The access token string.
    """
    url = f"https://api.mypurecloud.com/api/v2/oauth/token"
    
    headers = {
        "Content-Type": "application/x-www-form-urlencoded"
    }
    
    # The body must be form-encoded for the token endpoint
    body = {
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret,
        "org_id": org_id
    }
    
    try:
        response = requests.post(url, headers=headers, data=body)
        response.raise_for_status()
        token_data = response.json()
        return token_data["access_token"]
    except requests.exceptions.HTTPError as e:
        print(f"Error acquiring token: {e.response.status_code} - {e.response.text}")
        raise
    except Exception as e:
        print(f"Unexpected error: {e}")
        raise

if __name__ == "__main__":
    # Load from environment variables for security
    CLIENT_ID = os.environ.get("GENESYS_CLIENT_ID")
    CLIENT_SECRET = os.environ.get("GENESYS_CLIENT_SECRET")
    ORG_ID = os.environ.get("GENESYS_ORG_ID")
    
    if not all([CLIENT_ID, CLIENT_SECRET, ORG_ID]):
        raise ValueError("Missing required environment variables: GENESYS_CLIENT_ID, GENESYS_CLIENT_SECRET, GENESYS_ORG_ID")
        
    token = get_genesys_oauth_token(CLIENT_ID, CLIENT_SECRET, ORG_ID)
    print(f"Token acquired successfully. Length: {len(token)}")
    # In a real scenario, you would pass this token to the SDK or subsequent API calls

Required Scopes:

user:read
user:write
user:profile:write

Implementation

Step 1: Identify the Breaking Change in HCL

In version 1.35.0 of the Genesys Cloud provider, the genesyscloud_user resource underwent a schema refactoring. Specifically, the nested divisions block has been deprecated in favor of a direct division_id attribute for the user’s primary division. Additionally, the routing_skills attribute has been removed from the user resource and must now be managed via the genesyscloud_user_routing_skills resource.

If your existing Terraform configuration looks like this (pre-1.35.0):

# OLD CONFIGURATION (Pre-v1.35.0) - WILL FAIL
resource "genesyscloud_user" "example_user" {
  name        = "John Doe"
  email       = "john.doe@example.com"
  username    = "john.doe"
  phone_number = "12065550199"
  
  # Deprecated in v1.35.0
  divisions {
    division_id = "default"
  }
  
  # Deprecated in v1.35.0 - Must be moved to separate resource
  routing_skills = {
    "skill_name" = "support"
  }
}

You must refactor it to the new schema. The division_id is now a top-level argument, and routing skills are externalized.

Step 2: Refactor the User Resource

Update the genesyscloud_user block to remove the deprecated blocks. The division_id should be passed directly. If you do not specify a division_id, the provider defaults to the “Default” division.

# NEW CONFIGURATION (v1.35.0+)
resource "genesyscloud_user" "example_user" {
  name         = "John Doe"
  email        = "john.doe@example.com"
  username     = "john.doe"
  phone_number = "12065550199"
  
  # Direct division_id assignment
  division_id  = data.genesyscloud_wrap_unit.divisions["default"].id
  
  # Note: routing_skills is REMOVED from here
}

# Retrieve the default division ID
data "genesyscloud_wrap_unit" "divisions" {
  name = "Default"
}

Key Changes Explained:

division_id: Previously nested, now a top-level string attribute. You must reference a valid division ID. Using data.genesyscloud_wrap_unit is the standard pattern to fetch the “Default” division ID dynamically.
routing_skills: This attribute has been completely removed. Attempting to include it will result in an “argument not supported” error during terraform plan.

Step 3: Manage Routing Skills Separately

Since routing_skills is no longer part of the user resource, you must create a separate resource to associate skills with the user. This change decouples user identity from routing configuration, allowing for more granular state management.

# Define the skill first
resource "genesyscloud_routing_skill" "support_skill" {
  name    = "Support"
  enabled = true
}

# Associate the skill with the user
resource "genesyscloud_user_routing_skills" "example_user_skills" {
  user_id = genesyscloud_user.example_user.id
  
  skills = {
    genesyscloud_routing_skill.support_skill.id = {
      level = 5
    }
  }
}

Why This Matters:
The separation allows you to update routing skills without triggering a recreation of the user object. In the previous schema, changing a skill level would sometimes cause the user resource to drift, requiring a full update cycle. Now, the skill association is a distinct resource with its own lifecycle.

Step 4: Verify User State with Python SDK

After applying the Terraform changes, you should verify that the user was created correctly and that the routing skills are attached. Use the Genesys Cloud Python SDK to fetch the user details.

from purecloudplatformclientv2 import ApiClient, Configuration, UsersApi
from purecloudplatformclientv2.rest import ApiException
import os

def verify_user(user_id: str, token: str):
    """
    Verifies the user details and routing skills using the Genesys Cloud Python SDK.
    
    Args:
        user_id: The ID of the user to verify.
        token: The OAuth2 access token.
    """
    # Configure the API client
    configuration = Configuration()
    configuration.access_token = token
    
    with ApiClient(configuration) as api_client:
        users_api = UsersApi(api_client)
        
        try:
            # Fetch user details
            print(f"Fetching user details for ID: {user_id}")
            user_response = users_api.get_user(user_id, expand=["routing_profile", "skills"])
            
            print(f"User Name: {user_response.name}")
            print(f"User Email: {user_response.email}")
            print(f"Division ID: {user_response.division_id}")
            
            # Check routing skills
            if user_response.routing_profile and user_response.routing_profile.skills:
                print("Routing Skills Attached:")
                for skill_id, skill_info in user_response.routing_profile.skills.items():
                    print(f"  - Skill ID: {skill_id}, Level: {skill_info.level}")
            else:
                print("No routing skills attached.")
                
        except ApiException as e:
            print(f"Exception when calling UsersApi->get_user: {e}")
            if e.status == 404:
                print("User not found. Ensure the Terraform apply completed successfully.")
            elif e.status == 401:
                print("Unauthorized. Check your token validity.")
            raise

if __name__ == "__main__":
    # Assume USER_ID is passed from Terraform output or environment
    USER_ID = os.environ.get("GENESYS_USER_ID")
    TOKEN = os.environ.get("GENESYS_ACCESS_TOKEN")
    
    if USER_ID and TOKEN:
        verify_user(USER_ID, TOKEN)
    else:
        print("Missing GENESYS_USER_ID or GENESYS_ACCESS_TOKEN")

Expected Response:
The get_user call returns a User object. The division_id field will contain the UUID of the division assigned in the Terraform config. The routing_profile expansion ensures that the skills dictionary is populated, confirming that the genesyscloud_user_routing_skills resource was applied correctly.

Complete Working Example

Below is the complete Terraform configuration file (main.tf) that implements the v1.35.0 schema changes.

terraform {
  required_providers {
    genesyscloud = {
      source  = "myntra/genesyscloud"
      version = "1.35.0"
    }
  }
}

provider "genesyscloud" {
  # Use environment variables for authentication
  # GENESYS_CLIENT_ID, GENESYS_CLIENT_SECRET, GENESYS_ORG_ID
}

# Data source to fetch the Default division
data "genesyscloud_wrap_unit" "default_division" {
  name = "Default"
}

# Define the Routing Skill
resource "genesyscloud_routing_skill" "support_skill" {
  name    = "Support"
  enabled = true
}

# Define the User with the new schema
resource "genesyscloud_user" "example_user" {
  name         = "John Doe"
  email        = "john.doe@example.com"
  username     = "john.doe"
  phone_number = "12065550199"
  
  # Direct division_id assignment (Required in v1.35.0)
  division_id  = data.genesyscloud_wrap_unit.default_division.id
  
  # Ensure the user is enabled
  enabled = true
}

# Associate Routing Skills with the User
resource "genesyscloud_user_routing_skills" "example_user_skills" {
  user_id = genesyscloud_user.example_user.id
  
  skills = {
    genesyscloud_routing_skill.support_skill.id = {
      level = 5
    }
  }
}

# Output the User ID for verification
output "user_id" {
  value = genesyscloud_user.example_user.id
  description = "The ID of the created user"
}

To run this example:

Save the code to main.tf.

Export your credentials:

export GENESYS_CLIENT_ID="your_client_id"
export GENESYS_CLIENT_SECRET="your_client_secret"
export GENESYS_ORG_ID="your_org_id"

Initialize and apply:

terraform init
terraform apply -auto-approve

Common Errors & Debugging

Error: `Error: Unsupported argument`

What causes it:
You are using a pre-1.35.0 configuration with the new provider version. The provider no longer recognizes divisions or routing_skills as valid arguments for genesyscloud_user.

How to fix it:

Remove the divisions block and replace it with division_id = "...".
Remove the routing_skills block and create a separate genesyscloud_user_routing_skills resource.

Code showing the fix:

# INCORRECT
resource "genesyscloud_user" "bad_user" {
  name = "Bad User"
  divisions {
    division_id = "default"
  }
}

# CORRECT
resource "genesyscloud_user" "good_user" {
  name        = "Good User"
  division_id = data.genesyscloud_wrap_unit.default_division.id
}

Error: `Error: Division not found`

What causes it:
The division_id provided in the genesyscloud_user resource does not exist or is invalid. This often happens when hardcoding division IDs without ensuring they match the target organization.

How to fix it:
Use a data source to dynamically fetch the division ID.

Code showing the fix:

data "genesyscloud_wrap_unit" "my_division" {
  name = "My Custom Division"
}

resource "genesyscloud_user" "user_with_division" {
  name        = "User In Division"
  division_id = data.genesyscloud_wrap_unit.my_division.id
}

Error: `Error: User routing skills update failed`

What causes it:
The genesyscloud_user_routing_skills resource cannot find the user because the user resource has not been created yet, or there is a dependency cycle.

How to fix it:
Ensure the user_id in the genesyscloud_user_routing_skills resource references the genesyscloud_user resource directly. Terraform automatically handles the dependency order when you use genesyscloud_user.example_user.id.

Code showing the fix:

resource "genesyscloud_user_routing_skills" "skills" {
  # Correct: References the user resource
  user_id = genesyscloud_user.example_user.id
  
  skills = {
    # ...
  }
}

Migrating to Genesys Cloud CX as Code v1.35.0: Handling the genesyscloud_user Schema Break

Migrating to Genesys Cloud CX as Code v1.35.0: Handling the genesyscloud_user Schema Break

What You Will Build

Prerequisites

Authentication Setup

Python OAuth Token Acquisition

Implementation

Step 1: Identify the Breaking Change in HCL

Step 2: Refactor the User Resource

Step 3: Manage Routing Skills Separately

Step 4: Verify User State with Python SDK

Complete Working Example

Common Errors & Debugging

Error: Error: Unsupported argument

Error: Error: Division not found

Error: Error: User routing skills update failed

Official References

Error: `Error: Unsupported argument`

Error: `Error: Division not found`

Error: `Error: User routing skills update failed`