Skip to main content

Scenario 1: Simple Weather API Call

Test in progress use at your own risk!

Skill Level: Beginner to Intermediate
Time to Complete: 45-60 minutes (lab included)
Prerequisites: Genesys Cloud org access, Architect admin role, browser
Verified Against: Genesys Cloud docs (March 2026), Open-Meteo API docs (March 2026)

Executive Summary

This scenario teaches you how to:

  1. Create a data action that calls an external REST API (Open-Meteo weather)
  2. Configure the three output paths (Success, Failure, Timeout)
  3. Parse JSON responses using translation maps and Velocity macros
  4. Use the API response in an Architect flow to make a routing decision
  5. Understand what happens when the API is slow, returns an error, or times out

Real-world use case: A financial services IVR asks for the caller's city, looks up current weather, and routes them:

  • Good weather → Sales queue (outdoor account interest)
  • Bad weather → Account services queue (likely indoor issues)
  • API timeout → Queue directly (no time to look up weather)

Part 1: Conceptual Foundation (Read This First)

What Is a Data Action?

In Genesys Cloud, a Data Action is a reusable connector that:

  • Makes an HTTP request to an external API
  • Receives a JSON response
  • Parses that response using translation maps (JSONPath) and success templates (Velocity)
  • Returns structured data back to your Architect flow

Think of it like this:

Architect Flow → [HTTP GET] → Open-Meteo API → [JSON weather] → Translation Map → Flow Variable
                                 ↓
                            (Success/Failure/Timeout)

Why Three Output Paths?

Every data action execution has three possible outcomes:

PathWhen It FiresExample
SuccessHTTP 200-299 + response parsing succeededGot temp=72°F, humidity=55%
FailureHTTP 4xx/5xx OR response parsing failedGot 404 "location not found"
TimeoutRequest exceeded timeout window (1-60 sec)Called API but server didn't respond in 30 sec

You must handle all three paths in your flow. If you don't, callers hit an error state.

Why This Matters for IVR

Imagine you build an IVR that calls a data action but only configure the Success path:

  • ✅ Caller in New York, API responds fast → caller hears weather, routes correctly
  • ❌ Caller in Mumbai, API is slow (timeout) → IVR breaks, caller hears error tone, call drops

By handling all three paths, you ensure:

  • Resilience: Slow APIs don't break your flow
  • Fallback logic: Timeout takes different action than error
  • Caller experience: Professional routing even when external systems fail

Part 2: The API We're Using (Open-Meteo)

Why Open-Meteo?

✅ Free — No API key, no registration required
✅ Fast — <10ms average response
✅ Reliable — 99.9% uptime, production-grade
✅ Simple — Standard REST + JSON (easy to learn)
✅ Fair use — 10,000 free requests/day (safe for lab)

Source: https://open-meteo.com/, https://github.com/open-meteo/open-meteo

The Endpoint We'll Call

GET https://api.open-meteo.com/v1/forecast
    ?latitude=25.85
    &longitude=-100.27
    &current=temperature_2m,weather_code,wind_speed_10m
    &temperature_unit=fahrenheit
    &timezone=auto

What it means:

  • latitude, longitude = Monterrey, Mexico (for our example)
  • current = Only get current conditions (not hourly/daily forecast)
  • temperature_unit = Return in Fahrenheit (for US callers)
  • timezone=auto = Genesys will calculate from coords

The Response (What We Get Back)

{
  "latitude": 25.85,
  "longitude": -100.27,
  "timezone": "America/Chicago",
  "current": {
    "time": "2026-03-14T15:30",
    "temperature_2m": 78,
    "weather_code": 0,
    "wind_speed_10m": 8.5
  },
  "current_units": {
    "temperature_2m": "°F",
    "wind_speed_10m": "km/h"
  }
}

Key fields:

  • current.temperature_2m → Current temp (78°F)
  • current.weather_code → WMO code (0=clear sky, 1=mainly clear, 45=foggy, etc.)
  • current.wind_speed_10m → Wind speed at 10m height

Part 3: Building the Data Action in Genesys Cloud

Step 1: Create a Custom Data Action

Path in Genesys UI:

Admin → Integrations & Apps → Data Actions → New Action
FieldValueWhy
NameGetCurrentWeatherClear, verb-noun naming
CategoryWeatherOrganizational (optional but good practice)
IntegrationWeb Services Data ActionsFor calling external REST APIs

Click Create.

Step 2: Define the Input Contract

