How to use the Loop block to iterate over a JSON array returned from a Data Action

How-To-Articles
1

How to use the Loop block to iterate over a JSON array returned from a Data Action

What You Will Build

  • This tutorial demonstrates how to extract a JSON array from a Genesys Cloud Data Action response, pass that array into a Loop block, and process each item within a NICE CXone Studio flow.
  • The implementation uses the NICE CXone Studio visual flow editor and the underlying JSON data structure exposed by the platform.
  • The logic covers the specific mechanics of mapping Data Action output to Loop input, handling empty arrays, and accessing nested properties within the loop body.

Prerequisites

  • Platform: NICE CXone (formerly Five9).
  • Studio Access: You must have access to the CXone Studio environment with permissions to create and deploy Flows.
  • Data Action: A pre-existing Data Action that returns a JSON array. For this tutorial, we assume a Data Action named GetCustomerOrders that returns a structure like {"orders": [{ "id": "123", "status": "pending" }, ...]}.
  • Understanding of JSON: Familiarity with JSON syntax, specifically arrays and objects, is required.
  • Studio Version: CXone Studio version 10.0 or later (Loop blocks have evolved; this tutorial assumes the modern Loop block behavior).

Authentication Setup

  • CXone Studio is a web-based visual interface. Authentication is handled via your browser session after logging into the CXone Portal.
  • No API keys or OAuth tokens are required to build the flow, as the Studio environment authenticates the user session automatically.
  • When testing the flow via the CXone API (for validation), you will need an OAuth token with the studio:flow:read scope, but for building the flow, simply log in to https://[your-domain].cxone.com/studio.

Implementation

Step 1: Define the Data Action Output Structure

Before configuring the Loop block, you must understand the exact shape of the data returned by your Data Action. The Loop block requires an input that is a valid JSON array. If your Data Action returns an object containing an array, you must reference the specific array field.

  1. Open your CXone Studio Flow.
  2. Drag a Data Action block onto the canvas.
  3. Select your Data Action (e.g., GetCustomerOrders).
  4. In the Properties panel, locate the Output section.
  5. Note the variable name assigned to the output. By default, Studio often names this dataActionOutput or similar.
  6. Inspect the schema. If the output is:
    {
  "orders": [
    { "id": "A1", "amount": 100 },
    { "id": "B2", "amount": 200 }
  ]
}
    The array is located at dataActionOutput.orders. The Loop block cannot iterate over the root object; it must iterate over the orders array.

Step 2: Configure the Loop Block

The Loop block in CXone Studio is designed to iterate over an array of items. It exposes a context variable within its body that represents the current item.

  1. Drag a Loop block onto the canvas.
  2. Connect the Success output of your Data Action to the Start input of the Loop block.
  3. Select the Loop block and open the Properties panel.
  4. Input Array: Click the input field for the array source.
    • Use the data mapper to select the specific array field from the previous step.
    • Select dataActionOutput → orders.
    • Critical: Ensure you are selecting the array itself, not the parent object. If you select the parent object, the loop will fail or iterate over object keys instead of values.
  5. Item Variable Name: Define the name of the variable that will hold the current item during each iteration.
    • Set this to currentOrder.
    • This variable will be available inside the Loop body.

Step 3: Handle Empty Arrays

A common failure point in CXone Studio flows is sending an empty array to a Loop block. Depending on the Studio version and configuration, this may cause the flow to halt or skip entirely without error. To ensure robustness, you should validate the array length before entering the loop.

  1. Drag a Condition block onto the canvas.
  2. Connect the Data Action’s Success output to the Condition block.
  3. Connect the Condition’s True output to the Loop block.
  4. Connect the Condition’s False output to a fallback path (e.g., a “No Orders Found” message).
  5. Configure the Condition:
    • Left Operand: Select dataActionOutput.orders.
    • Operator: Select Length or Count (depending on Studio version).
    • Right Operand: Set to 0.
    • Logic: Greater Than.
    • Alternative: If your Studio version supports direct boolean checks, check if dataActionOutput.orders is not empty.

