Overview

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:

Node outputs - Data produced by previous nodes in your flow
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

Node Data
Trigger Data
Combined Usage

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.

Access data provided when the flow starts using the special trigger keyword:

$.trigger.property

Example:

{
  "webhookOrderId": "$.trigger.order_id",
  "webhookEvent": "$.trigger.event_type",
  "webhookTimestamp": "$.trigger.timestamp"
}

Trigger data is available to all nodes in the flow from the very first node.

Combine trigger data with node outputs for powerful workflows:

{
  "summary": {
    "eventType": "$.trigger.event",
    "userId": "$.trigger.user_id",
    "userDetails": "$.fetch_user.details",
    "processedAt": "$.process_data.timestamp",
    "message": "Event |$.trigger.event| processed for user |$.fetch_user.name|"
  }
}

This pattern is common in webhook-driven workflows.

Quick Reference

Basic Syntax

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

Array Operations

$.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

Filters & Queries

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

String Building

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

Flow Starts

Trigger data becomes available immediately via $.trigger.*

First Node Executes

Can access trigger data but not other node data yet

Subsequent Nodes Execute

Each node can access:

Trigger data ($.trigger.*)
All previous node outputs ($.node_id.*)

Data Transforms

JSONPath expressions extract and transform data as needed

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": "alice@example.com",
    "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

Webhook to Email
Data Enrichment
Conditional Routing

{
  "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!"
}

{
  "enrichedData": {
    "rawEvent": "$.trigger",
    "userProfile": "$.fetch_user",
    "accountDetails": "$.fetch_account",
    "computedScore": "$.calculate_score.value",
    "timestamp": "$.trigger.timestamp"
  }
}

Conditional logic in JSONPath works through filter expressions. Use filters to select data based on conditions:

{
  "highPriorityItems": "$.trigger.items[?(@.priority==='high' || @.priority==='urgent')]",
  "premiumCustomers": "$.customers[?(@.tier==='premium')]",
  "largeOrders": "$.orders[?(@.amount>1000)]",
  "activeVerifiedUsers": "$.users[?(@.active===true && @.verified===true)]"
}

For routing decisions, check conditions and use the results in your flow logic:

{
  "isPremiumCustomer": "$.fetch_customer[?(@.tier==='premium')]",
  "isHighPriority": "$.trigger[?(@.priority==='high')]",
  "requiresEscalation": "$.trigger[?(@.amount>1000)]"
}

These filter results return arrays:

Empty array [] means condition is false
Array with data [{...}] means condition is true

Use these results in subsequent nodes to make routing decisions.

Getting Started Checklist

Understand Data Sources

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

Master Basic Syntax

Practice accessing properties using $.NODE_ID.property pattern

Work with Arrays

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

Try the Pipe Operator

Build dynamic strings using QuivaWorks’ custom | concatenation

Learn Filters

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

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.

Get Started

Assistants

Flows

Account Management

Advanced

What is Variable Mapping?

Data Sources

Quick Reference

How Variable Mapping Works

Example Flow Data Structure

When to Use Variable Mapping

Webhook Processing

API Integration

Data Transformation

Dynamic Content

Conditional Logic

Data Aggregation

Common Use Cases

Getting Started Checklist

Documentation Structure

Basic Syntax

JSONPath Features

Pipe Operator

Filters & Expressions

Advanced Techniques

Examples

Reference

Next Steps

Learn Basic Syntax

View Examples

Quick Reference

Flow Builder

Get Started

Assistants

Flows

Account Management

Advanced

Documentation Index

​What is Variable Mapping?

​Data Sources

​Quick Reference

​How Variable Mapping Works

​Example Flow Data Structure

​When to Use Variable Mapping

Webhook Processing

API Integration

Data Transformation

Dynamic Content

Conditional Logic

Data Aggregation

​Common Use Cases

​Getting Started Checklist

​Documentation Structure

Basic Syntax

JSONPath Features

Pipe Operator

Filters & Expressions

Advanced Techniques

Examples

Reference

​Next Steps

Learn Basic Syntax

View Examples

Quick Reference

Flow Builder

What is Variable Mapping?

Data Sources

Quick Reference

How Variable Mapping Works

Example Flow Data Structure

When to Use Variable Mapping

Common Use Cases

Getting Started Checklist

Documentation Structure

Next Steps