Skip to main content
Variable mapping allows you to dynamically reference and transform data as it flows between nodes in your workflow. Instead of hardcoding values, you can pull data from previous nodes, triggers, and apply transformations on the fly.

​
What is Variable Mapping?

When building flows in QuivaWorks, you work with two primary data sources:
  1. Node outputs - Data produced by previous nodes in your flow
  2. Trigger data - Data provided when the flow is initiated
Variable mapping lets you:
  • Reference data from any previous node or the flow trigger
  • Transform data using powerful JSONPath expressions
  • Combine data from multiple sources
  • Build dynamic strings with the pipe operator
  • Filter and query complex data structures
{
  "email": "$.fetch_customer.email",
  "name": "$.fetch_customer.firstName| |$.fetch_customer.lastName"
}
Variable mapping is powered by JSONPath Plus v1.1.0 with custom QuivaWorks extensions for enhanced functionality.

​
Data Sources

Access output from any previous node in your flow using the node’s unique ID:
$.NODE_ID.property
Example:
{
  "customerEmail": "$.fetch_customer.email",
  "orderTotal": "$.calculate_total.amount"
}
Nodes execute sequentially, so you can only reference nodes that have already executed.

​
Quick Reference

$.NODE_ID.property              # Access node data
$.trigger.property              # Access trigger data
$.NODE_ID.nested.deep.value     # Nested properties

$.NODE_ID.items[0]              # First item (0-based)
$.NODE_ID.items[-1]             # Last item
$.NODE_ID.items[*]              # All items
$.NODE_ID.items[0:3]            # First 3 items

$.items[?(@.price>10)]          # Filter by condition
$..email                        # Recursive search
$.items[?(@.active===true)]     # Equality check

text|$.NODE.value               # Concatenate static text with values
$.first| |$.last                # Join values with separator
$.NODE.value|                   # Force string conversion
Trailing pipe behavior:
  • Missing data: Returns "" (empty string)
  • Arrays: Returns comma-separated string (e.g., "a,b,c")
  • Objects: Returns "[object Object]"
  • Primitives: Returns value as-is
Key Points to Remember:
  • Arrays are 0-based: [0] is first, [-1] is last
  • Use === for equality in filters, not =
  • Everything is case-sensitive
  • QuivaWorks auto-detects $. anywhere in your mapping

​
How Variable Mapping Works

1

Flow Starts

Trigger data becomes available immediately via $.trigger.*
2

First Node Executes

Can access trigger data but not other node data yet
3

Subsequent Nodes Execute

Each node can access:
  • Trigger data ($.trigger.*)
  • All previous node outputs ($.node_id.*)
4

Data Transforms

JSONPath expressions extract and transform data as needed
5

Flow Completes

Final node has access to all trigger and node data

​
Example Flow Data Structure

{
  "trigger": {
    "event": "order.created",
    "order_id": "ORD-12345",
    "user_id": "USR-789"
  },
  "fetch_customer": {
    "id": "USR-789",
    "name": "Alice Smith",
    "email": "[email protected]",
    "tier": "premium"
  },
  "fetch_order": {
    "id": "ORD-12345",
    "total": 299.99,
    "items": [
      {"product": "Widget", "price": 149.99},
      {"product": "Gadget", "price": 150.00}
    ]
  },
  "calculate_discount": {
    "amount": 29.99,
    "percentage": 10
  }
}
Access this data: 
{
  "triggerEvent": "$.trigger.event",
  "customerName": "$.fetch_customer.name",
  "orderTotal": "$.fetch_order.total",
  "firstProduct": "$.fetch_order.items[0].product",
  "finalAmount": "$.fetch_order.total",
  "discountApplied": "$.calculate_discount.amount"
}

​
When to Use Variable Mapping

Webhook Processing

Access incoming webhook data via $.trigger and enrich with additional API calls

API Integration

Map responses from external APIs to your flow data structure

Data Transformation

Convert data formats between different systems and services

Dynamic Content

Create personalized messages, emails, and notifications

Conditional Logic

Route data based on conditions and business rules

Data Aggregation

Combine data from multiple sources into unified structures

​
Common Use Cases

{
  "to": "$.fetch_customer.email",
  "subject": "Order Confirmation #|$.trigger.order_id|",
  "body": "Hi |$.fetch_customer.firstName|, your order for |$.fetch_order.items.length| items totaling $|$.fetch_order.total| has been confirmed!"
}

​
Getting Started Checklist

1

Understand Data Sources

Learn the difference between $.trigger (flow input) and $.node_id (node outputs)
2

Master Basic Syntax

Practice accessing properties using $.NODE_ID.property pattern
3

Work with Arrays

Get comfortable with array indexing [0], slicing [0:3], and wildcards [*]
4

Try the Pipe Operator

Build dynamic strings using QuivaWorks’ custom | concatenation
5

Learn Filters

Filter data with conditions like [?(@.price>10)]
6

Test in Debugger

Use the Flow Debugger to test your mappings with real data

​
Documentation Structure

This comprehensive guide is organized into focused sections:

Basic Syntax

Core concepts, trigger data, and simple examples

JSONPath Features

Standard JSONPath capabilities and operators

Pipe Operator

QuivaWorks’ string concatenation and fallbacks

Filters & Expressions

Query, filter, and select data

Advanced Techniques

Power user features and optimization

Examples

Real-world use cases and patterns

Reference

Syntax tables and troubleshooting
New to Variable Mapping? Start with Basic Syntax to learn the fundamentals.Need a quick answer? Jump to the Reference for syntax tables and troubleshooting.Want to see it in action? Check out Examples for real-world patterns.

​
Next Steps

Learn Basic Syntax

Start with the fundamentals of variable mapping

View Examples

See real-world variable mapping patterns

Quick Reference

Syntax tables and troubleshooting guide

Flow Builder

Learn how to build flows with multiple nodes
Need help? Visit our Help Center or join the Community for support.