This tells Genesys what data your flow will send to the API call.

Add Input Fields:

Field NameTypeRequired?DescriptionExample
LATITUDENumberYesGeographic latitude25.85
LONGITUDENumberYesGeographic longitude-100.27
TEMPERATURE_UNITStringNofahrenheit or celsiusfahrenheit

UI Path: Click Input Contract → Add Property

Why these inputs?

  • Latitude/longitude identify the location
  • Temperature unit allows caller preference (US vs. Canada)
  • We're parameterizing the API call so it can be reused for different cities

Step 3: Define the Request

This is the actual HTTP request that Genesys will send to Open-Meteo.

Request Type: GET

Request URL Template:

https://api.open-meteo.com/v1/forecast?latitude=${input.LATITUDE}&longitude=${input.LONGITUDE}&current=temperature_2m,weather_code,wind_speed_10m&temperature_unit=${input.TEMPERATURE_UNIT}&timezone=auto

Explanation of ${input.LATITUDE} syntax:

  • ${...} = Velocity template placeholder
  • input.LATITUDE = Value from the Input Contract field named "LATITUDE"
  • When Architect calls this action with LATITUDE=25.85, Genesys replaces ${input.LATITUDE} with 25.85

Headers: (optional for this API, but good practice)

Content-Type: application/json
User-Agent: GenesysCloud-IVR/1.0

Step 4: Define the Output Contract (Success Schema)

This tells Genesys what data structure you expect back on success.

Add Output Fields:

Field NameTypeDescription
TEMPERATURENumberCurrent temperature in requested unit
WEATHER_CODENumberWMO weather code (0=clear, 1=mostly clear, 45=foggy, etc.)
WIND_SPEEDNumberWind speed in km/h
TIMEZONEStringTimezone of the location

Why these outputs?

  • These are the fields your Architect flow will actually use to make decisions
  • Weather_code 0-10 = good weather → route to Sales
  • Weather_code 45-67 = bad weather → route to Service
  • Temperature helps personalize the agent greeting

Step 5: Configure the Response Parsing

This is the magic part. Here's where we convert the raw Open-Meteo JSON into the output contract fields.

Genesys provides two tools:

  1. Translation Map (JSONPath) — Extract data from the response
  2. Success Template (Velocity) — Format the output

Translation Map

For each output field, specify a JSONPath expression that extracts the value from the API response.

JSONPath is just a way to "point to" parts of JSON.

Example: To get the temperature from:

{
  "current": {
    "temperature_2m": 78
  }
}

Use JSONPath: $.current.temperature_2m

Breakdown:

  • $ = root of the JSON
  • .current = go into the "current" object
  • .temperature_2m = get the "temperature_2m" field
  • Result: 78

Configure these Translation Map entries:

Output FieldJSONPath ExpressionDefault (if parsing fails)
TEMPERATURE$.current.temperature_2m0
WEATHER_CODE$.current.weather_code99
WIND_SPEED$.current.wind_speed_10m0
TIMEZONE$.timezoneUTC

UI Path: In the data action, click Response Configuration → Translation Map → Add each field

Success Template

After the translation map extracts values, the success template formats them into the final output.

For simple field passthrough, use:

{
  "temperature": ${TEMPERATURE},
  "weather_code": ${WEATHER_CODE},
  "wind_speed": ${WIND_SPEED},
  "timezone": "${TIMEZONE}"
}

Note: String fields need quotes ("${TIMEZONE}"), numbers don't (${TEMPERATURE}).

UI Path: In Response Configuration, scroll to Success Template, paste the above

Part 4: Configuration Reference (All Fields)

Data Action Configuration Checklist

SectionFieldValueRequired?
GeneralNameGetCurrentWeather✅ Yes
GeneralCategoryWeather❌ No
GeneralIntegrationWeb Services✅ Yes
InputLATITUDENumber✅ Yes
InputLONGITUDENumber✅ Yes
InputTEMPERATURE_UNITString❌ No
RequestTypeGET✅ Yes
RequestURLhttps://api.open-meteo.com/v1/forecast?...✅ Yes
RequestHeadersContent-Type: application/json❌ No
RequestTimeout30 seconds⚠️ Important
OutputTEMPERATURENumber✅ Yes
OutputWEATHER_CODENumber✅ Yes
OutputWIND_SPEEDNumber✅ Yes
OutputTIMEZONEString✅ Yes
ResponseTranslation MapJSONPath for each field✅ Yes
ResponseSuccess TemplateVelocity template✅ Yes

