Parsing and Flattening Complex Nested JSON Responses Using JSONPath

How-To-Articles
1

Parsing and Flattening Complex Nested JSON Responses Using JSONPath

Executive Summary & Architectural Context

When integrating Genesys Cloud with modern SaaS platforms (Salesforce, Zendesk, ServiceNow), the REST API responses are almost never simple, flat key-value pairs. They are deeply nested JSON objects containing arrays, sub-objects, and metadata layers.

Genesys Cloud Architect flows cannot natively parse nested JSON arrays. If a Data Action returns a complex payload to Architect, the flow will fail because the Architect variable engine only accepts flat strings, integers, and booleans.

The engineering solution happens in the Data Action Configuration layer. Before the payload ever reaches Architect, you must use JSONPath combined with Velocity templating in the Data Action’s Translation Map to flatten the response into a simple, 1-dimensional contract. This masterclass details the exact syntax and strategies required to tame massive, unpredictable JSON payloads into clean variables for your IVR.

Prerequisites, Roles & Licensing

  • Licensing: Available on all Genesys Cloud CX tiers.
  • Roles & Permissions: Integrations > Action > Edit
  • Platform Dependencies:
    • Access to the API documentation of the third-party system.
    • A tool like JSONPath.com to validate your expressions before pasting them into Genesys Cloud.

The Implementation Deep-Dive

1. The Problem: The Nested JSON Payload

Assume your CRM returns the following payload when searching for a customer by phone number:

{
  "total_results": 1,
  "data": {
    "customers": [
      {
        "id": "CUST-9921",
        "profile": {
          "status": "Platinum",
          "balance": 450.25
        }
      }
    ]
  }
}

If you pass this raw payload to Architect, it will crash. Architect needs a flat contract: CustomerID, Status, Balance.

2. Defining the Output Contract

First, tell the Data Action what the final, flattened structure should look like.

  1. Navigate to your Data Action > Setup > Contracts > Output.
  2. Define a simple, flat JSON schema:
{
  "type": "object",
  "properties": {
    "CustomerID": { "type": "string" },
    "Status": { "type": "string" },
    "Balance": { "type": "number" }
  }
}

3. The Translation Map (The JSONPath Engine)

The Translation Map uses JSONPath to dive into the raw response, grab the specific nested values, and assign them to temporary variables.

  1. Navigate to Setup > Configuration > Response.
  2. In the translationMap block, map your JSONPath queries.
    • To get the ID from the first item in the array: $.data.customers[0].id
    • To get the status: $.data.customers[0].profile.status
"translationMap": {
  "raw_id": "$.data.customers[0].id",
  "raw_status": "$.data.customers[0].profile.status",
  "raw_balance": "$.data.customers[0].profile.balance"
}

4. Translation Map Defaults (Safety Net)

If the CRM returns 0 results, the array customers[0] does not exist. The JSONPath query will fail, causing the entire Data Action to fail and routing the caller to an error path. You must provide fallback values.

"translationMapDefaults": {
  "raw_id": "\"NOT_FOUND\"",
  "raw_status": "\"UNKNOWN\"",
  "raw_balance": "0"
}

Note the escaped quotes for strings. JSONPath defaults inject the literal text into the Velocity template.

5. The Success Template (Building the Flat Payload)

Finally, take the temporary variables and map them to the Output Contract you defined in Step 2. This is done using a Velocity macro.

"successTemplate": "{\n  \"CustomerID\": ${raw_id},\n  \"Status\": ${raw_status},\n  \"Balance\": ${raw_balance}\n}"

When Architect calls this action, it will now receive a clean, 1-dimensional JSON object perfectly formatted for standard variables.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Array Length Unknown (Extracting Lists)

If you need to extract a list of all recent order IDs (e.g., to read them to the caller), you cannot flatten them into a single string easily without advanced Velocity scripting.

  • Solution: Use JSONPath wildcard syntax: $.data.orders[*].order_id. This extracts all order IDs into a JSON array.
  • Architect Handling: In your Output Contract, define the field as an array of strings. Architect can handle arrays of strings (String Collections), which you can then iterate over using a Loop node in your call flow.

Edge Case 2: String Escaping Nightmares

If the CRM returns a customer name containing quotes (e.g., O'Connor or John "The Boss" Doe), the standard successTemplate will break because injecting a raw quote ruins the JSON structure.

  • Troubleshooting: Do not write manual JSON strings in the successTemplate if you expect unpredictable data. Instead, use the built-in Genesys Velocity macro $successTemplateUtils.firstFromArray().

The bulletproof Success Template:

"successTemplate": "${successTemplateUtils.firstFromArray(\"${raw_id}\", \"${raw_status}\")}"

This macro automatically sanitizes string outputs, handles array stripping, and guarantees perfectly valid JSON is passed back to Architect regardless of weird CRM data entry.

Official References

To master JSONPath and Velocity macros in Genesys Cloud, deeply review the following developer resources: