Formula Authoring Guide

Assume your StartNode defines two inputs: quantity and unit_price.

# These come from your StartNode inputs
quantity = 5
unit_price = 29.99

In a CalculateNode, multiply quantity by price:

subtotal = quantity * unit_price

Result: subtotal = 149.95

Use IF() to apply 10% discount for orders over $100:

discount_rate = IF(subtotal > 100, 0.10, 0)
discount = subtotal * discount_rate
total = subtotal - discount

Result: discount = 14.995, total = 134.955

All assigned variables are automatically available to the next node. No export needed!

subtotal = quantity * unit_price
discount_rate = IF(subtotal > 100, 0.10, 0)
discount = subtotal * discount_rate
total = subtotal - discount

# All four variables (subtotal, discount_rate, discount, total)
# are automatically available in the next node

Syntax

variable_name = expression

Examples

total = price * quantity
tax = total * 0.19
grand_total = total + tax

max_price = MAX(price_a, price_b, price_c)
rounded = ROUND(total, 2)
absolute = ABS(difference)

discount = IF(is_member, 0.15, 0.05)
status = IF(quantity > 0, "in_stock", "out_of_stock")

message = "Order confirmed"
error_code = 'ERR_NOT_FOUND'

Available Operators

How Variables Flow

subtotal = quantity * price
tax = subtotal * 0.19
total = subtotal + tax
# All three (subtotal, tax, total) are available downstream

_temp = quantity * price
_adjusted = _temp * 0.95
total = _adjusted + fees

export total
# Only 'total' is available downstream

base = hours * rate
overtime = MAX(hours - 40, 0) * rate * 0.5
gross_pay = base + overtime

return gross_pay

Logical Operators

Condition Examples

# Numeric comparison
quantity > 10

# String comparison
status == "active"

# Not equal
country != "US"

# Both must be true
total > 100 AND customer_type == "premium"

# Either can be true
is_sale OR has_coupon

# Complex logic with parentheses
(age >= 18 AND age <= 65) OR has_guardian_consent

# Free shipping eligibility
(subtotal >= 50 AND region == "domestic") OR is_prime_member

# Discount qualification
(order_count > 5 OR total_spent > 500) AND NOT is_first_order

# Business hours check
hour >= 9 AND hour < 17 AND day != "Sunday"

Where Variables Come From

# From API call: { "quantity": 5, "price": 29.99 }
total = quantity * price

# StartNode defines: tax_rate with default 0.19
tax = subtotal * tax_rate  # uses 0.19 if not provided

# Flow metadata: { "version": "2.0", "region": "EU" }
shipping = IF(region == "EU", 5.99, 9.99)

# Previous node calculated 'subtotal' and 'discount'
final = subtotal - discount

Understanding Scope

# Node A
temp = price * 1.1
result = temp + fees

# Node B (downstream) - can use BOTH variables
x = result              # ✓ works
y = temp                # ✓ works - all variables available!

# Flow: StartNode → NodeA → NodeB → EndNode

# NodeA can use:
#   - Runtime inputs
#   - StartNode defaults
#   - Flow metadata

# NodeB can use:
#   - Everything NodeA can use
#   - Plus: all variables from NodeA

Accessing Nested Data

Use dot notation to access nested object properties:

# Given input: { "order": { "total": 150, "items": [...] } }

amount = order.total
tax = order.total * 0.19

# Works with deeper nesting too
city = customer.address.city

Adds up all numeric values. Non-numeric values are ignored.

# With multiple arguments
total = SUM(10, 20, 30)                    # → 60

# With an array
total = SUM(prices)                        # → sum of all prices

# With projection (array of objects)
total = SUM(items[*].price)                # → sum of all item prices

# Mixed types (strings converted if numeric-looking)
total = SUM(["5", 2, "3.5"])               # → 10.5

# Empty array
total = SUM([])                            # → 0

Counts non-nil values. Zeros and empty strings are counted; nil/null values are not.

# Count array elements
num_items = COUNT(items)                   # → number of items

# Count with projection
num_prices = COUNT(items[*].price)         # → count of price values

# Nil values excluded
count = COUNT([1, nil, 3, 0])              # → 3 (nil excluded, 0 counts)

# Multiple arguments
count = COUNT(a, b, c)                     # → counts non-nil args

Find the minimum or maximum numeric value. Returns nil if no numeric values found.

# Find extremes
lowest = MIN(prices)                       # → smallest price
highest = MAX(prices)                      # → largest price

# With projection
min_price = MIN(items[*].price)            # → cheapest item
max_price = MAX(items[*].price)            # → most expensive item

# Multiple arguments
biggest = MAX(a, b, c)                     # → largest of a, b, c