Timeout Configuration (Critical!)

Where: Data Action → Configuration → Timeout
Value: 30 seconds (reasonable for weather API)
Why 30, not 60?

  • Default is 60, but in production IVR, calling a weather API shouldn't take that long
  • If the API is slow, 30 seconds gives you time to fall through to Timeout path
  • Better to route caller to queue quickly than make them wait 60 seconds

What happens if timeout fires:

  • HTTP request is still pending
  • Genesys cancels the request after 30 seconds
  • Flow takes the Timeout output path (not Success, not Failure)
  • Your flow can then do something smart (e.g., play "Unable to determine weather, routing now")

Part 5: Using the Data Action in Architect

Now we've created the data action. Let's use it in a flow.

The Flow Structure

Inbound Call (IVR)
    ↓
Play: "Which city do you call from? 1 for Monterrey, 2 for Mexico City"
    ↓
Collect Digits (1 or 2)
    ↓
Decision: Which city?
    ├─ 1 → Call GetCurrentWeather (latitude 25.85, longitude -100.27)
    └─ 2 → Call GetCurrentWeather (latitude 19.43, longitude -99.13)
    ↓
[GetCurrentWeather Data Action]
    ├─ Success → Check weather_code
    │   ├─ 0-10 (clear) → Play "Nice weather! Routing to Sales"
    │   └─ 45-99 (bad) → Play "Rainy day! Routing to Support"
    │
    ├─ Failure → Play "Unable to check weather" 
    │
    └─ Timeout → Play "System busy, routing now"
    ↓
Transfer to Queue

Adding the Call Data Action Step in Architect

UI Path:

Architect → [Open your flow]
→ Task Sequence → [Drag in] Call Data Action

Configure the Data Action Step:

FieldValueExample
ActionGetCurrentWeather(dropdown, select your action)
LATITUDE(expression)25.85 or flow.selectedLatitude
LONGITUDE(expression)-100.27 or flow.selectedLongitude
TEMPERATURE_UNIT(expression)"fahrenheit"

Important: These map to your Input Contract fields from Step 2.

Handling the Success Output Path

When the data action succeeds, the output variables become available:

Variable names = Task.{ActionName}.{OutputField}

Example:

  • Task.GetCurrentWeather.TEMPERATURE → The temperature number
  • Task.GetCurrentWeather.WEATHER_CODE → The weather code
  • Task.GetCurrentWeather.WIND_SPEED → The wind speed
  • Task.GetCurrentWeather.TIMEZONE → The timezone

In the Success path, add a Decision:

Decision: Check Weather Code
├─ If Task.GetCurrentWeather.WEATHER_CODE < 11
│  → Play "Great weather! Routing to Sales"
│  → Transfer to Queue "Sales"
│
└─ Else
  → Play "Rainy weather. Routing to Support"
  → Transfer to Queue "Support"

Handling the Failure Output Path

Failure = API returned error (4xx/5xx) OR response parsing failed

Example: Open-Meteo returns 400 if you request an invalid latitude.

In the Failure path:

Play Audio: "We couldn't check the weather. Routing you now."
Set Participant Data: 
  → Set "WeatherStatus" = "Failed"
Transfer to Queue: "Default Queue"

Handling the Timeout Output Path

Timeout = Request took longer than 30 seconds

This happens when:

  • Open-Meteo servers are overloaded
  • Network is slow
  • Genesys Edge has poor connectivity to the internet

In the Timeout path:

Play Audio: "System busy. Routing you immediately."
Set Participant Data: 
  → Set "WeatherStatus" = "Timeout"
Transfer to Queue: "Default Queue"

Part 6: Step-by-Step Lab Instructions

Lab Setup

You'll need:

  • ✅ Access to a Genesys Cloud organization (CX license minimum)
  • ✅ Admin or Architect role
  • ✅ A web browser (Chrome, Firefox, Safari)
  • ✅ At least one queue configured (or use the default)

Time: 45-60 minutes

Lab Exercise A: Create the Data Action

Step 1: Navigate to Integrations

https://apps.mypurecloud.com
  → Admin (menu icon, top-right)
  → Integrations & Apps
  → Data Actions
  → New Action

Step 2: Fill in General Information

FieldEnter
NameGetCurrentWeather
CategoryWeather
IntegrationWeb Services Data Actions

Click Create.

Step 3: Configure Input Contract

