Genesys Cloud - Developer Community!

Hi Team,

We are trying to maintain Script resources through Terraform automation, we are facing some design challenges, can you please guide us, how to implement same?

• Different formats:
  • While making changes on UI it accepts ".script" format and UI export also returns same format
  • Terraform accepts .json format and Terraform export also exports .json format
    • How can we export script file from UI and use in terraform
• Use of ID in the exports
  • Considering portability of script to different environments, how we can automate TF file to use generic configuration without ID;s and same can be used in all places just by using substitution variable?

Can you please guide us how to implement scripts in the deployment cycles?

Regards,

Rohit S 

Hi Rohit, 

You can export the file from the UI and save it as .json and reference the file in your terraform resource as per the below from the documentation.

resource "genesyscloud_script" "example_script" {
  script_name       = "Example script name ${random_uuid.uuid.result}"
  filepath          = "${local.working_dir.script}/email.script.json"
  file_content_hash = filesha256("${local.working_dir.script}/email.script.json")
  substitutions = {
    /* Inside the script file, "{{foo}}" will be replaced with "bar" */
    foo = "bar"
  }
}

Olá Rohit! Você está no caminho certo. Eis como costumo estruturar scripts do Genesys Cloud com Terraform para manter portabilidade e automação:

1) Formatos: .script (UI) vs .json (Terraform)

• O export da UI entrega um arquivo com extensão .script, mas o conteúdo é JSON puro.

• Para usar no Terraform, basta salvar o mesmo conteúdo como .json (por exemplo, renomear para meu_script.script.json).

• Dica: garanta que o arquivo esteja em UTF-8 sem BOM.

2) Usando o arquivo exportado no recurso genesyscloud_script

Exemplo funcional (similar ao que já foi mencionado):

resource "genesyscloud_script" "example_script" {
  script_name       = "Script Exemplo ${random_uuid.uuid.result}"
  filepath          = "${path.module}/scripts/meu_script.script.json"
  file_content_hash = filesha256("${path.module}/scripts/meu_script.script.json")
 
  # Substituições: placeholders no JSON do script do tipo {{chave}}
  substitutions = {
    # Dentro do JSON, algo como "queueId": "{{queue_id_sales}}"
    # será substituído pelo valor abaixo em tempo de apply
    queue_id_sales = data.genesyscloud_routing_queue.sales.id
    division_id    = data.genesyscloud_auth_division.this.id
    # etc...
  }
}
 
data "genesyscloud_routing_queue" "sales" {
  name = var.sales_queue_name   # evita ID fixo; resolve por nome
}
 
data "genesyscloud_auth_division" "this" {
  name = var.division_name
}
 
resource "random_uuid" "uuid" {}

Pontos importantes:

• filepath aponta para o arquivo JSON do script.

• file_content_hash com filesha256(...) garante que mudanças no arquivo acionem atualização.

• substitutions injeta valores nos placeholders do arquivo (ex.: {{queue_id_sales}}).

3) Tornando o script "genérico" sem IDs fixos

O segredo é trocar IDs por placeholders no arquivo exportado da UI. Exemplos práticos:

No JSON do script (arquivo):

{
  "someControl": {
    "queueId": "{{queue_id_sales}}",
    "divisionId": "{{division_id}}",
    "flowName": "{{flow_name}}"
  }
}

No Terraform:

substitutions = {
  queue_id_sales = data.genesyscloud_routing_queue.sales.id     # resolve por nome
  division_id    = data.genesyscloud_auth_division.this.id
  flow_name      = var.flow_name                                 # variável por ambiente
}

Assim você evita IDs "hard-coded" e mantém portabilidade: em cada ambiente, muda apenas *.tfvars com os nomes dos recursos e o Terraform resolve os IDs dinamicamente via data sources.

4) "Como exportar da UI e usar no Terraform"

Passo a passo objetivo:

1. Na UI, exporte o script (extensão .script).

2. Renomeie para algo como meu_script.script.json.

3. Abra o arquivo e substitua IDs fixos por placeholders {{...}} onde for necessário (queueId, divisionId, datatableId, etc.).

4. Referencie esse arquivo no recurso genesyscloud_script e preencha os placeholders via substitutions, usando:

   • data "genesyscloud_*" para resolver IDs por nome, ou

   • variáveis var.* para valores específicos por ambiente.

5) Uso de ID nos exports

• Exports da UI trazem vários IDs. Troque por {{placeholders}} e resolva no Terraform com:

  • data "genesyscloud_routing_queue" por nome de fila

  • data "genesyscloud_auth_division" por nome de divisão

  • data "genesyscloud_*" equivalentes para outros recursos

• Se algum recurso não existe no ambiente de destino, crie-o com Terraform e depois referencie resource.*.id na substitution.

6) Portabilidade entre ambientes

• Mantenha um módulo de script e diferentes *.tfvars:

  • dev.tfvars, staging.tfvars, prod.tfvars

  • Cada um define division_name, sales_queue_name, flow_name etc.

• No CI/CD, rode:

  • terraform plan -var-file=dev.tfvars

  • terraform apply -var-file=dev.tfvars

  • Repita para staging/prod.

• Isso permite o mesmo template de script servir a todos os ambientes.

7) Deployment cycle recomendado

1. Fonte única do JSON do script em repositório (padrão *.script.json).

2. PR revisa mudanças no JSON e placeholders.

3. Pipeline executa terraform plan e apply com o -var-file correto.

4. file_content_hash assegura atualização quando o conteúdo muda.

5. Monitorar drift (se alguém editar o script na UI, o plan acusará divergência).

8) E se já existe um script em produção?

• Use terraform import genesyscloud_script.<nome> <script_id> para trazer ao estado do Terraform.

• Em seguida, alinhe o arquivo e as substituições até o plan ficar limpo.

Thank you @Fernando Sotto dos Santos for detailed information. Appreciate your response.

resource "genesyscloud_script" "example_script" {
  script_name       = "Script Exemplo ${random_uuid.uuid.result}"
  filepath          = "${path.module}/scripts/meu_script.script.json"
  file_content_hash = filesha256("${path.module}/scripts/meu_script.script.json")
 
  # Substituições: placeholders no JSON do script do tipo {{chave}}
  substitutions = {
    # Dentro do JSON, algo como "queueId": "{{queue_id_sales}}"
    # será substituído pelo valor abaixo em tempo de apply
    queue_id_sales = data.genesyscloud_routing_queue.sales.id
    division_id    = data.genesyscloud_auth_division.this.id
    # etc...
  }
}
 
data "genesyscloud_routing_queue" "sales" {
  name = var.sales_queue_name   # evita ID fixo; resolve por nome
}
 
data "genesyscloud_auth_division" "this" {
  name = var.division_name
}
 
resource "random_uuid" "uuid" {}

{
  "someControl": {
    "queueId": "{{queue_id_sales}}",
    "divisionId": "{{division_id}}",
    "flowName": "{{flow_name}}"
  }
}

substitutions = {
  queue_id_sales = data.genesyscloud_routing_queue.sales.id     # resolve por nome
  division_id    = data.genesyscloud_auth_division.this.id
  flow_name      = var.flow_name                                 # variável por ambiente
}