Feed lookup actions
Use a feed lookup action to find rows in a data feed using information already available in the service. Typical uses include matching a reference number to a record, finding an addressable area from a code, or returning a controlled list of results for a search page.
Configure the data feed before adding the action, then add the action from Page actions. A lookup is most reliable when the source data has a clear key column and the service normalises the value it uses to search.
Design the lookup first
Decide whether the service expects one match or many. A reference-number lookup should normally return one row. A search or filter can legitimately return a list of rows.
flowchart LR
A[Collect or already have a search value] --> B[Feed lookup action]
B --> C{Matching row found?}
C -- Yes --> D[Use the result in the page or next action]
C -- No --> E[Show a clear next step]Avoid treating the first result as authoritative when duplicates are possible. Improve the source data or add matching rules until a single-record lookup truly identifies one record.
Configure the data feed and lookup timing
- Add or select the required data feed in the service configuration.
- In Page actions, choose Add action and select Feed lookup.
- Give the action a stable ID and descriptive name, for example
find_site_by_code. - Choose a trigger after the search input has been collected and validated in most cases.
- Select the data feed and add the matching rules.
- Choose a single or multiple result mode.
- Test matching, no-match and ambiguous-match cases in User view and QA.
For a lookup based on page input, After validation is usually appropriate: it avoids querying the feed when the search value is incomplete or invalid. A Page load lookup can be suitable when it uses a value established earlier in the journey.
Add matching rules
Data feed elements are the rules that connect a value in the service to a column in the data feed. Select the source of the value, choose a comparison, then identify the feed column or supply the comparison value as required by the rule.
Common patterns include:
| Need | Example approach |
|---|---|
| Find a row by a field | Match the site_code field against the SiteCode feed column. |
| Find a row by a value calculated earlier | Match the result of an earlier assignment against the appropriate feed column. |
| Test a particular feed column | Compare a feed column to a Liquid value such as the value the person entered. |
| Select a known row for controlled testing | Use a fixed row only in a tightly controlled scenario; prefer a business key for live services. |
Use exact matching for identifiers. Use case-insensitive matching only when letter case is not meaningful. Be cautious with partial, fuzzy and regular-expression matching: these can create unexpected matches and should be backed by clear user-facing search guidance.
When there are several rules, use all conditions when each must be true, such as matching both a region and an account number. Use any condition only when either criterion is intentionally sufficient.
Select the right result shape
Choose Single result when the action should return the first matching record. Choose Multiple results when a later component or template needs the full matching set.
If only one column is useful, use Limit results to column to return that value rather than the whole record. This can simplify a later template, but it also makes the action less flexible if another value is needed later. Use the exact feed-column name, and test the result when the cell is blank.
Keep the data feed’s headers stable. Renaming a source column can break a lookup even when the data itself has not changed.
Handle no match and unexpected data
Design a no-match path rather than allowing an empty result to silently continue. You might show an explanation, offer the person another way to continue, or route the case for review. The right response depends on whether a missing record is an expected user error or an operational exception.
Also test duplicate keys, blank cells, leading or trailing spaces, differently cased values and changed source data. If a lookup is used to make a decision, make the decision condition explicit and test it independently from the lookup itself.
Example: find a local service area
A person enters a location code. After validation, find_area matches that field to the LocationCode column in an approved feed and returns a single row. A following Assign action saves the returned area name for display, and a condition handles a no-match result by showing contact information instead of continuing to an unavailable route.
Test checklist
- The action uses the correct, current data feed.
- Every rule compares the intended service value with the intended feed column.
- The match mode reflects whether one or several results are valid.
- The service has a deliberate no-match and duplicate-match path.
- Feed headers and key values are stable and documented for maintainers.
- A changed, blank or unusually formatted input has been tested.
- Any action consuming the result runs after the lookup.