Skip to content

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

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

Field Description Example
task_17001_run Success status true
task_17001_run_text Status message Match found
task_17001_match Whether match found true/false
task_17001_key Matched key (or "fallback") NY
task_17001_value Returned value New York

Real-World Examples

Example 1: Dynamic Lead Routing by State

Scenario: Route leads to territory-specific sales reps based on state

Workflow: 1. Form Submission - Lead inquiry 2. Key Match - Map state to sales rep 3. Coalesce - Fallback to default rep 4. New Client - Create lead with assigned rep 5. Workflow Note - Create follow-up task 6. Email - Notify rep

State to Rep Mapping: 

Match Value: {{task_55001_state}}

Key: CA → Value: rep-west@company.com
Key: OR → Value: rep-west@company.com
Key: WA → Value: rep-west@company.com
Key: NY → Value: rep-east@company.com
Key: NJ → Value: rep-east@company.com
Key: PA → Value: rep-east@company.com
Key: TX → Value: rep-south@company.com
Key: FL → Value: rep-south@company.com
Key: GA → Value: rep-south@company.com
Key: IL → Value: rep-central@company.com
Key: MI → Value: rep-central@company.com
Key: OH → Value: rep-central@company.com

Fallback: rep-default@company.com

Verify Assignment: 

Coalesce:
Values to check:
1. {{task_17001_value}}
2. sales-manager@company.com

Returns: Assigned rep or escalates to manager

Create Lead: 

Company: {{task_55001_company}}
Status: New Lead
Responsible Manager: {{task_19001_value}}

Contact:
First Name: {{task_55001_first_name}}
Surname: {{task_55001_last_name}}
Email: {{task_55001_email}}
Cell: {{task_55001_phone}}

Notify Rep: 

To: {{task_19001_value}}
Subject: New {{task_55001_state}} Lead Assignment

New lead from {{task_55001_state}} territory:

Company: {{task_55001_company}}
Contact: {{task_55001_full_name}}
Location: {{task_55001_city}}, {{task_55001_state}}
Phone: {{task_55001_phone}}

Territory Rep: {{task_17001_value}}
Match Status: {{task_17001_match}}

[View in CRM]

Example 2: Status Code Translation

Scenario: Convert numeric API status codes to human-readable messages

Workflow: 1. Webhook In - API response received 2. Key Match - Translate status code 3. If Task - Check if success or error 4. Email - Notify based on status 5. MySQL Query - Log result

Status Code Mapping: 

Match Value: {{task_46001_status_code}}

Key: 200 → Value: Success: Request completed successfully
Key: 201 → Value: Success: Resource created
Key: 204 → Value: Success: No content to return
Key: 400 → Value: Error: Bad request - check parameters
Key: 401 → Value: Error: Authentication failed
Key: 403 → Value: Error: Access denied
Key: 404 → Value: Error: Resource not found
Key: 429 → Value: Error: Rate limit exceeded
Key: 500 → Value: Error: Server error - retry later
Key: 503 → Value: Error: Service unavailable

Fallback: Unknown status code: {{task_46001_status_code}}

Check Success: 

Condition: {{task_46001_status_code}} >= 200 AND {{task_46001_status_code}} < 300
True: Success path
False: Error path

Success Notification: 

To: admin@company.com
Subject: ✓ API Integration Success

API Request Completed:

Status: {{task_46001_status_code}}
Message: {{task_17001_value}}

Request ID: {{task_46001_request_id}}
Endpoint: {{task_46001_endpoint}}
Timestamp: {{current_timestamp}}

Error Notification: 

To: support@company.com
Subject: ⚠️ API Integration Error

API Request Failed:

Status Code: {{task_46001_status_code}}
Error Message: {{task_17001_value}}

Request ID: {{task_46001_request_id}}
Endpoint: {{task_46001_endpoint}}

Response Body:
{{task_46001_response_body}}

[View Logs]

Example 3: Product Category Routing

Scenario: Route product inquiries to specialized teams based on category

Workflow: 1. Form Submission - Product inquiry 2. Key Match - Map category to specialist team 3. Match to Client - Find customer 4. Workflow Note - Assign to specialist 5. Email - Auto-response with specialist info

Category to Team Mapping: 

Match Value: {{task_55001_product_category}}

Key: Hardware → Value: hardware-specialists@company.com
Key: Software → Value: software-specialists@company.com
Key: Cloud Services → Value: cloud-team@company.com
Key: Consulting → Value: consulting-team@company.com
Key: Training → Value: training-team@company.com
Key: Support → Value: support-team@company.com

Fallback: general-inquiries@company.com

Create Specialist Task: 

Type: Call
Client ID: {{task_15001_client_id}}
Due: today
Priority: High
User Tags: {{task_17001_value}}

Note: Product Inquiry - {{task_55001_product_category}}

Customer: {{task_15001_full_name}} at {{task_15001_company_name}}
Contact: {{task_15001_cell}} / {{task_15001_email}}

