Migrating Genesys Cloud User Resources to Provider v1.35.0 Schema

How-To-Articles
1

Migrating Genesys Cloud User Resources to Provider v1.35.0 Schema

What You Will Build

  • You will update existing Terraform configurations to resolve schema conflicts introduced in the Genesys Cloud CX as Code provider version 1.35.0.
  • You will use the genesyscloud_user resource to create and manage users with the new nested attribute structure for routing profiles and division associations.
  • The tutorial covers Python-based validation scripts and Terraform HCL implementation.

Prerequisites

  • Terraform: Version 1.5.0 or later.
  • Genesys Cloud CX as Code Provider: Version 1.35.0 or later (hashicorp/genesyscloud is not the correct source; use mygenesys/genesyscloud).
  • Python 3.9+: For validation scripts using httpx.
  • OAuth Credentials: A Genesys Cloud OAuth client with the following scopes:
    • user:read
    • user:write
    • routing:profile:read
    • routing:profile:write
  • Network Access: The execution environment must have outbound HTTPS access to api.mypurecloud.com (or your regional endpoint).

Authentication Setup

The Genesys Cloud provider handles authentication internally via environment variables or the credentials block. However, when writing validation scripts in Python, you must implement the OAuth2 Client Credentials flow.

Python OAuth Implementation

This script retrieves a valid access token. You will use this token to verify that your Terraform changes align with the actual API state.

import httpx
import os
import json
from typing import Optional

class GenesysAuth:
    """Handles OAuth2 Client Credentials flow for Genesys Cloud."""
    
    def __init__(self, client_id: str, client_secret: str, region: str = "us"):
        self.client_id = client_id
        self.client_secret = client_secret
        self.region = region
        self.base_url = f"https://api.{region}.mypurecloud.com"
        
    def get_token(self) -> Optional[str]:
        """
        Retrieves an OAuth2 access token.
        Returns None if authentication fails.
        """
        url = f"{self.base_url}/oauth/token"
        headers = {
            "Content-Type": "application/x-www-form-urlencoded"
        }
        data = {
            "grant_type": "client_credentials",
            "client_id": self.client_id,
            "client_secret": self.client_secret
        }
        
        try:
            with httpx.Client() as client:
                response = client.post(url, headers=headers, data=data)
                response.raise_for_status()
                token_data = response.json()
                return token_data.get("access_token")
        except httpx.HTTPStatusError as e:
            print(f"Authentication failed with status {e.response.status_code}")
            print(f"Response body: {e.response.text}")
            return None
        except Exception as e:
            print(f"An error occurred during authentication: {e}")
            return None

# Usage Example
if __name__ == "__main__":
    CLIENT_ID = os.getenv("GENESYS_CLIENT_ID")
    CLIENT_SECRET = os.getenv("GENESYS_CLIENT_SECRET")
    
    if not CLIENT_ID or not CLIENT_SECRET:
        raise ValueError("GENESYS_CLIENT_ID and GENESYS_CLIENT_SECRET environment variables are required.")
        
    auth = GenesysAuth(CLIENT_ID, CLIENT_SECRET)
    token = auth.get_token()
    
    if token:
        print("Authentication successful. Token obtained.")
        # Save token for use in subsequent API calls
        with open("token.txt", "w") as f:
            f.write(token)
    else:
        print("Failed to obtain token.")

Implementation

Step 1: Identify the Breaking Change

In provider version 1.35.0, the genesyscloud_user resource schema was refactored to align more closely with the underlying REST API structure. The primary breaking change affects how Routing Profiles and Divisions are assigned.

Previous versions allowed flat attribute assignment for some routing properties. The new version requires explicit nesting for routing_profile_id within a routing block or specific division-based scoping. If you attempt to apply old configurations, Terraform will return a Error: Unsupported argument or Error: Invalid attribute name message.

Old Schema (Pre-1.35.0):

resource "genesyscloud_user" "example" {
  name            = "Test User"
  email           = "test@example.com"
  routing_profile_id = "abc-123" # Flat attribute
  division_id       = "xyz-789"  # Flat attribute
}

New Schema (v1.35.0+):

resource "genesyscloud_user" "example" {
  name   = "Test User"
  email  = "test@example.com"
  
  # Routing configuration is now nested or strictly typed
  routing_profile_id = "abc-123" # Still exists but validation is stricter
  
  # Division association may require explicit block depending on user type
  division_id = "xyz-789"
}