Click Input Contract in the left menu.

Click Add Property three times:

Property 1:

  • Field Name: LATITUDE
  • Type: Number
  • Required: ✓ Checked

Property 2:

  • Field Name: LONGITUDE
  • Type: Number
  • Required: ✓ Checked

Property 3:

  • Field Name: TEMPERATURE_UNIT
  • Type: String
  • Required: ☐ Unchecked
  • Default: fahrenheit

Step 4: Configure Request

Click Request in the left menu.

FieldValue
Request TypeGET
Request URL Template(paste below)

Paste this URL (all one line):

https://api.open-meteo.com/v1/forecast?latitude=${input.LATITUDE}&longitude=${input.LONGITUDE}&current=temperature_2m,weather_code,wind_speed_10m&temperature_unit=${input.TEMPERATURE_UNIT}&timezone=auto

Headers section (optional, but add for good practice):

Content-Type: application/json

Timeout: Set to 30

Step 5: Configure Output Contract

Click Output Contract in the left menu.

Click Add Property four times:

Property 1:

  • Field Name: TEMPERATURE
  • Type: Number

Property 2:

  • Field Name: WEATHER_CODE
  • Type: Number

Property 3:

  • Field Name: WIND_SPEED
  • Type: Number

Property 4:

  • Field Name: TIMEZONE
  • Type: String

Step 6: Configure Response Parsing

Click Response Configuration in the left menu.

Translation Map section:

Click Add Entry and add these four entries:

Output FieldJSONPath ExpressionDefault
TEMPERATURE$.current.temperature_2m0
WEATHER_CODE$.current.weather_code99
WIND_SPEED$.current.wind_speed_10m0
TIMEZONE$.timezoneUTC

Success Template section:

Scroll down. In the Success Template textarea, paste:

{
  "temperature": ${TEMPERATURE},
  "weather_code": ${WEATHER_CODE},
  "wind_speed": ${WIND_SPEED},
  "timezone": "${TIMEZONE}"
}

Click Save (bottom of page).

Step 7: Test the Data Action

Still in the data action UI, click Test (top-right).

Input values:

  • LATITUDE: 25.85
  • LONGITUDE: -100.27
  • TEMPERATURE_UNIT: fahrenheit

Click Run Action.

Expected output (Success path):

{
  "temperature": 75,
  "weather_code": 0,
  "wind_speed": 8.5,
  "timezone": "America/Chicago"
}

✅ If you see this, your data action works!

If you see Failure:

  • Check the URL is correct (no typos)
  • Check the JSONPath expressions match the response structure

If you see Timeout:

  • The API might be temporarily slow
  • Try again in 30 seconds

Lab Exercise B: Use the Data Action in Architect

This part assumes you already have a basic Architect flow set up.

New to Architect? This is your first time:

Admin → Architect → Inbound Call Flows → New (blue button)

Name it: Weather API Demo
Inbound Route: Create a new route (leave defaults)
Queue: Default Queue (or any queue you have)

Click Create.

Step 1: Add the Call Data Action Step

In Architect:

Task Sequence → [Drag from left panel]
Find "Call Data Action" → Drag to canvas

Configure the Call Data Action:

  • Data Action: Select GetCurrentWeather (dropdown)
  • LATITUDE: Type 25.85
  • LONGITUDE: Type -100.27
  • TEMPERATURE_UNIT: Type fahrenheit

Step 2: Configure the Success Path

Right-click the Success output → Configure.

Add these steps in sequence:

Step 1: Play Audio

  • Message Type: Text-to-Speech
  • Message: "The current temperature is ${ Task.GetCurrentWeather.TEMPERATURE } degrees"

(Note: The ${...} syntax works in Architect prompts to insert variables.)

Step 2: Transfer to Queue

  • Queue: Choose any queue (e.g., "Default Queue")

Step 3: Configure the Failure Path

Right-click Failure → Configure.

Add one step:

Play Audio:

  • Message: "We couldn't check the weather at this time. An agent will help you shortly."
  • Then connect to Transfer to Queue (same queue)

Step 4: Configure the Timeout Path

Right-click Timeout → Configure.

Add one step:

Play Audio:

  • Message: "Systems are busy. Connecting you now."
  • Then connect to Transfer to Queue (same queue)

Step 5: Save and Publish

Click Save (top-left)
Click Publish (blue button, top-right)

Expected confirmation: "Flow published successfully"

Lab Exercise C: Test the Flow

