Key Match Task¶

Overview¶

The Key Match Task performs dynamic lookups by matching a value against multiple key-value pairs and returning the corresponding result. Think of it as a lookup table or switch statement that converts one value into another.

When to use this task:

• Route workflows based on values (status codes, categories, types)
• Convert codes to descriptions (state abbreviations to full names)
• Dynamic team assignment based on criteria
• Status code mapping and translations
• Multi-language content selection
• Product category routing
• Priority level conversions

Key Features:

• Unlimited key-value mappings
• Fallback value support
• Exact string matching
• Variable replacement in keys and values
• Returns matched key and value
• Case-sensitive matching

Quick Start¶

1. Add Key Match task
2. Enter value to match
3. Add key-value pairs
4. Optional: Set fallback value
5. Save

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Match Value¶

Match Value: {{task_55001_state}}
Match Value: {{task_47001_status_code}}
Match Value: NY

The value to search for in your key-value pairs.

Key-Value Pairs¶

Key: NY → Value: New York
Key: CA → Value: California
Key: TX → Value: Texas
Key: FL → Value: Florida

Add as many mappings as needed. If match value equals a key, returns that key's value.

Fallback Value¶

Fallback: Unknown State
Fallback: default@company.com
Fallback: Not Found

Optional. Returned if no key matches.

Output Fields¶

Real-World Examples¶

Turn a product code into a department¶

Webhook In
  └─ Key Match     ELEC → electronics@example.com, FURN → furniture@example.com
      └─ Email     send to {{task_17001_value}}

{{task_17001_value}} is the matched result and {{task_17001_match}} tells you whether anything matched at all — check it before using the value.

Map a form's plan choice to a price¶

Form Submission
  └─ Key Match         basic → 250, standard → 500, premium → 900
      └─ Math Formula  calculate the total from {{task_17001_value}}

Route by branch¶

Google Review Received
  └─ Key Match     location ID → that branch manager's email
      └─ Email      notify {{task_17001_value}}

Best Practices¶

Key Design¶

1. Use consistent formats - All keys same case, format
2. Avoid duplicates - Each key should be unique
3. Consider variations - Include common alternatives
4. Document mappings - Keep reference of key-value pairs
5. Test all keys - Verify each mapping works

Fallback Strategy¶

1. Always provide fallback - Prevent undefined results
2. Meaningful defaults - Descriptive fallback values
3. Log unmatched values - Track missing mappings
4. Alert on fallback - Notify if fallback used frequently
5. Review and expand - Add new keys based on usage

Value Types¶

# Email addresses
CA → sales-west@company.com

# Numbers (as strings)
High → 1
Medium → 2
Low → 3

# URLs
Product A → https://example.com/product-a

# Descriptions
200 → Success: Request completed

# IDs
active → 5
pending → 3

Performance¶

1. Moderate key count - Works well with 10-100 mappings
2. Cache frequently used - Store in variables if reused
3. Exact matching only - No pattern matching overhead
4. Consider alternatives - keep a large mapping in a sheet and read it with Google Sheets

Troubleshooting¶

No Match Found¶

Issue: Returns fallback when expecting match

Causes:

• Key spelling doesn't match exactly
• Case sensitivity (NY vs ny vs Ny)
• Extra whitespace in match value or keys
• Variable not properly replaced

Solution:

# Check exact value
Code Task: return {debug: input.task_55001_state};

# Normalize before matching
Find Replace:
  Input: {{task_55001_state}}
  Find: " " → Replace: ""
  (Remove spaces)

# Use Formatter for case
Formatter: UPPERCASE {{task_55001_state}}

Fallback Always Triggered¶

Issue: Never finding matches

Cause: Match value empty or undefined

Solution:

# Add If condition before Key Match
If: {{task_55001_state}} is not empty
Then: Run Key Match
Else: Use default value

Wrong Value Returned¶

Issue: Unexpected value returned

Causes:

• Duplicate keys (first one wins)
• Variable in value not replaced
• Incorrect key-value configuration

Solution:

• Review all key-value pairs
• Test each key individually
• Check for typos in keys

Variable Not Replaced in Output¶

Issue: {{variable}} appears in returned value

Cause: Variable doesn't exist in previous task

Solution:

• Verify source task ran successfully
• Check variable name spelling
• Use Coalesce for fallbacks

Frequently Asked Questions¶

Is matching case-sensitive?¶

Yes, "NY" and "ny" are different keys. Use Formatter task to normalize case before matching.

Can I use partial matching?¶

No, only exact matches. Use Regex task for pattern matching.

How many key-value pairs can I add?¶

No hard limit, but keep it practical (10-100). For a larger or frequently changing mapping, keep it in a sheet and read it with Google Sheets get_rows.

Can values contain variables?¶

Yes, all values support variable replacement from previous tasks.

What if multiple keys match?¶

First matching key wins. Ensure keys are unique.

Can I nest Key Match tasks?¶

Yes, output from one can be input to another for multi-level lookups.

Does order matter?¶

Keys checked in order configured. First match returns immediately.

Related Tasks¶

• Coalesce - Provide fallback values
• If Task - Simple true/false branching
• Formatter - Normalize text before matching
• Variable - Store matched values for reuse
• Code Task - Complex conditional logic