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.

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.