How to Structure and Deploy Reusable Common Modules in Architect

How-To-Articles
1

How to Structure and Deploy Reusable Common Modules in Architect

Executive Summary & Architectural Context

In enterprise-grade Genesys Cloud environments, Contact Center IVRs rapidly become massive, monolithic beasts. When multiple departments (Sales, Support, Billing) all require the same complex logic-such as verifying a customer’s VIP status via a CRM Data Action, calculating business hours based on dynamic data tables, or authenticating an account number-copy-pasting this logic across 50 different Inbound Call Flows is architectural suicide. It creates massive technical debt, guarantees inconsistent customer experiences, and makes system-wide updates a nightmare.

The engineering solution is the Common Module. A Common Module in Genesys Cloud Architect is a globally scoped, reusable flow fragment that encapsulates specific business logic. It acts exactly like a functional subroutine or a class method in software engineering. You pass it input variables, it executes its logic, and it returns output variables.

This masterclass details the precise methodology for engineering, versioning, and deploying Common Modules to drastically reduce flow footprint and ensure single-source-of-truth logic across your entire CCaaS ecosystem.

Prerequisites, Roles & Licensing

Before architecting common modules, verify the following:

  • Licensing: Available on all Genesys Cloud CX tiers.
  • Roles & Permissions:
    • Architect > Flow > Edit (to create and modify Common Modules)
    • Architect > Flow > Publish (to deploy the module for consumption)
  • Architectural Rules:
    • Common Modules cannot contain Transfer or Disconnect nodes. They must always return control to the parent flow.
    • Common Modules cannot play audio prompts directly unless explicitly designed for it, though it is highly discouraged as it breaks the separation of logic and presentation.

The Implementation Deep-Dive

Step 1: Defining the Contract (Inputs and Outputs)

Just like an API, a Common Module must have a strict contract. The parent flow needs to know exactly what to send in, and what to expect out.

  1. Navigate to Architect > Common Modules and click Add.
  2. Name the module strictly according to its function (e.g., CM_Authenticate_Account).
  3. Define your Input Variables:
    • Go to Data > Variables.
    • Create a string variable Task.Input_AccountNumber.
    • CRITICAL: In the variable settings, set the Variable Scope to Input. This exposes it to the parent flow.
  4. Define your Output Variables:
    • Create a boolean variable Task.Output_IsAuthenticated.
    • Create a string variable Task.Output_AccountTier.
    • Set their Variable Scope to Output.

Step 2: Building the Encapsulated Logic

Now, construct the core logic inside the Common Module.

  1. Add a Call Data Action node that hits your CRM API, passing Task.Input_AccountNumber.
  2. Configure the Success path:
    • Use an Update Data action to set Task.Output_IsAuthenticated = True.
    • Parse the CRM response to set Task.Output_AccountTier.
  3. Configure the Failure/Timeout path:
    • Set Task.Output_IsAuthenticated = False.
  4. End the Task: The logic must terminate at an End Task node. When the task ends, Architect automatically returns control to the parent flow, passing the output variables back.

Step 3: Publishing and Versioning

A Common Module cannot be consumed by a parent flow until it is published.

  1. Click Publish.
  2. Note the version number (e.g., v1.0).
  3. Dependency Warning: When you publish a Common Module, any parent flow currently utilizing an older version will NOT automatically update to the new version. This is a crucial safety mechanism to prevent system-wide regressions.

Step 4: Consuming the Module in a Parent Flow

With the module published, it is time to inject it into your Inbound Call Flows.

  1. Open your Inbound Call Flow (e.g., Sales_Inbound).
  2. Drag a Call Common Module action into your task logic.
  3. In the configuration panel, select CM_Authenticate_Account.
  4. Select the specific version you want to use (usually Latest).
  5. Map the Inputs: You will see a field for Input_AccountNumber. Assign a flow variable to it (e.g., the digits collected from a Collect Input node).
  6. Map the Outputs: Define where the module should dump its results. Map Output_IsAuthenticated to a local flow variable Task.IsAuth.
  7. Add a Decision node immediately after the Common Module to evaluate Task.IsAuth and route the call accordingly.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Infinite Loops via Recursion

Genesys Cloud permits Common Modules to call other Common Modules. However, if Module A calls Module B, and Module B calls Module A, you have created infinite recursion.

  • Result: The Architect runtime engine has a strict loop detection mechanism. If a flow iterates recursively without yielding, the platform will terminate the call and throw a systemic error to protect infrastructure.
  • Prevention: Enforce a strict “DAG” (Directed Acyclic Graph) architecture. Modules should only call “downward” into utility modules, never laterally or upward.

Edge Case 2: The “Update All” Trap

When a critical bug is fixed in a Common Module (e.g., updating a broken API endpoint), you will publish v2.0. However, the 50 parent flows using v1.0 are still broken.

  • Troubleshooting: You must open every single parent flow, click on the Call Common Module node, manually update the version selector to v2.0, and re-publish the parent flow.
  • Best Practice: Use the Dependency Report within the Common Module’s overview screen to find a list of every Inbound Flow that currently references it, ensuring you don’t miss any updates.

Official References

To master the nuances of Common Module architecture and dependency management, refer to: