Operational Console Workaround

Problem

Genesys Cloud’s operational console returns failed and error outputs; however, it often lacks the necessary data to support effective investigation and troubleshooting.

Example:

The image above shows only the current value and error code. It does not provide any information to help identify which flow, queue, or conversation the error occurred in.

The following example offers more context:

With the conversationId, we can easily locate and analyze the error.

Cause

Genesys Cloud does not have a robust failure and error event handling system by default. The primary sources of these unidentified errors are:

• Find functions and actions used within any flow
• Common Module Flows, which may not log sufficient context when failures occur

Solution

graph TB
    subgraph Inbound / In-Queue Flow
        A[Find function] -->
        B[Call Common Module Flow:
        Object Lookup Failure
        ]
    end

    subgraph Inbound / In-Queue Flow
        C[Find action]
        C -->|Found| D[...]
        C -->|Not Found| E[Call Common Module Flow:
        Object Lookup Failure
        ]
    end

    subgraph Object Lookup Failure
        F[Call Data Action:
        Post Operational Events Query]
        F -->|Error| G[Call Data Action: Trigger Workflow]
        F -->|No Error| H[Exit]
    end

    subgraph Workflow
        I[Call Data Action: Create Row in Operational Events]
    end

    B --> F
    E --> F
    G --> I

As a workaround, the solution includes:

• Data Action: Post Operational Events Query
• Data Action: Trigger Workflow
• Data Action: Create Row in Operational Events
• Data Table: Operational Events
• Common Module Flow: Object Lookup Failure
• Workflow: Create Row in Operational Events

Data Action: Post Operational Events Query

• POST /api/v2/usage/events/query
• Request Body:

{
  "interval": "${input.interval}", // 2025-10-07T18:37:32.690Z/2025-10-07T18:37:32.786Z
  "sortOrder": "ASC",
  "eventDefinitionIds": ["ARCHITECT-0001"]
}

• Response Body:

{
  "entities": [
    {
      "eventDefinition": {
        "id": "ARCHITECT-0001",
        "selfUri": "/api/v2/usage/events/definitions/ARCHITECT-0001"
      },
      "currentValue": "MAX_VOICE_DEV",
      "errorCode": "LOOKUP_OBJECT_BY_NAME_NOT_FOUND",
      "dateCreated": "2025-10-07T18:37:32.704Z"
    },
    {
      "eventDefinition": {
        "id": "ARCHITECT-0001",
        "selfUri": "/api/v2/usage/events/definitions/ARCHITECT-0001"
      },
      "currentValue": "MAX",
      "errorCode": "LOOKUP_OBJECT_BY_NAME_NOT_FOUND",
      "dateCreated": "2025-10-07T18:37:32.731Z"
    }
  ]
}

Data Action: Trigger Workflow

• POST /api/v2/flows/executions
• Request Body:

{
    "flowId": "${input.flowId}",
    "inputData": {
        ${input.inputData}
        // "Flow.errorCode": "LOOKUP_OBJECT_BY_NAME_NOT_FOUND",
        // "Flow.conversationId": "45004b6b-2ae5-4201-850d-00f7a30fff8e",
        // "Flow.originFlow": "Inbound Call Flow: [DEV] Dependency Tracking [76.0] → Common Module: Object Lookup Failure v2",
        // "Flow.erroredVariable": "Flow.ScheduleGroup",
        // "Flow.currentValue": "MAX",
        // "Flow.dateCreated": "2025-10-07T18:37:32.731Z",
        // "Flow.eventDefinitionId": "ARCHITECT-0001"
    }
}

Data Action: Create Row in Operational Events

• POST /api/v2/flows/datatables/${input.datatableId}/rows
• Request Body:

{
  "KEY": "${input.KEY}", // 2025-10-07T18:37:32.704Z~45004b6b-2ae5-4201-850d-00f7a30fff8e
  "ConversationId": "${input.ConversationId}", //45004b6b-2ae5-4201-850d-00f7a30fff8e
  "DateCreated": "${input.DateCreated}", // 2025-10-07T18:37:32.704Z
  "Origin": "${input.Origin}", // Inbound Call Flow: [DEV] Dependency Tracking [76.0] → Common Module: Object Lookup Failure v2
  "ErrorCode": "${input.ErrorCode}", // ARCHITECT-0001 LOOKUP_OBJECT_BY_NAME_NOT_FOUND
  "ErroredVariable": "${input.ErroredVariable}", // Flow.Queue
  "Value": "${input.Value}" // MAX_VOICE_DEV
}

Common Module Flow: Object Lookup Failure

• Dependencies:
  • Data Action: Post Operational Events Query
  • Data Action: Trigger Workflow
• Captures the current dateTime
• Calls Data Action: Post Operational Events Query
  • If entities.length > 0, there’s an error
    • Loops through the given variables list
      • Switch case 1: If variable[index] includes the string “Flow.”, call Data Action: Trigger Workflow
      • Switch case 2: If variable[index] includes the string “Task.”, call Data Action: Trigger Workflow
      • Default: Next loop
  • If entities.length == 0, exit the flow

Workflow: Create Row in Operational Events

• Dependencies:
  • Data Action: Create Row in Operational Events
• Gets triggered by Data Action: Trigger Workflow when there’s an error.

Implementation

Inbound / In-Queue Flows

1. Capture the Current DateTime
   • Example: Task.InitialDateTime = GetCurrentDateTimeUtc()
   • This step is important because it records the timestamp before any potential errors occur.
   • We’ll need this to be able to add to the dateTime interval for Data Action: Post Operational Events Query.
2. Initialize Variables
   • Set key variables and their initial values to support dependency tracking.
   • Refer to Dependency Tracking for more details.
3. Identify Variables Utilizing Find Functions
   • Create a string collection variable to track whether specific objects were found.
   • isSet(Flow.ScheduleGroup) ? Flow.ScheduleGroup.name : "Flow.ScheduleGroup": This assigns the object name if found, or the variable name if not.
   • If using Genesys’ built-in Find action, assign the variable under the Not Found path.
4. Use Common Module Flow: Object Failure Lookup
   • After initializing data or using a Find action, invoke the common module flow Object Lookup Failure
   • When using the Find action, call the common module flow in the Not Found path, after identifying variables.
   • Inputs:
     • Common.ArchitectFlow: Name of the Architect Flow
     • Common.ConversationId
     • Common.InitialDateTime: Use the variable from step 1
     • Common.InvolvedVariables: Include the string collection variable created earlier
   • Outputs:
     • Common.ErroredVariablesArray, string collection: Lists variables that were not properly set
     • Common.ErrorOccurred, boolean: Returns true if an error occurred, otherwise, false.
   • Result:
   • Optional:
     • Result from Common.ErrorOccurred can be used as somewhat of an error handling

Common Module Flows

Since common module flows cannot be called within another common module flow, the solution must be implemented inside.

Outcome

If there is an error, a workflow will be triggered. It will create a row in Operational Events data table with more details for each error

Source

• Data Action: Post Operational Events Query
• Data Action: Trigger Workflow
• Data Action: Create Row in Operational Events
• Data Table: Operational Events
• Common Module Flow: Object Lookup Failure
• Workflow: Create Row in Operational Events