This ensures that the Loop block only executes when there is data to process.

Step 4: Process Items Within the Loop Body

Inside the Loop block, you can access properties of the current item using the item variable defined in Step 2 (currentOrder).

  1. Enter the Loop block body.
  2. Add a Set Variable block to demonstrate data access.
  3. Create a new variable named orderStatus.
  4. Map the value to currentOrder.status.
  5. Add a Log block (or Message block) to verify the value.
    • Set the message to: Processing Order ID: ${currentOrder.id}.
    • Note the use of ${} syntax for string interpolation in Studio messages.

Step 5: Handle Loop Completion

After the Loop block finishes iterating through all items, the flow continues from the End output of the Loop block.

  1. Connect the End output of the Loop block to a Set Variable block.
  2. Create a variable named processingComplete with value true.
  3. Connect this to a final Message block: All orders processed..

Complete Working Example

Below is the logical structure of the flow. You can replicate this in CXone Studio by following the block connections.

Flow Name: Process Customer Orders

Blocks:

  1. Start
  2. Data Action: GetCustomerOrders
    • Output Variable: dataActionOutput
  3. Condition: HasOrders
    • Condition: dataActionOutput.orders.length > 0
    • True Path: To Loop
    • False Path: To “No Orders” Message
  4. Loop: ForEachOrder
    • Input Array: dataActionOutput.orders
    • Item Variable: currentOrder
    • Body:
      • Set Variable: orderStatus = currentOrder.status
      • Log: Processing: ${currentOrder.id} - Status: ${orderStatus}
    • End Path: To “Complete” Message
  5. Message: No orders found. (Connected from Condition False)
  6. Message: All orders processed. (Connected from Loop End)

JSON Representation of Data Action Output (Example):

{
  "orders": [
    {
      "id": "ORD-001",
      "status": "shipped",
      "amount": 45.99
    },
    {
      "id": "ORD-002",
      "status": "pending",
      "amount": 120.50
    }
  ]
}

Expected Log Output:

Processing: ORD-001 - Status: shipped
Processing: ORD-002 - Status: pending

Common Errors & Debugging

Error: “Input is not an array” or Loop fails silently

  • Cause: The Data Action output is an object, but you mapped the root object to the Loop’s Input Array field instead of the specific array field within the object.
  • Fix: Inspect the Data Action output schema. If the output is { "data": [ ... ] }, you must map dataActionOutput.data to the Loop input, not dataActionOutput.
  • Verification: Add a Log block immediately before the Loop to print the type of the input variable. In CXone Studio, you can often use a JavaScript expression or a simple string concatenation to check the structure.

Error: “Variable not found: currentOrder”

  • Cause: You are trying to access the item variable (currentOrder) outside the Loop body. The item variable is scoped strictly to the Loop block.
  • Fix: Ensure all references to currentOrder are inside the Loop block’s visual container. If you need to aggregate data from the loop, use a Set Variable block inside the loop to append to a list or accumulate a total, then access that aggregate variable after the Loop ends.

Error: Infinite Loop

  • Cause: This is rare in CXone Studio’s visual Loop blocks because they are designed to iterate over a static array. However, if you modify the array source variable inside the loop (which is generally not recommended or allowed in pure visual flows), it can cause unexpected behavior.
  • Fix: Do not modify the source array (dataActionOutput.orders) inside the loop. Create a new variable for any modified data.

Error: Performance issues with large arrays

  • Cause: The Loop block processes items sequentially. If the Data Action returns 1,000+ items, the flow will take a long time to complete, potentially timing out.
  • Fix:
    1. Limit the Data Action query to return fewer results (pagination).
    2. Use a Batch operation if the subsequent action supports bulk updates.
    3. Consider moving the loop logic to a backend API endpoint rather than processing it in the Studio flow.

Official References