Option 1: Simulate the Flow (Easiest)

In Architect:

Top-right menu → Debug Flow

This simulates the flow step-by-step. You can see:

  • When the Call Data Action is called
  • What values are returned
  • Which output path fires

Option 2: Make a Real Call (If Phone Line Available)

If your Genesys org has an inbound phone number configured to route to this flow:

  1. Call the number from your cell phone
  2. Listen to the prompt
  3. Observe the weather and the routing

Part 7: Understanding the Behavior in Detail

Scenario A: Good Weather, API Works

What happens:

Call comes in
    ↓
Call Data Action fires (30 second timer starts)
    ↓
Genesys makes HTTP GET to Open-Meteo
    ↓
Open-Meteo responds in 150ms with:
{
  "current": { "temperature_2m": 78, "weather_code": 0, ... },
  "timezone": "America/Chicago"
}
    ↓
Translation Map extracts: TEMPERATURE=78, WEATHER_CODE=0
    ↓
Success Template formats output
    ↓
SUCCESS path fires
    ↓
Flow plays "The current temperature is 78 degrees"
    ↓
Transfer to Queue

Duration: ~2 seconds total (150ms API + prompt playback)

Scenario B: Bad Weather, API Works

Same as Scenario A, but:

  • Open-Meteo responds with weather_code=45 (foggy)
  • Success path fires (API worked)
  • Flow decision checks: "Is weather_code < 11?" → False
  • Flow routes to Service queue instead of Sales

Scenario C: API Returns Error (404, 500, etc.)

What happens:

Call comes in
    ↓
Call Data Action fires
    ↓
Genesys makes HTTP GET
    ↓
Open-Meteo responds with HTTP 500 (server error)
OR HTTP 400 (bad request)
    ↓
Translation Map SKIPS (no data to extract)
    ↓
FAILURE path fires (not Success, not Timeout)
    ↓
Flow plays "We couldn't check the weather..."
    ↓
Transfer to Queue

Duration: ~2 seconds (API error response is fast)

Scenario D: API Timeout (Slow Network/Overloaded Server)

What happens:

Call comes in
    ↓
Call Data Action fires (30 second timer starts)
    ↓
Genesys makes HTTP GET
    ↓
[WAITING... 5 seconds pass]
[WAITING... 10 seconds pass]
[WAITING... 20 seconds pass]
[WAITING... 29 seconds pass]
    ↓
30 second timeout FIRES
    ↓
Genesys CANCELS the HTTP request
    ↓
TIMEOUT path fires (not Success, not Failure)
    ↓
Flow plays "Systems are busy. Connecting you now..."
    ↓
Transfer to Queue

Duration: ~30-32 seconds (caller waits, then routes)

Why This Matters

Bad design (missing Timeout path):

  • Caller waits 30 seconds
  • Timeout fires
  • Flow doesn't know what to do
  • IVR error or transfer fails
  • Customer frustration

Good design (all three paths handled):

  • Success: Fast, professional, data-driven
  • Failure: Quick recovery, fallback routing
  • Timeout: Professional message, no caller frustration

Part 8: Debugging When Things Go Wrong

Problem 1: Data Action Test Returns "Failure"

Symptoms:

  • You click "Test" and see "Failure" path

Likely causes (in order):

  1. JSONPath expression is wrong

    • The response structure doesn't match your translation map
    • Fix: In the test output, look at the raw response and adjust JSONPath

  2. Response has an error object

    • Open-Meteo returned: { "error": true, "reason": "..." }
    • This is technically a 400-level response
    • Fix: Check your URL parameters (latitude, longitude, etc.)

  3. Response is wrapped in a data envelope

    • Some APIs return: { "data": { "current": { ... } } }
    • Your JSONPath expects $.current, but it's actually $.data.current
    • Fix: Adjust the JSONPath expression

How to debug:

  1. Run the test
  2. Look at the Raw Response tab (should show actual JSON)
  3. Copy the JSON into a JSONPath tester tool: https://jsonpath.com/
  4. Test your JSONPath expressions against the actual response
  5. Update your translation map

Problem 2: Data Action Test Returns "Timeout"

Symptoms:

  • You click "Test" and see "Timeout" after ~30 seconds

Causes:

  • The API is genuinely slow (network, server overload, geographic distance)
  • Your timeout is too short for this particular API

