6 Rules for Portable Genesys Cloud Configurations
A practical, opinionated checklist for keeping your Genesys Cloud configurations portable, governable, and ready for automation.
These six rules are the foundation of portable, production-ready Genesys Cloud configurations. They're the same principles CXDeploy enforces and automates, so you can promote changes confidently between Test, UAT, and Prod.
Pillar 1: Portability & ID Management
This pillar directly addresses the ID remapping problem that CXDeploy solves. IDs are different in every org, but names can be stable, predictable, and automatable.
Rule 1
Always Reference by Name, Never by GUID (The Golden Rule)
Never copy a UUID (ID) from the URL or an API response into a file, external documentation, or another configuration object if you can avoid it. Instead, rely on the object's unique, human-readable name—for example, Sales_Queue.
How CXDeploy helps: CXDeploy uses name-based lookup to guarantee the correct ID is used in the target environment. This is how we safely resolve the right queue, flow, or data action when promoting between orgs.
Rule 2
Adopt Strict Naming Conventions
Use a consistent naming scheme that includes project and division prefixes, such as PRJ_NAME_Queue_Function. This ensures that even if you have ten different "Main Flows," they are uniquely identifiable when searching the API or your snapshots.
Why it matters for CXDeploy: these conventions are critical for CXDeploy's ability to reliably find the correct target object during the promotion workflow.
Pillar 2: Decoupling Environment Values
Decoupling keeps your application logic clean and your environments safe. It's also a prerequisite for any serious automation.
Rule 3
Ban Hardcoded URLs and Endpoints
Absolutely prohibit hardcoding external API URLs into Data Action configurations. Hardcoded endpoints lock a flow to a specific environment and make safe promotion nearly impossible.
Best practice: mandate the use of Integration Configuration Parameters (e.g., $rest.baseUrl) for all external endpoints.
How CXDeploy enforces this: CXDeploy will block promotions that violate this rule. Hardcoded URLs make configurations non-portable, so we treat them as a safety issue, not just a style problem.
Rule 4
Isolate All Secrets
All credentials, keys, and tokens must be stored using Genesys Cloud's Secure Variables mechanism and accessed via the $credentials syntax. Secrets should never live inside flow logic, data action bodies, or documentation.
How CXDeploy handles secrets: CXDeploy will not snapshot or expose these secret values. We intentionally treat them as write-only, reinforcing the security benefit of this practice.
Pillar 3: Cleanliness and Governance
These rules reduce complexity today and unlock future automation—including CXDeploy V3 capabilities.
Rule 5
Maintain Snapshot Freshness
Ensure that your target organization (for example, Prod) has a successful snapshot taken at least once every 24 hours. Stale snapshots create blind spots and risk.
Why this matters for CXDeploy: the CXDeploy Impact Analysis relies on a fresh snapshot to accurately warn you about breaking changes—like a modified queue that affects multiple flows. Without recent data, those warnings become less reliable.
Rule 6
Define Ownership Boundaries (Divisions)
Clearly define which teams or projects own which Divisions, and minimize unnecessary cross-divisional dependencies. Ambiguous ownership leads to tangled promotion paths and slow incident response.
How this helps CXDeploy: clear divisional boundaries simplify scoping for the CXDeploy Workspace Promotion feature and make it easier to automate targeted, safe deployments.
Adopting these rules today makes every future deployment easier. CXDeploy is built to enforce and automate them—so your teams can focus on designing great customer experiences, not chasing brittle configuration bugs.