# Numeric string conversion
smallest = MIN(["5", 2, "3.5"])            # → 2

# Empty array
result = MIN([])                           # → nil

Calculates the arithmetic mean of numeric values. Returns nil if no numeric values found.

# Average of array
avg_price = AVERAGE(prices)                # → mean of all prices
avg_price = AVG(prices)                    # → same (alias)

# With projection
avg_score = AVERAGE(reviews[*].rating)     # → average rating

# Multiple arguments
mean = AVERAGE(10, 20, 30)                 # → 20

# Empty array
result = AVERAGE([])                       # → nil

Get the first or last element of an array. Returns nil for empty arrays.

# Get first/last element
first_item = FIRST(items)                  # → first element
last_item = LAST(items)                    # → last element

# With projection
first_price = FIRST(items[*].price)        # → price of first item
last_name = LAST(users[*].name)            # → name of last user

# Single element (scalar) auto-wrapped
result = FIRST(42)                         # → 42

# Empty array
result = FIRST([])                         # → nil

Get the first N elements from an array. Useful for limiting results.

# Get first N elements
top_three = TAKE(items, 3)                 # → first 3 items

# With projection
top_prices = TAKE(items[*].price, 5)       # → first 5 prices

# Negative or zero returns empty
result = TAKE(items, 0)                    # → []
result = TAKE(items, -2)                   # → []

# More than available returns all
result = TAKE([1, 2, 3], 10)               # → [1, 2, 3]

Remove duplicate values from an array. Preserves order (keeps first occurrence).

# Remove duplicates
unique = DISTINCT([1, 2, 2, 3, 1])         # → [1, 2, 3]

# With strings
unique_names = DISTINCT(["a", "b", "a"])   # → ["a", "b"]

# With projection - unique categories
categories = DISTINCT(products[*].category)

# Count unique values
unique_count = COUNT(DISTINCT(items[*].type))

Transform each element using an expression. Use item to reference the current element.

# Double each value
doubled = MAP([1, 2, 3], "item * 2")       # → [2, 4, 6]

# Apply discount to prices
discounted = MAP(prices, "item * 0.9")    # → 10% off each

# Access object fields via 'item' or directly
totals = MAP(items, "item.price * item.quantity")
totals = MAP(items, "price * quantity")   # same result

# Calculate line totals with tax
with_tax = MAP(items, "price * quantity * 1.19")

Keep only elements where the predicate is true. Use item to reference each element.

# Keep values over 10
large = FILTER([5, 15, 8, 20], "item > 10")    # → [15, 20]

# Filter by object property
expensive = FILTER(items, "price > 50")

# Filter by category
electronics = FILTER(products, "category == 'electronics'")

# Multiple conditions
premium = FILTER(items, "price > 100 AND in_stock")

# Combine with aggregation
expensive_total = SUM(FILTER(items, "price > 50")[*].price)

Accumulate values with custom logic. Use acc (or accumulator) for the running total and item for each element.

# Sum (same as SUM function)
total = REDUCE([1, 2, 3], 0, "acc + item")     # → 6

# Product of all values
product = REDUCE([2, 3, 4], 1, "acc * item")   # → 24

# Find running maximum
max_val = REDUCE(values, 0, "IF(item > acc, item, acc)")

# Sum with weighted values
weighted = REDUCE(items, 0, "acc + (price * weight)")

Sum values where a condition is true. Optionally project a field to sum.

# Sum prices of expensive items
expensive_total = SUMIF(items, "price > 50", "price")

# Sum values directly (no projection needed for simple arrays)
positive_sum = SUMIF([5, -3, 10, -2], "item > 0")  # → 15

# Sum by category
electronics_total = SUMIF(products, "category == 'electronics'", "price")

# Sum with compound condition
premium_sales = SUMIF(orders, "total > 100 AND status == 'completed'", "total")

# Real-world: Sum line totals for taxable items
taxable_amount = SUMIF(line_items, "is_taxable", "price * quantity")

Count elements where a condition is true.

# Count expensive items
expensive_count = COUNTIF(items, "price > 50")

# Count positive values
positive_count = COUNTIF([5, -3, 10, -2], "item > 0")  # → 2

# Count by status
active_users = COUNTIF(users, "status == 'active'")
pending_orders = COUNTIF(orders, "status == 'pending'")

# Count with compound condition
vip_count = COUNTIF(customers, "total_spent > 1000 AND is_subscribed")

# Check if any match (count > 0)
has_errors = COUNTIF(items, "has_error") > 0

Common Mistakes

# In a ConditionNode - WRONG
status = "active"

# Correct
status == "active"

# 'discount_rate' was never defined - WRONG
final = subtotal * (1 - discount_rate)