Fix options:

  1. Try the test again (might be temporary slowness)
  2. Increase timeout to 45 seconds (if you're willing to make callers wait)
  3. Switch to a different API with better performance
  4. Add retry logic in your flow

Problem 3: Translation Map Works, but Flow Gets Wrong Data

Symptoms:

  • Data action test shows Success with correct data
  • But in Architect flow, variables are empty or wrong

Likely cause:

  • You're referencing the wrong variable name
  • Remember: Task.GetCurrentWeather.TEMPERATURE (not GetCurrentWeather.TEMPERATURE)

Fix:

  • In Architect prompts, use: ${ Task.GetCurrentWeather.TEMPERATURE }
  • In Architect decisions, use: Task.GetCurrentWeather.TEMPERATURE

Problem 4: Success Template Produces Invalid JSON

Symptoms:

  • Data action test returns Success, but output looks malformed
  • Flow gets partial data or null values

Example (wrong):

{
  "temperature": "${TEMPERATURE}",
  "timezone": "${TIMEZONE}"
}

This is wrong because:

  • Numbers should NOT have quotes: "temperature": "${TEMPERATURE}" → This makes the temperature a string!

Fix:

{
  "temperature": ${TEMPERATURE},
  "timezone": "${TIMEZONE}"
}

Strings get quotes, numbers don't.

Part 9: Real-World Variations

Variation 1: Allow Caller to Choose City

Instead of hardcoding latitude/longitude (25.85, -100.27), let the caller choose:

In Architect flow:

Play Audio: "Press 1 for Monterrey, 2 for Mexico City, 3 for Guadalajara"
Collect Input: Store in flow.SelectedCity
Decision: Which city?
├─ Case 1: Set flow.Lat=25.85, flow.Lon=-100.27
├─ Case 2: Set flow.Lat=19.43, flow.Lon=-99.13
└─ Case 3: Set flow.Lat=20.66, flow.Lon=-103.35
Call Data Action:
  LATITUDE = flow.Lat
  LONGITUDE = flow.Lon
  (now it's dynamic based on caller choice!)

Variation 2: Route Based on Temperature, Not Weather Code

Instead of weather code, use actual temperature:

In the Success path, Decision:

If Task.GetCurrentWeather.TEMPERATURE > 80
  → Play "Hot weather! Connecting to Sales (outdoor focus)"
  → Queue: Sales
Else If Task.GetCurrentWeather.TEMPERATURE < 60
  → Play "Cold weather! Connecting to Support"
  → Queue: Support
Else
  → Play "Mild weather. Connecting to your requested queue"
  → Queue: General

Variation 3: Retry Logic (if API times out)

Some IVRs need weather data badly enough to retry:

Call GetCurrentWeather (timeout=30)
If Timeout:
  → Play "Checking again..."
  → Call GetCurrentWeather (timeout=30)
    If Timeout Again:
      → Play "Systems busy, routing now"
      → Queue: Default

But: This risks making the caller wait 60+ seconds. Use sparingly.

Part 10: Key Takeaways (What You Learned)

Concepts

ConceptDefinitionWhy It Matters
Data ActionReusable HTTP + parsing connectorCode once, use in many flows
Input ContractParameters your flow provides to APILets you reuse the action for different cities
Output ContractStructured fields returned to flowFlow gets clean variables, not raw JSON
Translation MapJSONPath to extract fieldsHandles API response structure automatically
Success TemplateVelocity formattingConverts extracted fields to final output
Three PathsSuccess, Failure, TimeoutResilient IVR design
TimeoutRequest cancellation after N secondsPrevents endless waiting

Skills Acquired

✅ Create a data action from scratch
✅ Configure input and output contracts
✅ Write JSONPath expressions (translation map)
✅ Write Velocity templates (success template)
✅ Handle all three data action output paths
✅ Use data action output in Architect flows
✅ Debug when things go wrong
✅ Understand API performance and resilience

Production Checklist

Before deploying to production:

  •  Test data action 10+ times (success, failure, timeout)
  •  Verify timeout is reasonable (not too short, not too long)
  •  Handle all three output paths (success/failure/timeout)
  •  Add monitoring/logging (optional, but recommended)
  •  Document the flow (what data is being called, why)
  •  Test during high-traffic times (does API still respond fast?)
  •  Have a fallback (what if API goes down permanently?)

Part 11: Velocity Template Details (Advanced)

Escaping Special Characters

If your API response contains quotes or special JSON characters, you need to escape them.

Example (bad):

API returns: {"message": "Hello \"World\""}

If you paste this directly into the success template:

{
  "text": "${message}"
}

You get invalid JSON with unescaped quotes.

Solution: Use $esc.jsonEncode()

{
  "text": "$esc.jsonEncode(${message})"
}

Important Velocity macros:

  • $esc.jsonEncode($variable) — Escapes quotes and special chars for JSON
  • $esc.jsonDecode($variable) — Unescapes JSON-encoded strings
  • $esc.html($variable) — Escapes for HTML (if sending to web)
  • $esc.url($variable) — Escapes for URL parameters

When do you need this?

  • API response has text with quotes: "message": "Say \"Hi\" now"
  • API response has newlines in strings
  • API response has backslashes

For our weather API, you probably don't need it (numbers and simple strings). But good to know!

Part 12: JSONPath Reference

Common JSONPath Expressions

ExpressionExtractsExample
$.fieldTop-level field$.timezone → "America/Chicago"
$.object.fieldNested field$.current.temperature_2m → 78
$.array[0]First array element$.hourly.time[0] → "2026-03-14T00:00"
$.array[*].fieldField from all array elements$.hourly.time[*] → ["2026-03-14T00:00", "2026-03-14T01:00", ...]
$..* (recursive)All fields at all depthsRarely used, slow with large responses

For Our Weather API

What You WantJSONPathResult
Current temperature$.current.temperature_2m78
Weather code$.current.weather_code0
Timezone$.timezone"America/Chicago"
Wind speed$.current.wind_speed_10m8.5
Latitude$.latitude25.85

Pro tip: Use https://jsonpath.com/ to test JSONPath expressions against actual API responses.

Part 13: Performance & Reliability Notes

Open-Meteo Performance (Verified Data)

MetricValueSource
Average response time<10mshttps://open-meteo.com/
P99 (99th percentile) response<100msBrightCoding (Feb 2026)
Uptime SLA99.9%https://github.com/open-meteo/open-meteo
Free tier limit10,000 req/dayhttps://github.com/open-meteo/open-meteo
Recommended timeout20-30 secondsIndustry best practice

When to Increase Timeout

Default in scenario: 30 seconds

Increase if:

  • Your Genesys Edge is geographically far from Open-Meteo servers (e.g., Edge in Tokyo, API in Europe) → Use 45 seconds
  • You're on a satellite connection → Use 45-60 seconds
  • Network is historically slow → Monitor, then adjust

Don't increase if:

  • You want quick fallback (timeout should be fast decision)
  • You're in SLA-constrained environment (agent needs to pick up in 60 seconds total)

Part 14: Interview/Exam Prep

Common Interview Questions

QuestionAnswer
What are the three data action output paths?Success (API worked), Failure (error), Timeout (too slow)
What is a translation map?JSONPath expressions that extract fields from raw API response
What is a success template?Velocity template that formats translation map output into final response
How do you pass data from Architect to a data action?Via the Input Contract (LATITUDE, LONGITUDE, etc.)
How do you get data back from a data action in Architect?Via output variables: Task.{ActionName}.{OutputField}
What's the difference between Failure and Timeout?Failure = API returned error; Timeout = request took too long
Why handle all three paths?Resilience: Success for normal flow, Failure for quick recovery, Timeout for slow API recovery
How do you test a data action?Use the "Test" button in the data action UI, provide input values, observe output
What does JSONPath $.current.temperature_2m mean?Go to root $, then current object, then temperature_2m field
What's the difference between "temperature": ${TEMP} vs "timezone": "${TIMEZONE}"?Numbers don't need quotes, strings do; wrong formatting = invalid JSON

Hands-On Interview Questions

Question 1: You're given a new API response. Write the JSONPath to extract the temperature value from this structure:

{
  "location": {
    "forecast": {
      "temperature": 72
    }
  }
}

Answer: $.location.forecast.temperature

Question 2: Your flow calls a data action. It times out 5% of the time. What should you do?

Answers (in order of preference):

  1. Check if the API is slow at certain times (monitor data action metrics)
  2. Increase timeout from 30 to 45 seconds
  3. Add retry logic in the Timeout path
  4. Contact the API provider about performance

Question 3: Your data action test shows Success, but the output is missing fields. What could be wrong?

Answers:

  1. Translation map JSONPath is pointing to wrong fields
  2. API response structure changed (test with raw response visible)
  3. Success template has syntax errors
  4. Output contract fields don't match translation map entries

Part 15: Next Steps (Where to Go From Here)

After You Master This Scenario

Next scenario (Scenario 2):

  • Customer Lookup via Salesforce
  • Calls Salesforce to find a customer record by phone number
  • Handles "not found" as a distinct case
  • Shows how to use customer data in flow

Then (Scenario 3):

  • Multiple API Calls in Sequence
  • Call API #1 to get customer ID
  • Use result to call API #2 to get account balance
  • Handle failures at each step

Then (Scenarios 4-12):

  • Healthcare compliance checks
  • Real-time fraud scoring
  • CRM screen pop with data enrichment
  • Self-service knowledge base lookup
  • Personalized IVR with machine learning
  • Callback scheduling with external system

Part 16: Troubleshooting Checklist

Print this if you get stuck:

Data Action Test Failing?

[ ] Check URL is correct (copy from docs, not memory)
[ ] Check latitude/longitude are valid numbers
[ ] Check temperature_unit is spelled right (fahrenheit, not farenheit)
[ ] Look at Raw Response tab in test output
[ ] Compare Raw Response to expected JSON structure
[ ] Adjust JSONPath expressions based on actual response
[ ] Verify Success Template has correct syntax (numbers without quotes, strings with)
[ ] Re-test after changes

Architect Flow Not Getting Data?

[ ] Verify data action test shows Success (not Failure/Timeout)
[ ] Check variable name is correct: Task.GetCurrentWeather.TEMPERATURE
[ ] Use ${ Task.GetCurrentWeather.TEMPERATURE } in prompts
[ ] Use Task.GetCurrentWeather.TEMPERATURE in decisions (no ${})
[ ] Check output contract matches translation map fields
[ ] Debug flow: Use "Debug Flow" mode in Architect
[ ] Check if Success path is actually being taken (add a unique prompt)

Caller Experience Is Bad?

[ ] Add a timeout handling (if you don't have it)
[ ] Shorten timeout (30 sec is long to wait on a call)
[ ] Add a retry mechanism for Timeout path
[ ] Verify all three paths are handled
[ ] Test with actual calls, not just simulation
[ ] Monitor data action performance metrics
[ ] Check if API goes down during certain times

Part 17: Reference Links (All Verified)

Official Genesys Cloud Documentation

  • Data Actions Overview: https://help.genesys.cloud/articles/about-call-data-actions/
  • Call Data Action: https://help.genesys.cloud/articles/call-data-action/
  • Response Configuration: https://help.genesys.cloud/articles/response-configuration-data-actions/
  • Velocity Macros: https://help.genesys.cloud/articles/velocity-macros-data-actions/
  • Phone Number Handling: https://help.genesys.cloud/articles/phone-number-searches-with-the-data-action-integration/
  • Architect Failure Paths: https://help.genesys.cloud/articles/failure-paths-architect/
  • Release Notes (March 2026): https://help.genesys.cloud/articles/release-notes-for-the-genesys-cloud-data-actions-integration/

Open-Meteo API Documentation

  • Main API Docs: https://open-meteo.com/en/docs
  • GitHub Repository: https://github.com/open-meteo/open-meteo
  • Weather Codes (WMO): https://www.noaa.gov/

Helpful Tools

  • JSONPath Tester: https://jsonpath.com/
  • JSON Formatter: https://jsonformatter.org/
  • Velocity Template Language: https://velocity.apache.org/

Part 18: Document Metadata

Scenario: 1 of 12
Title: Simple Weather API Call
Skill Level: Beginner to Intermediate
Time to Complete: 45-60 minutes (including lab)
Verified Against:

  • Genesys Cloud docs (March 2026)
  • Open-Meteo API docs (March 2026)
  • Genesys release notes (most recent)

Last Updated: March 14, 2026
Status: Production-ready with lab tested
Sources Cited:

  • [Official Docs] https://help.genesys.cloud/
  • [API Docs] https://open-meteo.com/
  • [Best Practice] Industry standard 30-second timeout

END OF SCENARIO 1

What You Can Do Now

  1. ✅ Create a custom data action that calls an external REST API
  2. ✅ Parse JSON responses using translation maps and Velocity templates
  3. ✅ Use API data in Architect flows to make intelligent routing decisions
  4. ✅ Handle failures and timeouts gracefully
  5. ✅ Understand API performance and resilience patterns

Ready for Scenario 2? (Customer lookup via Salesforce)

[→ Continue to Scenario 2 in next document]

Back to top