While the top-level attributes remain, the provider now enforces that the routing_profile_id must exist in the target division. The breaking change often manifests when the provider attempts to resolve the division context for the user. In v1.35.0, if you do not specify a division_id for a user in a multi-division environment, the provider defaults to the global division, which may cause a 400 Bad Request if the routing profile is not global.

Step 2: Update Terraform Configuration

You must update your genesyscloud_user resources to explicitly define the division_id if the user is not in the default division. Additionally, ensure that the routing_profile_id referenced belongs to the same division as the user, or is a global profile.

Create a file named main.tf with the following content. This example demonstrates the correct schema usage for v1.35.0.

terraform {
  required_providers {
    genesyscloud = {
      source  = "mygenesys/genesyscloud"
      version = ">= 1.35.0"
    }
  }
}

provider "genesyscloud" {
  # Credentials are loaded from environment variables:
  # GENESYS_CLIENT_ID, GENESYS_CLIENT_SECRET, GENESYS_REGION
}

# Data source to fetch the routing profile ID by name
# This ensures we are using a valid ID before creating the user
data "genesyscloud_routing_profile" "standard_agent" {
  name = "Standard Agent"
}

# Data source to fetch the division ID if using a specific division
# Replace 'My Division' with your actual division name
data "genesyscloud_user_division" "sales_division" {
  name = "Sales Division"
}

resource "genesyscloud_user" "new_agent" {
  name          = "John Doe"
  email         = "john.doe@example.com"
  username      = "john.doe"
  password      = "SecurePassword123!" # Note: This is plaintext in state; use sensitive = true
  
  # Explicitly set the division ID
  division_id   = data.genesyscloud_user_division.sales_division.id
  
  # Reference the routing profile ID
  # The provider will now validate that this profile exists in the target division
  routing_profile_id = data.genesyscloud_routing_profile.standard_agent.id
  
  # Optional: Assign a language
  languages {
    language_id = "en-US"
    preference_order = 1
  }
  
  # Optional: Assign skills
  skills {
    skill_id = "your-skill-id-here" # Replace with actual skill ID
  }
  
  # Lifecycle block to prevent accidental deletion
  lifecycle {
    ignore_changes = [password]
  }
}

Key Changes Explained:

  1. Explicit Division ID: The division_id attribute is now critical for multi-division tenants. The provider no longer guesses the division context as aggressively as previous versions.
  2. Routing Profile Validation: The provider performs a pre-flight check to ensure routing_profile_id is compatible with division_id. If they mismatch, the apply fails with a clear error.
  3. Language Block: The languages attribute is now a nested block list. Each language requires a language_id and preference_order.

Step 3: Validate with Python

Before applying the Terraform changes, you can validate that the routing profile and division exist and are compatible using Python. This script checks the API directly to ensure your Terraform data sources will resolve correctly.

import httpx
import json
import sys

def validate_user_prerequisites(token: str, region: str, division_id: str, routing_profile_id: str):
    """
    Validates that a routing profile exists and is accessible in the specified division.
    """
    base_url = f"https://api.{region}.mypurecloud.com"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }

    # 1. Check Division
    div_url = f"{base_url}/api/v2/users/divisions/{division_id}"
    try:
        with httpx.Client() as client:
            div_response = client.get(div_url, headers=headers)
            div_response.raise_for_status()
            division_data = div_response.json()
            print(f"Division Found: {division_data.get('name')} (ID: {division_id})")
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            print(f"Error: Division {division_id} not found.")
            sys.exit(1)
        else:
            print(f"Error fetching division: {e.response.status_code} - {e.response.text}")
            sys.exit(1)

    # 2. Check Routing Profile
    # Note: Routing profiles are global or divisional. We check if the profile exists.
    rp_url = f"{base_url}/api/v2/routing/profiles/{routing_profile_id}"
    try:
        with httpx.Client() as client:
            rp_response = client.get(rp_url, headers=headers)
            rp_response.raise_for_status()
            profile_data = rp_response.json()
            print(f"Routing Profile Found: {profile_data.get('name')} (ID: {routing_profile_id})")
            
            # Check if the profile is global or divisional
            profile_div_id = profile_data.get("divisionId")
            if profile_div_id and profile_div_id != division_id:
                print(f"Warning: Routing Profile is in division {profile_div_id}, but User is in {division_id}.")
                print("This may cause a validation error in Terraform v1.35.0+ unless the profile is global.")
            else:
                print("Routing Profile division matches User division (or profile is global).")
                
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            print(f"Error: Routing Profile {routing_profile_id} not found.")
            sys.exit(1)
        else:
            print(f"Error fetching routing profile: {e.response.status_code} - {e.response.text}")
            sys.exit(1)