# Correct: define it first or pass as input
discount_rate = 0.1
final = subtotal * (1 - discount_rate)

# Trying to export a variable that doesn't exist - WRONG
total = price * quantity
export total, discount  # ERROR: 'discount' was never defined

# Fix: only export variables you've defined
discount = IF(quantity > 10, 0.1, 0)
total = price * quantity * (1 - discount)
export total, discount  # ✓ both variables exist

# Input is 'userId' but you reference 'userid' - WRONG
result = userid * 2   # Unknown: userid

# Correct: match exact case
result = userId * 2

1 Use Clear, Descriptive Names

order_subtotal = quantity * unit_price
shipping_cost = IF(order_subtotal > 50, 0, 5.99)
tax_amount = order_subtotal * tax_rate

x = q * p
s = IF(x > 50, 0, 5.99)
t = x * r

2 Keep Formulas Focused

Each CalculateNode should do one thing well. Split complex logic across multiple nodes.

# Node 1: Calculate subtotal
subtotal = quantity * unit_price
# subtotal flows automatically to next node

# Node 2: Apply discounts
discount = IF(subtotal > 100, 0.1, 0)
discounted = subtotal * (1 - discount)
# discount, discounted flow automatically

# Node 3: Add tax and shipping
tax = discounted * 0.19
shipping = IF(discounted > 50, 0, 5.99)
total = discounted + tax + shipping

subtotal = quantity * unit_price
discount = IF(subtotal > 100, 0.1, 0)
discounted = subtotal * (1 - discount)
tax = discounted * 0.19
shipping = IF(discounted > 50, 0, 5.99)
total = discounted + tax + shipping
# All 6 variables flow downstream automatically

3 Use Export to Limit Variables

By default, all assigned variables flow downstream. Use export only when you want to limit which variables are passed.

# Without export: gross, tax, and net ALL flow downstream
gross = hours * rate
tax = gross * 0.25
net = gross - tax

# With export: ONLY net flows downstream (hides internals)
export net

4 Document Business Logic

Use comments to explain the "why", especially for business rules that aren't obvious.

# Loyalty discount: 15% for customers with 5+ orders
# As per marketing policy Q4-2025
loyalty_discount = IF(order_count >= 5, 0.15, 0)

# Free shipping threshold is $50 domestic, $100 international
free_shipping_threshold = IF(is_domestic, 50, 100)
shipping = IF(subtotal >= free_shipping_threshold, 0, base_shipping)

5 Prefix Internal Variables

Use underscore prefix as a convention to indicate internal/temporary calculations. Combine with export to hide them from downstream nodes.

# Internal calculations (prefixed with _ by convention)
_base_score = points / max_points * 100
_with_bonus = _base_score + bonus_points
_capped = MIN(_with_bonus, 100)

# Final result (no prefix - the main output)
final_score = ROUND(_capped, 0)

# Use export to only pass final_score downstream
export final_score

Q: Do I need to use export?

A: No! By default, all assigned variables automatically flow to downstream nodes. Only use export or return if you want to limit which variables are passed.

Q: Are variable names case-sensitive?

A: Yes. total, Total, and TOTAL are three different variables. Stick to snake_case for consistency.

Q: Can I export a variable I didn't assign?

A: No. Exporting an unknown variable will cause an error. You can only export variables that exist in scope (defined in the current node or available from upstream).

Q: Are there built-in default variables like price or metadata?

A: No. There are no magic default variables. All variables come from:

• Runtime parameters (API inputs)
• StartNode defaults
• Flow metadata
• Exported from upstream nodes

Q: What happens if I divide by zero?

A: Division by zero will cause an execution error. Protect against it with a condition:

result = IF(divisor != 0, value / divisor, 0)

Q: How do I handle null/nil values?

A: Use conditional logic or provide defaults:

# Using IF to provide default
safe_value = IF(value, value, 0)

# Or use StartNode defaults for inputs

Q: Can I call one flow from another?

A: Yes, using MapNodes. A MapNode can execute a sub-flow for each element in an array. This is useful for processing collections with complex logic.

Q: Why does my function show "unknown variable" warning?

A: Check these common issues:

• Spelling: SUM not Sum or sum
• Parentheses: SUM(items) not SUM items
• Recognized functions: see the Functions sections for the complete list

Q: How do I pass arrays from the API?

A: Pass arrays directly in your JSON input:

{
  "inputs": {
    "items": [
      { "name": "Widget", "price": 10 },
      { "name": "Gadget", "price": 25 }
    ]
  }
}

Then use projection: SUM(items[*].price)

Q: Is the formula language Turing-complete?

A: No, intentionally. Formulas are designed for safe, predictable calculations. There are no loops or recursion to prevent infinite execution. Use multiple nodes for complex logic.