Category: {{task_55001_product_category}}
Assigned Team: {{task_17001_value}}

Product Interest: {{task_55001_product_name}}
Budget: ${{task_55001_budget}}
Timeline: {{task_55001_timeline}}

Inquiry:
{{task_55001_message}}

Auto-Response: 

To: {{task_55001_email}}
Subject: We received your {{task_55001_product_category}} inquiry

Dear {{task_55001_first_name}},

Thank you for your interest in our {{task_55001_product_category}} solutions.

Your inquiry has been assigned to our specialist team: {{task_17001_key}}

A specialist will contact you within 24 hours to discuss:
- {{task_55001_product_name}}
- Your requirements and timeline
- Pricing and implementation

Contact Information:
Team: {{task_17001_value}}
Phone: {{company_phone}}

Best regards,
{{company_name}}

Example 4: Priority Level Conversion

Scenario: Convert ticket urgency levels to SLA response times and routing

Workflow: 1. Email Trigger - Support email received 2. AI Prompt - Classify urgency 3. Key Match - Map urgency to SLA hours 4. Key Match - Map urgency to support tier 5. Match to Client - Find customer 6. Workflow Note - Create ticket with SLA 7. If Task - Alert manager for critical issues

Urgency to SLA Mapping: 

Match Value: {{task_38001_urgency}}

Key: Critical → Value: 1
Key: High → Value: 4
Key: Medium → Value: 12
Key: Low → Value: 24

Fallback: 24

Urgency to Tier Mapping: 

Match Value: {{task_38001_urgency}}

Key: Critical → Value: tier3-escalations@company.com
Key: High → Value: tier2-support@company.com
Key: Medium → Value: tier1-support@company.com
Key: Low → Value: tier1-support@company.com

Fallback: tier1-support@company.com

Create Support Ticket: 

Type: To-Do
Client ID: {{task_15001_client_id}}
Due: today
Priority: {{task_38001_urgency}}
User Tags: {{task_17002_value}}

Note: Support Ticket - SLA: {{task_17001_value}} hours

From: {{task_2001_from_email}}
Subject: {{task_2001_subject}}

Priority: {{task_38001_urgency}}
SLA: Response within {{task_17001_value}} hours
Assigned Tier: {{task_17002_value}}

Issue Summary:
{{task_38001_issue_summary}}

Customer Impact:
{{task_38001_impact}}

Issue:
{{task_2001_body}}

Critical Alert: 

Condition: {{task_38001_urgency}} = Critical

To: support-manager@company.com
Subject: 🚨 CRITICAL Support Ticket

CRITICAL ISSUE REPORTED

Customer: {{task_15001_company_name}}
SLA: {{task_17001_value}} hour response required
Assigned: {{task_17002_value}}

Issue:
{{task_38001_issue_summary}}

[View Ticket]

Example 5: Multi-Language Content Selection

Scenario: Serve content in customer's preferred language

Workflow: 1. Webhook In - User registration 2. Match to Client - Find existing user 3. Key Match - Map language code to welcome template 4. Key Match - Map language to support email 5. Email - Send localized welcome email 6. Edit Client - Store language preference

Language to Template Mapping: 

Match Value: {{task_46001_language}}

Key: en → Value: template-welcome-english
Key: es → Value: template-welcome-spanish
Key: fr → Value: template-welcome-french
Key: de → Value: template-welcome-german
Key: pt → Value: template-welcome-portuguese
Key: zh → Value: template-welcome-chinese
Key: ja → Value: template-welcome-japanese

Fallback: template-welcome-english

Language to Support Email: 

Match Value: {{task_46001_language}}

Key: en → Value: support@company.com
Key: es → Value: soporte@company.com
Key: fr → Value: support-fr@company.com
Key: de → Value: support-de@company.com
Key: pt → Value: suporte@company.com

Fallback: support@company.com

Send Welcome Email: 

To: {{task_46001_email}}
Template: {{task_17001_value}}

Variables:
- customer_name: {{task_46001_full_name}}
- language: {{task_46001_language}}
- support_email: {{task_17002_value}}
- account_url: https://app.company.com

Store Preference: 

Client ID: {{task_15001_client_id}}
Custom Field - language_preference: {{task_46001_language}}
Custom Field - welcome_template: {{task_17001_value}}
Custom Field - support_contact: {{task_17002_value}}

Template Content (example for English): 

Subject: Welcome to {{company_name}}!

Hi {{customer_name}},

Welcome! Your account is ready.

Get Started:
1. Complete your profile
2. Explore features
3. Contact support: {{support_email}}

[Login to Dashboard]

Language: {{language}}

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 - Use MySQL for 1000+ mappings

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 practical (10-100). For larger lookups, use MySQL Query with database table.

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.

  • Coalesce - Provide fallback values
  • If Task - Simple true/false branching
  • Formatter - Normalize text before matching
  • Variable - Store matched values for reuse
  • MySQL Query - Large-scale lookups from database
  • Code Task - Complex conditional logic