Handbook
Genesys Cloud configuration as code: CX as Code, Archy and environments
A detailed handbook for the people who own Genesys Cloud configuration across environments. It covers CX as Code and Terraform state, export and adopting an existing organisation, Archy flows, substitutions and schemas, the provider's flow resource, tracking IDs and flow validation, environment strategy, naming, state and repositories, secrets, velocity, pipelines, drift, testing, rate limits and functions. Checked against Genesys sources on 16 November 2026.
In short
- Configuration as code makes configuration reviewable and rebuildable; it is not a backup of interaction data.
- Terraform creates on first apply and reverts console edits to objects it owns, so seed state and stop console changes.
- Archy substitutions are text replacement, references do not nest, and schemas are only valid for the organisation refreshed.
- Use one organisation per environment; divisions separate access, not runtime, and a published flow is live at once.
- Keep state per environment, secrets in the CI store, fast-changing items like membership out of code, and move forward.
01
What configuration as code fixes, and when not to do it
This handbook is for the people who own Genesys Cloud configuration across more than one environment: platform owners, solution architects, flow authors, DevOps engineers and the security teams who review them. Every statement about Genesys Cloud and its tools comes from Genesys's documentation, its Developer Center and the provider's published documentation, listed in the sources and checked on 16 November 2026. Where something is our own practice, it is labelled QVCCS practice.
1.1 Reviewable configuration with readable history
Most teams say they want CX as Code for consistency between environments. That is a benefit, but not the main one. The change that alters how a programme runs is narrower: configuration becomes reviewable, and its history becomes readable. Genesys's 2026 functions blog lists four benefits: version control in Git, repeatability across development, staging and production, peer review through pull requests, and disaster recovery by re-running Terraform.
Peer review ends a familiar kind of incident. A queue's skills change late on a Thursday and calls start reaching the wrong team. In a console-managed estate, finding out who did it means asking around; in a code-managed estate it is a commit, an author, a diff and an approval. Repeatability pays back fastest where one design serves several brands, subsidiaries or tenants.
1.2 Rebuild is not backup
Disaster recovery needs care in how it is described. Terraform rebuilds configuration: queues, flows, skills, schedules and data actions. It does not hold calls, messages, recordings, transcripts or analytics, and never will. Genesys's FAQ also notes that the provider itself creates no audit trail; source control provides it, and keeping Terraform's plan output is your responsibility.
1.3 When not to do it
Genesys is unusually direct about when CX as Code is the wrong choice. Its guidance says it is a set of lower-level primitives for a CI/CD pipeline, not a packaged, no-code solution, and that without the staff and time to learn it, it will end in frustration. It says teams that have not begun adopting DevOps should hold off, and that a small or medium company with only one Genesys Cloud organisation may not need it. Its positive advice is to start small, with one Architect flow and one piece of infrastructure, and to understand how a change is deployed and reversed before going further.
- How many environments? One suggests no; two is marginal; three or more suggests yes.
- Do several brands, regions or tenants share a design? If so, the case is strong.
- Is there an existing Git and CI practice, with someone who will own this? If not, build that capability first.
- Can a named engineer review and operate the pipeline after the build team leaves? If not, do not build it yet.
02
Three tools, three jobs
Genesys provides three automation tools for contact centre configuration, and they are often confused. Sorting them out early prevents most mis-scoped projects.
2.1 What each tool is
| Tool | What Genesys says it is | What it manages |
|---|---|---|
| CX as Code | A tool to declaratively manage Genesys Cloud resources and configuration across organisations using Terraform | Genesys Cloud objects such as queues, skills, schedules, integrations, data actions, prompts and flows |
| Archy | An Architect YAML processor that creates flows from YAML files and checks them in, out, publishes or updates them | Architect flows only |
| Platform API CLI | A standalone CLI for the Genesys Cloud API on macOS, Linux and Windows | Anything the API exposes, one call at a time |
- A queue is a small, flat object that Terraform handles well. An IVR flow is a graph of actions, menus, tasks and expressions, for which YAML plus a purpose-built processor is a better fit.
- Genesys's low-code guide names Archy and CX as Code as the two tools for moving flows between organisations, and its published blueprints combine them to deploy queues, data actions and flows together.
- Genesys's FAQ says that although CX as Code can do one-time bulk operations, a script against the API, or the CLI, is often more effective.
03
How Terraform sees a Genesys Cloud organisation
Three Terraform ideas remove most of the mystery around CX as Code, and one of them causes most of the disasters: state.
3.1 Resources and data sources
Resources are the objects you declare. Genesys points to the provider registry for each resource's schema, and the registry's resource list is the boundary of what can be managed: version 1.88.0, published on 4 November 2026, lists 160 resources and 121 data sources. If an object has no resource type, Terraform cannot own it.
Data sources read without owning. Genesys describes them as a way to reference existing resources you do not want Terraform to manage, including objects defined outside Terraform or in another configuration. A queue that stays under a business team's control in the console can still be referenced by a Terraform-managed flow or schedule.
3.2 State and ownership
State is Terraform's record of which real object corresponds to which block of configuration. Plans compare configuration with state, not with the live organisation. Genesys's best practice spells out the consequence: Terraform expects to be the sole maintainer of the objects it owns, so if you change a Terraform-managed object in the console, the next run reverts it. Its example is routing rules added to a Terraform-managed queue through the console and silently undone at the next deployment.
Losing state does not delete Genesys objects, but Terraform no longer knows what it created, and its first instinct is to create everything again. Parts 9 and 12 cover hosting state and preventing drift.
3.3 Connecting, support and licensing
- The provider needs an OAuth client with a client credentials grant, and Terraform later than 0.13.
- Credentials can come from environment variables such as GENESYSCLOUD_OAUTHCLIENT_ID, GENESYSCLOUD_OAUTHCLIENT_SECRET and GENESYSCLOUD_REGION.
- Every object Terraform creates is attributed to the integration, not a person, so the audit viewer shows the same principal for every change; the person is in the Git commit.
- Genesys's FAQ says CX as Code has no additional cost, is open source under an MIT-style licence and is supported as is, with defects raised on the Developer Forum.
- Problems Genesys judges to be in the Terraform CLI are referred to HashiCorp's community. Genesys also says it tests the provider with OpenTofu and supports both.
- The provider can be configured with an outbound proxy, a token pool of one to 50 tokens, and retry timeouts; Genesys's FAQ says it retries with backoff when rate limited.
04
Export, and adopting an organisation that already exists
Export is the feature everyone asks for first and the one most often misunderstood. It does not do the two things people usually want from it.
4.1 The export resource
Genesys provides a special resource, genesyscloud_tf_export, which exports existing resources into a configuration file. You run an apply to produce an export. The provider documentation sets out its options:
- export_format chooses HCL, JSON or both, and defaults to JSON. The older export_as_hcl attribute is deprecated.
- include_filter_resources and exclude_filter_resources select resource types, or types matching a pattern, and include_filter_resources_by_id selects individual objects. The older resource_types attribute is deprecated.
- include_state_file writes a state file alongside the configuration, which the documentation says can be used for organisations to begin managing existing resources with Terraform.
- replace_with_datasource turns matching resources into data sources, and enable_dependency_resolution exports the objects that flows and scripts depend on.
- split_files_by_resource writes a file per resource type, and log_permission_errors logs missing permissions instead of failing.
4.2 Export omits secrets
Genesys states that some values are never exported, including credentials used by integrations and data actions. Instead, the export injects a Terraform variable for each and generates a variables file with empty values, so sensitive values can be managed in one place or in a secrets vault. An exported configuration is therefore safe to commit and will not run until someone supplies those credentials.
4.3 The rule that breaks most first attempts
Genesys's FAQ says exports from one organisation can be applied to another, but that this is not the primary use case. Terraform always tries to create resources on the first apply; it will not create or update, so resources with the same name already in the target organisation cause the run to fail. It therefore works best when the target is a new organisation.
So copying production to test fails if test already contains anything, and in any case copies definitions only, with no data, users or credentials. Genesys also says there is no comparison support between organisations, and that exports from different organisations vary in order and naming, so a raw text comparison is likely to be wrong.
4.4 Bringing an existing organisation under management
For an organisation that already exists, the answer is to record existing objects in state rather than create them. The export's include_state_file option is documented for this purpose, and Terraform's own import mechanism does the same for individual objects. Genesys publishes no step-by-step adoption procedure for production, so the sequence below is our own practice built on those mechanisms; check current syntax in the provider documentation first.
- Choose object types, not the whole organisation, starting with low-risk ones such as skills, wrap-up codes and schedules.
- Export that narrow selection with its state, then reduce it by hand into reviewed configuration.
- Confirm that a plan shows no changes. An empty plan proves the configuration and the live objects agree, and it is the acceptance test for this step.
- Only then make a real change, and let an incremental plan show it does what you expect.
- Restrict console editing of those object types the same day (part 12).
05
Archy: flows as text, composition and substitutions
Archy solves a problem Architect's interface cannot: the objects a flow depends on have different identities in every organisation, so a flow is not portable on its own.
5.1 Why flows need it
Genesys explains that Archy covers cases where building a flow in the interface is awkward and time consuming. Its example: move a flow between test and production organisations and you lose all mappings to queues, data actions and more, which you must remap by hand; with Archy you define the flow and update those mappings procedurally. Architect's import article adds that importing a flow from another organisation may need configuration updates, even for data actions with similar names, and returns validation errors until they are fixed.
On a five-action flow, remapping is an afternoon. On forty flows, a shared library and four environments, it is a tax on every release and a reliable source of a flow that works in test and misroutes in production.
5.2 Export, edit, import
Since May 2021, flows can be exported from Architect in YAML, edited in a text editor and imported again with Archy. You do not have to write flows in YAML from scratch to benefit: export a flow someone built visually and you have a reviewable text version with a history.
Archy runs on Linux, macOS and Windows, built on the Platform SDK and the Architect Scripting SDK, and Genesys notes that although it can be run by hand, it is intended for automated environments. That explains its options files, schema output and lack of a wizard.
5.3 References, and the one thing you cannot do
Archy's references let a flow embed objects from other YAML files, which Genesys recommends for logic shared between flows. That turns a pile of flows into a library: shared tasks such as identity capture, language selection and error handling, fixed once and promoted everywhere.
Genesys's Archy FAQ sets the limit: embedding an external reference from within a common file, with ref or refArray, is not allowed, including references within the same common file. References do not nest. A flow can pull in a common file, but that file cannot pull in another, so the shared library must be flat. Genesys also notes that substitutions are applied after referenced objects have been embedded, so a shared file can use substitution keys exactly as a flow does.
5.4 Substitutions are text replacement
A substitution is a key and value pair supplied in an options file. Keys must be at least one character with no leading or trailing spaces, and values must be a string, number or Boolean. Genesys's example replaces a greeting, an organisation name and a queue name, and tells authors to quote the whole string wherever a substitution appears.
Genesys also explains that the preprocessor uses a text replacement algorithm, which is why substitutions should replace values, not chunks of YAML, and it does not recommend using them to embed actions or tasks; references are the mechanism for that. Its example queue substitution comes with the assumption that the named queue exists in the organisation, so a renamed queue breaks the flow.
- Substitutions go in values, never structure.
- Quote every substituted value, so a value that begins with a special character cannot change how the YAML is parsed.
- Every key must exist in every environment's file; a missing key can put a literal placeholder into a production prompt.
- Name keys for the concept, such as support_queue_name, never for the current value, and prefix them by type so a key cannot collide with words in a text-to-speech prompt.
06
Running Archy: commands, options files and schemas
Archy's command set is small, its options files carry the environment strategy, and its schemas carry a consequence that surprises almost everyone.
6.1 Commands and options files
The commands used routinely include create, publish, checkin, checkout, export, refresh, validate, validateYaml, configure, setup, dump and version. Genesys documents that if a flow with the same name exists, you can use the recreate option to overwrite it, or rename the flow in the YAML. Since October 2026, publish also has a debugPublish option that debug-publishes a flow without changing its published version.
Genesys encourages options files for supplying values per organisation and per environment. Its description of its own pipelines is a sensible pattern: an options file holds the client ID, secret and location, while the flow file, which changes every run, is passed on the command line. Archy prints each resolved parameter with where it came from, which is the best record of which organisation a flow was actually published to. You do not need to run setup in a pipeline.
6.2 Operational notes from Genesys
- Several Archy instances running at once can collide over folders in the Archy home directory, such as the debug folder, and can fail writing the same file; use one runner per home directory.
- Executable permissions can be lost when the download is unzipped, so restore them in the install step.
- Debug mode increases processing time, and the debug log is written on error anyway, so leave it off in normal runs.
- If a flow file name contains a space, quote the path. We avoid spaces in file names altogether.
- archy version lists installed versions and switches between them, and Genesys advises running refresh after changing major or minor version.
6.3 Schemas describe your organisation
Archy's refresh command generates JSON schemas not only for flow objects but for the queues, groups, wrap-up codes, data actions and other objects configured in your organisation at that moment. Genesys says they are generated per instance and must be regenerated as the organisation changes, and that refresh can take a couple of minutes; its parallel option limits concurrent flow schema generation to five to reduce memory use.
Then the sharp part. Genesys's FAQ says that, as in Architect, what you can do in Archy depends on the organisation: if an organisation lacks inbound message flows, the schemas will not describe them, and the same applies to actions and data types. This is by design, so schemas do not call something valid where it is not. A flow that validates in development can therefore be invalid in production if production lacks the flow type, action or entitlement. Genesys's beta guidance, to use beta features in development or test, makes the point sharper.
6.4 What Archy cannot do
Genesys's Archy FAQ says the only Architect feature not available in Archy is builder support, such as the Audio Sequence Editor and String Builder. Architect's export article says sequence builders are rendered as equivalent expressions on export, which work as expected but no longer appear as builders. Round-tripping a flow through YAML does not preserve that authoring experience.
The same FAQ says neither Archy nor Architect Scripting supports proxy configuration. For an enterprise whose build agents must use an authenticating proxy, that can rule out Archy in the pipeline. The Terraform provider, by contrast, documents proxy settings, so its flow resource (part 7) may be the route for those estates; that is our reading, to be tested in the client's network.
07
Flows in Terraform, native export, tracking IDs and validation
Flows can now be promoted three ways, two 2026 changes make exported flows far more useful, and published flows can be re-validated.
7.1 The provider's flow resource
A 2022 Genesys blog described a CX as Code flow resource that could deploy an Architect flow without the CLI installed, then in closed beta. The provider's current documentation describes genesyscloud_flow with no beta notice. It takes a YAML file path, which can be in S3, a substitutions map that replaces the Archy options file, an optional force unlock that mirrors Archy's behaviour, an option to create stub flows for dependencies that do not yet exist, and a hash of the file content to detect changes. The documentation warns that changing a flow's name creates a new flow, and the original remains in the organisation.
7.2 Native export and import
Without any toolchain, Architect exports a flow in its own format or YAML, optionally with tracking ID details, and imports a file after analysing what it contains. The cost is the remapping and validation errors described in part 5. And publishing is immediate: Genesys says that when you update and publish a flow, Architect saves the changes and puts them into effect straight away. Within one organisation there is no staging; a published change is live traffic.
| Method | What it costs | What you get | Suits |
|---|---|---|---|
| Architect export and import | Manual remapping per flow, per environment | Nothing reusable | One-off moves |
| Archy | YAML skills and options file discipline | Text flows, substitutions and scripted remapping | Flow promotion across environments |
| CX as Code | Terraform, state and a pipeline | Whole-estate consistency, review and rebuild | Several environments or brands |
7.3 Tracking IDs survive a move
Since July 2026, administrators can include tracking IDs when they export and import flows in YAML, which Genesys says keeps identifiers for actions, tasks, menus and states consistent across organisations and environments. Without stable IDs, every identifier differs between environments, so a YAML comparison shows every line as changed and is useless for review.
7.4 Validating published flows
Architect validates when you author and publish, marking red errors that stop a flow working and yellow suggestions that do not. Since October 2026, Genesys's Architect flow validator lets administrators find published flows that have become invalid because of platform or dependency changes, using the Archy CLI or Archy CX as Code, before they cause failures at run time. Previously nothing re-checked a published flow when a data action, prompt or other dependency changed underneath it.
Archy's validate and validateYaml commands are the documented route. We found no separate validation resource in provider version 1.88.0, so confirm how the CX as Code route works before relying on it.
08
Environment strategy: organisations, purposes and divisions
This is the part most guides skip and most programmes need, because the rest of the design follows from it.
8.1 One organisation per environment
Genesys's model is one organisation per environment. The evidence is consistent: the FAQ's advice that exports work best into a new organisation, its best practice about promoting through development, test and production with no manual steps, and blueprints that use an environment name as an affix on resource names. Each organisation has its own OAuth clients, limits and licences.
A separate organisation gives four things no partition within one organisation can: publication that affects only that environment, its own limits and licence tier, its own data, and the freedom to fail. Because publishing a flow takes effect immediately across the whole organisation, the first is the decisive one: you need somewhere a mistake cannot reach a customer.
8.2 What each environment is for
| Environment | Built by | Purpose | Who may change it | Data |
|---|---|---|---|---|
| Development | Pipeline, on merge | Authoring, integration and early flow testing | Flow authors and engineers | Synthetic |
| Test | Pipeline, on merge to the release branch | Business sign-off, acceptance, training and performance tests | Only the pipeline | Synthetic, at realistic volume |
| Production | Pipeline, after human approval | Live traffic | Only the pipeline, or break-glass | Real customer data |
| Sandbox (optional) | By hand or pipeline | Demonstrations, partner builds and experiments | Broad | Never real |
- Development is the only place a broken flow is normal, and where schemas are refreshed for editors, so entitle it like production.
- Test receives only what will go to production: the same artefacts, the same pipeline and different variables. Sign-off in a hand-tuned environment approves something you are not about to deploy.
- Genesys ships changes continuously, so keep test aligned with production all the time, not at milestones, and run regression after notable releases.
- Never copy production contacts into test to make it realistic; that is a personal data incident.
8.3 Divisions are not environments
A division partitions access and visibility within one organisation. It controls who can see and change which objects; it does not create an isolated runtime. There is one set of published flows, queues and schedules per organisation, so a flow published in a test division is live in production. Divisions suit brands, regions or outsourced partners that one organisation must hold safely apart, as our roles, permissions and divisions handbook explains.
The two combine well: three organisations for the delivery lifecycle, with the same divisions inside each for brand or region separation, so division names carry through substitutions unchanged.
09
Naming, state and repository layout
Names decide whether substitutions move cleanly between environments, state decides whether a mistake stays in one environment, and the repository layout decides whether the estate stays understandable.
9.1 Naming
Where possible, give objects identical names in every environment. Organisations are independent, so there is no collision, and matching names make substitutions, logs and comparisons easy to read across environments. Where names must differ, put the difference in one variable, as Genesys's blueprints do with an environment name affix on generated resources.
Both Terraform and Archy rely on names, and Genesys's substitution example assumes the named queue exists. Rename a queue in one environment only and the flow points at nothing. Naming is therefore a data integrity control, and a rename is a change across every environment, planned and proved by the pipeline.
9.2 State: shared, separate and protected
- Keep state on a shared remote backend with locking, never on a laptop. Two applies against the same state at once corrupt it.
- Keep one state per environment. Genesys recommends breaking a contact centre into major areas of functionality with separate repositories and backing states; with separate state, a plan against test cannot see production and a destroy in development cannot reach it.
- Choose the backend by directory, not by a variable, because a mistyped variable pointing production at test's state is a far worse accident than a wrong directory.
- Protect state as sensitive: it holds the attributes of every managed object, and an export can include a state file, so it is easy to leave one in a repository or build artefact.
- Genesys warns that a single flow can have dozens of dependencies, so even flow-aligned projects grow. Split by functional area first and environment second.
9.3 Repository and modules
The shape that works is modules that define, environments that configure and pipelines that execute. Each module takes a typed input, iterates over a map keyed by name, and outputs a map of IDs for other modules to use: queues produce queue IDs, skills produce skill IDs, and flow or membership modules consume them. Each environment directory holds its backend, provider settings, module calls and variable values, alongside its substitution file.
Genesys names the common mistake: managing the whole contact centre in one Terraform project, in one repository, with one state. It suggests using Architect flows to find natural divisions in the contact centre, because a flow and its dependencies tend to change together. Genesys also publishes reusable remote modules, for example for EventBridge, Lambda with data actions, and data actions that wrap Genesys Cloud APIs.
10
Secrets and access
A configuration-as-code estate concentrates privilege, so this is a security part as much as a DevOps one.
10.1 Where secrets must never appear
- In the repository. Genesys's blueprints warn not to commit sensitive values in variable files. Keep OAuth credentials in the CI system's secret store, and declare variables as sensitive so plan output hides them; that does not encrypt the state file, a point often assumed otherwise.
- In export output. Exports never contain integration or data action credentials, which become empty variables (part 4), so the export is safe to commit and inert until credentials are supplied.
- In a shared or over-privileged client. One OAuth client across all environments means one leaked secret compromises production. Use separate clients per environment, scoped to the roles the configuration needs, and rotate them on a tested schedule.
- In Archy options files. Their documented format holds the client ID and secret in plain text, so either generate them in the pipeline from the secret store or keep secrets out and pass them on the command line.
10.2 Accountability and lower environments
Client credentials carry no user identity, so the human trail lives in Git: author, pull request and approver. That only improves accountability if branch protection is real; if people can push straight to the main branch, the review trail is decoration.
Genesys's best practice adds a counter-intuitive instruction: lock down test and production so only a very small number of people can make changes, and do not leave lower environments open for speed. A development organisation anyone can edit is where an unplanned queue appears, gets exported into the repository and then propagates to production automatically.
11
Velocity, and what stays out of the repository
The most important scoping decision is what not to manage as code, and Genesys states the principle as a named best practice: understand the velocity of change.
11.1 Genesys's rule
Genesys says not all configuration should be managed under CX as Code. If agents are reassigned to queues several times a day, tying that to a pipeline with several environments and approvals ties critical business processes to it. It recommends defining queues in code but not mapping agents to queues there, and says identity management through SCIM is a much better fit for users and roles. Things that change several times a day should not be under CX as Code.
| In the repository | Outside: SCIM, the console or the API |
|---|---|
| Queues, skills and wrap-up codes | User accounts and attributes |
| Schedules, holidays and opening hours | Queue and skill membership |
| Architect flows | Contact lists and do-not-contact lists |
| Data actions and their integrations | Workforce schedules, forecasts and adherence |
| Prompts and audio | Interactions, recordings and transcripts |
| Divisions and role definitions | Anything a business owner changes daily |
| Messenger configurations and deployments | Objects with no provider resource type |
11.2 Why the boundary matters
Read the right-hand column as owned by a system or a person and changed on business time. SCIM is the clearest case: the identity source of truth is the client's directory, not Git, and a pipeline that provisions users will lose every argument with a directory synchronisation that runs every half hour.
If the boundary is left implicit, the first urgent membership change pushed through the repository teaches everyone that the pipeline is slow and the console is the real system. Once that belief takes hold, the estate drifts and the design becomes decoration. The fix is a correct boundary, so operations never need to go around it.
11.3 What configuration as code does not reach
Genesys's best practice says CX as Code is not a packaged disaster recovery, backup or migration tool; it can help build those, but such tooling is specific to your organisation, takes time to develop and must be tested regularly. Interaction data, contacts, users, workforce data and anything without a resource type are outside it. Integrations are partly inside, because credentials are not exported; flows are partly inside, because of builders and per-organisation validity. Prompt audio and knowledge content need their own handling designed into the pipeline.
Genesys's FAQ offers three routes for an unsupported object: raise an idea on its ideas portal, contribute the resource to the open source provider, or call the API from a script within your Terraform process.
12
The pipeline, drift and break-glass
The pipeline is where the design becomes real. Genesys's requirement is unambiguous: automate everything, with no manual steps and no manual movement of files anywhere between development, test and production.
12.1 Stages
- Validate: terraform validate and archy validateYaml, refreshed against the target organisation.
- Plan: a Terraform plan for every environment, posted to the pull request.
- Review: a required human approval.
- Apply: objects first, then flows with the substitutions for that environment.
- Verify: flow validation against the target organisation and automated smoke tests.
- Promote: merge to the next environment, with the same commit and different variables.
12.2 Ordering and promotion
Terraform works out the order of the dependencies it can see, but flows resolve some dependencies by name, outside Terraform's view. The practical rule is objects before flows. A pipeline that publishes flows in the same breath as creating their queues fails intermittently, and intermittent failures are the ones people retry rather than fix.
Terraform promotes configuration, not artefacts. Production computes its own plan against its own state from the same commit, so a clean test apply does not guarantee a clean production apply if the two have drifted apart.
12.3 Move forward, don't roll back
Genesys's best practice is explicit: CX as Code cannot roll an environment back to a snapshot, and it recommends moving forward, fixing in lower environments and promoting the fix. If you must roll back, tag every production deployment and redeploy the tagged version, run a plan first so you do not drop resources created since, and run automated tests after deployment, in production too, so problems surface quickly instead of tempting someone into the console under pressure.
12.4 Drift
Drift is how a configuration-as-code programme quietly unravels: an object edited in the console is reverted at the next deployment, with no error. Two defences are needed together. Detect it with a scheduled plan against every environment, raising an alert when the plan is not empty. Prevent it by restricting console permissions on managed object types in every environment, including development.
12.5 Break-glass
Genesys asks for this explicitly: avoid console changes in test and production except in a break-glass event, and have a documented playbook for backporting emergency production changes into the CX as Code definitions. If production is failing and someone fixes a queue in the console, the fix is right, and the pipeline will undo it at the next apply unless the repository is updated first.
13
Testing, and the API budget of a pipeline
Terraform and Archy check syntax and dependencies, not behaviour. And every action they take is an API call, so the platform's rate limits shape how a pipeline must be built.
13.1 Four layers of testing
- Static validation on every pull request: terraform validate, and Archy validation against the target organisation.
- Behavioural checks after deployment: a test call or message to each entry point, each data action executed against a test endpoint, and schedules checked for the expected open or closed state. This is the layer people leave out and the one that catches most of what matters.
- Flow regression: the scheduled flow validation from part 7, which catches dependencies that broke after deployment.
- Human acceptance in test, by the people who own the customer journey. Configuration as code makes acceptance trustworthy, because what is approved is what will be deployed; it does not replace it.
13.2 Rate limits: what Genesys publishes
Genesys's FAQ says the provider can be rate limited when many updates run, and retries automatically with backoff. The published limits differ between pages, so cite the one you use and confirm your organisation's value.
| Source | Client credentials token | User tokens |
|---|---|---|
| Developer Center limits page | 500 requests per minute per token, configurable | 300 per minute per token, not configurable; 3,000 per user per minute for certain grants |
| Platform authorisation overview | 300 per minute by default, up to 3,000 on request | Fixed at 300 per minute |
| Limits page, request size | 512,000 bytes per request, not configurable | Same |
13.3 Why pipelines hit the limit
Terraform reads state, computes a difference, applies and re-reads, so a plan touching a few hundred objects can generate well over a thousand requests. Archy's refresh walks the organisation to build schemas, and a matrix build that plans three environments at once multiplies all of it. The provider's token pool, of one to 50 tokens, raises throughput but can itself trigger rate limiting on the OAuth endpoint while it fills, and Genesys's documentation says to match it to parallel paging rather than set it higher.
- Honour Retry-After with exponential backoff in any custom scripts.
- Limit parallelism in matrix builds.
- Run refresh on a schedule rather than in every stage.
- Split very large states, which also reduces the burst per apply.
14
Data actions and functions, handover, and what goes wrong
The last part covers the integration chain, where configuration as code earns its keep, the handover that keeps a pipeline alive, and the problems we see most often.
14.1 Data actions, integrations and functions
Data actions and their integrations are managed resources, but credentials are never exported, so each environment supplies its own endpoint, credentials and sometimes contract through its variables. Genesys's March 2026 blog shows Genesys Cloud Functions deployed through the provider, from integration and data action through to packaging and uploading Node.js code, with the usual init, plan and apply.
That blog lists the constraints: a 15-second execution limit, 1,536 MB of memory, strict payload sizes, no static IP addresses, and Node.js 20 or 22 as the runtimes supported at the time. Its error-handling advice is to return structured responses with a success flag rather than throwing exceptions, so the flow can branch on the result; a function that throws fails a live customer interaction. Its verification step is manual, using the action's Test button and execution log. Our data actions handbook covers the actions themselves.
14.2 Handover
- The repository, with a README that explains why as well as how.
- An environment register: organisations, divisions, licence tiers, capability differences, OAuth clients and their expiry dates.
- The naming and substitution standard.
- A runbook for break-glass, provider and Archy upgrades, credential rotation and state restore.
14.3 What goes wrong
| Symptom | Likely cause | Fix |
|---|---|---|
| First apply into test fails on duplicate names | Terraform creates; it does not adopt existing objects | Seed state, or build a clean organisation (part 4) |
| A console change vanishes | Terraform reverts objects it owns | Restrict console rights, detect drift, follow the playbook (part 12) |
| Flow points at a queue that does not exist | Missing substitution key, or a rename in one environment | Every key in every file; renames across all environments (parts 5 and 9) |
| Flow valid in development, invalid in production | Schemas and validity are per organisation | Match entitlements; refresh against the target (part 6) |
| Exported configuration will not apply | Credentials are never exported | Make credential collection a milestone (part 4) |
| Flow comparison shows every line changed | Tracking IDs not included on export | Include tracking ID details (part 7) |
| Shared YAML fails to import | References inside a common file are not allowed | Keep the shared library flat (part 5) |
| Audio sequence lost after a YAML round trip | Builders are not supported in Archy | One authoritative version per flow (part 6) |
| Archy cannot reach Genesys from the build agent | No proxy support in Archy | Direct egress, or the provider's flow resource (parts 6 and 7) |
| Apply fails part-way, then works on retry | Rate limiting on a large run | Backoff, less parallelism, smaller states (part 13) |
| Archy fails intermittently in parallel jobs | Several instances sharing one home directory | One runner per home (part 6) |
| Renaming a flow leaves the old one behind | The flow resource creates a new flow on rename | Plan renames and remove the old flow deliberately (part 7) |
| Provider upgrade breaks attributes mid-release | Provider version not pinned | Pin exactly; upgrade by its own commit (part 9) |
| A rebuild leaves objects behind | No resource type for them | Coverage check at design (part 3) |
Questions
Common questions
Can I use CX as Code to copy production into a test organisation?
Not as a copy. Genesys's FAQ says exports can be applied to another organisation but this is not the primary use case: Terraform creates resources on the first apply and fails where objects with the same names exist, so it works best into a new organisation. It copies definitions only, with no data, users or credentials. Build each environment from the same versioned configuration instead.
Why did a change I made in the Genesys Cloud console disappear?
Because Terraform expects to be the only maintainer of the objects it owns. Genesys's best practice says that if you change a Terraform-managed object in the console, the next run reverts it. Restrict console permissions on managed object types, run a scheduled plan to detect drift, and backport any emergency console change into the repository before the next deployment.
Is the CX as Code flow resource still in beta?
A 2022 Genesys blog described it as a closed beta. The provider's current documentation describes genesyscloud_flow with no beta notice: it takes a flow YAML file, supports substitutions in place of an Archy options file, and can force unlock and create stub dependencies. Note that renaming a flow through it creates a new flow and leaves the original in the organisation.
Can Archy substitutions replace whole blocks of a flow?
No. Genesys explains that Archy replaces substitutions with a text replacement algorithm, so they should supply property values, such as a queue name or prompt text, not chunks of YAML, and it recommends references for embedding actions or tasks. Keys need values that are strings, numbers or Booleans, and Genesys's examples quote every substituted string.
Should I use divisions instead of separate test and production organisations?
No. A division separates access and visibility within one organisation; it does not isolate runtime. There is one set of published flows and queues per organisation, and Architect puts a published flow into effect immediately, so a flow published in a test division is live. Use separate organisations for environments and divisions inside them for brands or regions.
What API rate limit applies to a CX as Code pipeline?
Pipelines use client credentials tokens. Genesys's limits page shows 500 requests per minute per token, configurable, while its authorisation overview describes 300 by default, raisable to 3,000 on request. Confirm your organisation's value, plan against the lower figure, and design for backoff; Genesys says the provider retries with backoff when rate limited.
Sources
- Define Architect flows using YAML – Genesys Cloud Resource Centerhelp.genesys.cloud
- Validate a flow – Genesys Cloud Resource Centerhelp.genesys.cloud
- Import or export a flow – Genesys Cloud Resource Centerhelp.genesys.cloud
- Maintain a flow – Genesys Cloud Resource Centerhelp.genesys.cloud
- Manage flows – Genesys Cloud Resource Centerhelp.genesys.cloud
- Publish an Architect flow – Genesys Cloud Resource Centerhelp.genesys.cloud
- Work with in-queue flows – Genesys Cloud Resource Centerhelp.genesys.cloud
- How does my organization get configured for a beta? – Genesys Cloud Resource Centerhelp.genesys.cloud
- December 15, 2021 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
- July 13, 2026 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
- May 5, 2021 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
- October 26, 2026 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
- CX as Code – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- CX as Code FAQ – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- CX as Code best practices – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Welcome to Archy – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Archy frequently asked questions – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Archy commands and parameter values – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Using Archy in automated environments – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Archy setup – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Archy JSON object schemas and the refresh command – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Archy example flows – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Archy lesson 7: substitutions – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Archy changelog – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Platform API CLI – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Genesys Cloud low code guide – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Limits – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Platform authorization overview – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Introducing CX as Code – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Introducing the new Archy export feature – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- How to begin your CX as Code journey – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- A quick update on CX as Code – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- CX as Code and DevOps best practices – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- CX as Code and remote modules – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Introducing Genesys Cloud Terraform Functions – Genesys Cloud Developer Centerdeveloper.genesys.cloud
- Genesys Cloud provider (MyPureCloud/genesyscloud) – Terraform Registryregistry.terraform.io
- terraform-provider-genesyscloud – GitHubgithub.com
Keep reading
More guides
Genesys Cloud user lifecycle: the handbook for SCIM, SSO, MFA and licences
A detailed handbook to running Genesys Cloud users: joiners, movers and leavers, CSV import, SCIM, SSO, MFA, deletion and GDPR, and licence operations.
Read the guideGenesys Cloud workforce management: the workforce planner's handbook
A detailed Genesys Cloud workforce management handbook for planners: set-up, forecasting, scheduling, time off, intraday, shrinkage and an operating procedure.
Read the guideGenesys Cloud routing explained: bullseye, conditional, preferred and predictive
How Genesys Cloud ACD routes interactions: evaluation and scoring methods, skills, bullseye, conditional group, preferred agent, predictive and utilisation.
Read the guide