if __name__ == "__main__":
    # Load token from file generated in Authentication Setup
    try:
        with open("token.txt", "r") as f:
            token = f.read().strip()
    except FileNotFoundError:
        print("Error: token.txt not found. Run the authentication script first.")
        sys.exit(1)

    # Replace these with actual IDs from your Genesys Cloud instance
    REGION = "us"
    DIVISION_ID = "your-division-id-here"
    ROUTING_PROFILE_ID = "your-routing-profile-id-here"

    if DIVISION_ID == "your-division-id-here" or ROUTING_PROFILE_ID == "your-routing-profile-id-here":
        print("Please update DIVISION_ID and ROUTING_PROFILE_ID in the script.")
        sys.exit(1)

    validate_user_prerequisites(token, REGION, DIVISION_ID, ROUTING_PROFILE_ID)

Complete Working Example

The following is a complete Terraform configuration file that creates a user with the v1.35.0 schema. It includes error handling for common misconfigurations.

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

provider "genesyscloud" {
  # Ensure these environment variables are set:
  # export GENESYS_CLIENT_ID="your-client-id"
  # export GENESYS_CLIENT_SECRET="your-client-secret"
  # export GENESYS_REGION="us"
}

# Fetch the default division if you want to use the global scope
data "genesyscloud_user_division" "default" {
  name = "Default"
}

# Fetch a specific routing profile
data "genesyscloud_routing_profile" "agent_profile" {
  name = "Standard Agent"
}

resource "genesyscloud_user" "migration_test_user" {
  name          = "Migration Test User"
  email         = "migration.test@example.com"
  username      = "migration.test"
  password      = "TempPassword123!"
  
  # Explicitly assign the division
  division_id   = data.genesyscloud_user_division.default.id
  
  # Assign the routing profile
  routing_profile_id = data.genesyscloud_routing_profile.agent_profile.id
  
  # Set languages
  languages {
    language_id = "en-US"
    preference_order = 1
  }

  # Add a note for auditing
  description = "Created via Terraform v1.35.0 migration"
  
  # Prevent state drift on password
  lifecycle {
    ignore_changes = [password]
  }
}

output "user_id" {
  value       = genesyscloud_user.migration_test_user.id
  description = "The ID of the created user"
}

output "user_email" {
  value       = genesyscloud_user.migration_test_user.email
  description = "The email of the created user"
}

To run this example:

  1. Save the code to main.tf.
  2. Set the environment variables for your OAuth client.
  3. Run terraform init.
  4. Run terraform plan to verify the configuration.
  5. Run terraform apply to create the user.

Common Errors & Debugging

Error: Unsupported argument routing_profile_id in routing block

Cause: In some transitional updates, users attempt to nest routing_profile_id inside a routing block, which is not supported in v1.35.0 for the genesyscloud_user resource.

Fix: Ensure routing_profile_id is a top-level attribute of the genesyscloud_user resource.

# INCORRECT
resource "genesyscloud_user" "bad_example" {
  routing {
    profile_id = "abc-123"
  }
}

# CORRECT
resource "genesyscloud_user" "good_example" {
  routing_profile_id = "abc-123"
}

Error: Invalid value for division_id

Cause: The provided division_id does not exist in the Genesys Cloud instance, or the OAuth client lacks permissions to read that division.

Fix: Verify the division ID using the Python validation script. Ensure the OAuth client has the user:read scope and access to the specific division.

Error: Routing profile not found in division

Cause: The routing_profile_id belongs to a different division than the user’s division_id, and the profile is not global.

Fix: Either move the user to the division where the profile exists, or change the user’s routing profile to one that exists in the target division. You can check this by inspecting the divisionId field of the routing profile in the Genesys Cloud Admin UI or via the API.

Error: 409 Conflict

Cause: A user with the same username or email already exists in the target division.

Fix: Check for existing users with the same identifiers. Terraform will attempt to import the existing resource if you use terraform import, but you must ensure the state file matches the current configuration.

Official References