This article explains the different ways to perform a lookup in HappyFox Workflows — matching an incoming value against a table of key-value pairs to retrieve a mapped result — and helps you choose the right method for your use case.

When to use a lookup

A lookup lets you translate a raw field value from your trigger into something more useful for a downstream action. For example, you can map a ticket's category ID to an assignee name, or a domain name to an account tier, without hard-coding that logic into separate branches.

HappyFox Workflows offers three ways to perform a lookup:

• Use Lookup Table (inbuilt action) — enter pairs manually or upload a CSV. Best for self-contained, simple two-column mappings where all data lives inside Workflows.
• Google Sheets actions — look up row data from a connected Google Sheet. Best when your mapping data is large, maintained by others, or needs to be updated frequently without touching the workflow.

Method 1: Use Lookup Table (inbuilt action)

The Use Lookup Table action is an inbuilt action under Inbuilt Actions in the workflow builder. It matches a key from your trigger data against a two-column table you define, and returns the corresponding value.

Advantages over external lookups: All data is stored inside HappyFox Workflows. There is no dependency on a third-party account or file owner — if the person who manages an external sheet leaves or their account is deactivated, the lookup still works without reconfiguration.

The action supports two lookup types: Lookup Table (manual entry) and Lookup File (CSV upload).

Option A: Lookup Table (manual entry)

Use this when your mapping data is small and stable — for example, a fixed set of category codes mapped to team names.

Steps

1. Open the workflow builder and add a new action. Search for Use Lookup Table under Inbuilt Actions and select it.
2. In the Lookup Key field, insert the merge field from your trigger data whose value will be used as the key — for example, a ticket ID or domain name. Use Insert Merge Fields to select it.
3. In the Lookup Type dropdown, select Lookup Table.
4. In the Lookup Table section, enter your key-value pairs row by row. The left column is the key (the value to match); the right column is the mapped value to return. Click + to add more rows.
5. In the Fallback Value field, enter the value the action should return if no matching key is found. You can also use a merge field here.
6. Click Save and Test to validate the configuration against a test ticket.

Note: The table has no column headers in the UI. The left column is always treated as the key and the right column as the mapped value.

Note: The manual lookup table supports up to 50 rows. If your mapping data exceeds this, use the Lookup File option or the Google Sheets integration instead.

The Use Lookup Table action configured with manual key-value pairs and a fallback value set.

Option B: Lookup File (CSV upload)

Use this when your mapping data is larger or already maintained as a spreadsheet that you can export to CSV.

Steps

1. Open the workflow builder and add the Use Lookup Table action under Inbuilt Actions.
2. In the Lookup Key field, insert the merge field whose value will be used as the key.
3. In the Lookup Type dropdown, select Lookup File.
4. Under Lookup File, click Upload file and select your CSV. The file must have exactly two columns. The first column is treated as the key; the second column is the mapped value. Maximum file size: 10 MB.
5. In the Fallback Value field, enter or select the value to return when no match is found.
6. Click Save and Test.

Note: Your CSV must have exactly two columns. Files with more than two columns or with non-standard formatting will not parse correctly. Column headers in the CSV are included in the lookup — if your file has a header row, ensure the header values will never match a real key, or remove the header row before uploading.

The Use Lookup Table action with Lookup File selected and the Upload file button visible.

Using the lookup result in subsequent actions

After the Use Lookup Table action runs, the matched value is available as Lookup Value in the merge field selector for all subsequent actions. Use Insert Merge Fields in any downstream action field to reference it.

If no key matches and a fallback value is configured, the fallback is returned as the Lookup Value. If no fallback is set and no key matches, the field will be empty at runtime.

Note: The Lookup Value variable is scoped to the actions that follow Use Lookup Table in the same workflow. It is not available before the action or in a different branch.

Method 2: Google Sheets lookup actions

If your mapping data is large, maintained by your team in a shared spreadsheet, or needs to support filtering by more than one column, the Google Sheets integration provides three dedicated lookup actions:

• Lookup Row from Google Sheet — finds the first row where a single column matches the lookup value, and returns the full row.
• Lookup Row from Google Sheet (using Formula) — uses a Google Sheets formula to locate the row, for more flexible matching logic.
• Lookup a Row by Multiple Column Values — matches against more than one column simultaneously.

For setup and configuration steps, see Integrating Google Sheets with HappyFox Workflows.

When to choose Google Sheets over the inbuilt action:

• The data is already in a spreadsheet and updated regularly by a team member.
• You need to filter by more than one column (use Lookup a Row by Multiple Column Values).

When to choose the inbuilt action over Google Sheets:

• You want the data to stay entirely within HappyFox Workflows with no external dependency.
• The mapping is small and changes infrequently.
• You want to avoid reconfiguration risk if the Google account connected to the integration changes.

Method 3: Lookup Table Row action (Tables module)

The Lookup Table Row action retrieves the first row from a centrally managed table that matches one or more filter conditions you configure. Unlike the inbuilt Use Lookup Table action, it supports any number of columns and uses AND logic across multiple filters — making it suited for lookups that require more than one matching condition.

When to use this method:

• Your lookup requires matching on more than one column — for example, matching both a ticket category and a region to return the correct assigned team.
• Your mapping data has more columns or more rows than the inbuilt action supports.
• The same reference data is used across multiple workflows and you want to manage it centrally.
• You want multi-column lookup capability without an external dependency on Google Sheets.

Prerequisites

A table must already exist in the Tables module and be populated with data before you can configure this action. See Tables and the Lookup Table Row Action in HappyFox Workflows for steps to create a table and import data via CSV.

Steps

1. Open the workflow builder and navigate to the step where you want to add the lookup.
2. Click Add Action and select Lookup Table Row from the action list.
3. In the Table field, enter the exact name of the table to query. You can also use Insert Merge Fields to pass the table name dynamically from an earlier step or trigger field.
4. Under Match All, click + to add a filter condition.
5. In the Column field, enter the exact column header name from the table.
6. In the Condition field, select Is.
7. In the Value field, enter the value to match, or use Insert Merge Fields to pass a dynamic value from an earlier step.
8. Repeat steps 4–7 to add additional filter conditions. All conditions use AND logic — the action returns only rows where every condition is met.
9. Click Save or Save & Test to validate the configuration.

Note: The Condition field currently supports Is only. Matching is case-sensitive — the value you pass must match the table data exactly, including casing.

Warning: If no row matches the configured filters at runtime, the action fails and the workflow stops at that step. Run History will show the error: No rows matched the given filters. To avoid unexpected failures, verify that the values you pass are always present in the table before enabling the workflow.

Using the output in subsequent actions

When the Lookup Table Row action finds a match, each column value from the matched row becomes available as a merge field in all downstream actions. Merge fields follow the format Row [column header] — for example, a column called Priority is available as Row Priority, and a column called Assignee Email is available as Row Assignee Email.

To use a row value in a downstream action field, click Insert Merge Fields, expand the Lookup Table Row step, and select the column whose value you want to pass.

Choosing the right method

Next Steps

Your lookup result is now available as a variable in all subsequent workflow actions. Next, learn how to use merge fields and dynamic variables in HappyFox Workflows to pass the Lookup Value into messages, ticket fields, or other actions.