Look Up Value
Overview
Look Up Value performs data mapping by searching for an input value in a lookup table and returning the corresponding output value. Use this stage for data transformation, categorization, and value mapping in flows.
When the input value matches a key in the lookup table, the corresponding value is returned. If no match is found, the default value is used instead.
* Example flow demonstrating how Look Up Value maps a deposit status to a corresponding value and makes the result available for use in the next stage.
Note: The variable names, values, criteria, and configuration used in this example are for demonstration purposes only.
Where to find it: Actions > Transformers in the stage library.
Configuration
Required Fields
| Field | Description | Example |
|---|---|---|
| Input variable | The value to look up in the lookup table | {{status}}, {{productCode}} |
| Default if not found | Value returned if no matching key found | Unknown, ={{defaultValue}} |
| Output value | Variable name to store the result | statusDescription, category |
| Lookup Table | Key-value pairs mapping inputs to outputs | 1 → Pending, 2 → Processing |
Using functions in these fields: Any value field above accepts @ functions, for example @NowSecond for the current time or @calc(...) for a calculation.
See Flows Functions for the full list.
Exit Points
| Exit | When | Output Variable |
|---|---|---|
| Pass | Input key matches a key in lookup table | Contains matched value (or evaluated expression) |
| Fail | Input key does NOT match any key in lookup table | Contains default value |
How It Works
When executed, the stage:
- Resolves input value - Evaluates the input variable from flow
- Searches lookup table - Compares input against each key (case-sensitive, exact match)
- Returns matched value - If match found, returns corresponding value (evaluates expressions starting with =)
- Uses default if not found - If no match, returns default value
- Routes to appropriate exit - Pass if matched, Fail if using default
Lookup Table Structure
| Key (Input to Match) | Value (Output to Return) | Supports |
|---|---|---|
| Exact match string | Static value or expression | Text, numbers, codes |
| Case-sensitive | Expressions starting with = | Math calculations |
Common Use Cases
1. Order Status Mapping
Map numeric status codes to user-friendly descriptions.
Configuration:
- Input variable:
{{orderStatus}} - Default:
Unknown Status - Output value:
statusDescription - Lookup Table:
1→Pending2→Processing3→Shipped4→Delivered5→Returned
Result:
- If
{{orderStatus}}= "2" → Pass exit,{{statusDescription}}= "Processing" - If
{{orderStatus}}= "99" → Fail exit,{{statusDescription}}= "Unknown Status"
2. Product Category Lookup
Map product IDs to category names.
Configuration:
- Input variable:
{{product.id}} - Default:
Uncategorized - Output value:
category - Lookup Table:
PROD001→ElectronicsPROD002→ClothingPROD003→FoodPROD004→Books
3. Region to Tax Rate Lookup
Map regions to tax rates using mathematical expressions.
Configuration:
- Input variable:
{{shippingRegion}} - Default:
0.07 - Output value:
taxRate - Lookup Table:
CA→=0.0725TX→=0.0625NY→=0.08FL→=0
Then use in calculation: {{orderTotal}} * {{taxRate}}
4. Currency Code to Symbol
Convert currency codes to display symbols.
Lookup Table:
USD→$EUR→€GBP→£JPY→¥
Expression Support
A matched value starting with = is evaluated as a math expression (arithmetic and math functions, no conditional logic). This applies to the values in the lookup table only. the default value is returned as-is and is not evaluated, so keep it a plain value.
| Value | Interpretation | Result |
|---|---|---|
=0.0725 | Math expression | "0.0725" (string) |
=10 + 5 | Math expression | "15" (string) |
Text Value | Static text | "Text Value" (string) |
Key Behaviors
| Feature | Behavior |
|---|---|
| Case Sensitivity | "CA" and "ca" are different keys (exact match required) |
| Exit Routing | ✓ Pass = Match found, Fail = Default used |
| Expression Evaluation | ✓ Values starting with = evaluated as math expressions |
| Default Value | ✓ Always returns a value (match or default) |
| First Match | ✓ Stops at first matching key (order matters if duplicates exist) |
Best Practices
- ✓ Use meaningful default values that indicate "not found" clearly
- ✓ Keep keys consistent in format (all uppercase or all lowercase)
- ✓ Use Pass/Fail exits to handle matched vs unmatched cases differently
- ✓ Test with both matching and non-matching inputs
- ✓ Use expressions (=) for numeric lookups when calculations needed
- ✓ Document your lookup tables in flow comments
- ✓ Consider using Query Data stage for very large lookup tables stored in database
Common Mistakes
| Mistake | Symptom | Fix |
|---|---|---|
| Case mismatch | Expected match not found, uses default | Ensure keys match exactly including case ("CA" ≠ "ca") |
| Expecting Fail for match | Wrong exit path taken | Pass = match found, Fail = default used (not error) |
| Forgetting = for expressions | Expression treated as text instead of being evaluated | Start values with = for math: =0.0725 not 0.0725 |
| Using same key multiple times | Only first match used | Ensure unique keys; first matching key wins |
| Not handling Fail exit | Flow breaks when no match found | Connect Fail exit to handle unmatched cases |
Troubleshooting
| Issue | Exit/Result | Common Cause | Fix |
|---|---|---|---|
| Always using default value | Fail (default used) | Keys don't match exactly (case, whitespace, type) | Verify exact match including case; check for extra spaces |
| Expression not evaluating | Pass/Fail (but wrong value) | Missing = prefix for expression | Start value with =: =10+5 not 10+5 |
| Wrong value returned | Pass (but unexpected value) | Duplicate keys, first match used | Remove duplicate keys; ensure each key is unique |
| Flow breaks on no match | Fail (but no handler) | Fail exit not connected | Connect Fail exit to handle default case |
Do's and Don'ts
Do:
- ✓ Use meaningful default values
- ✓ Keep keys consistent in format
- ✓ Test with both matching and non-matching inputs
- ✓ Use expressions for numeric calculations
- ✓ Connect both Pass and Fail exits
- ✓ Document lookup tables in comments
Don't:
- ✗ Mix case in keys (inconsistent uppercase/lowercase)
- ✗ Expect Fail exit to mean error (it means "no match")
- ✗ Forget = prefix for expressions
- ✗ Use duplicate keys (only first matches)
- ✗ Leave Fail exit unconnected
Related Stages
- Route Flow: For more complex conditional logic beyond simple lookups
- Query Data: For lookups from database tables instead of hardcoded values
- Change Data: For simple value assignments without lookup logic
- Set Default Value: For providing fallback values