FORM Butler – Web Form Lookup Filter

1.  Overview #

The Lookup Filter is a new configuration parameter available on the Lookup component in the Form Editor. It allows administrators to define custom filtering logic that controls which records appear in a lookup dropdown during data entry.

Without a filter, the lookup shows all records of the target object. With a filter, only records matching the specified conditions are displayed — giving you precise control over what users can select.

✓  Tip:  This feature requires no code changes by end-users. All configuration is done through the Form Editor’s property panel.

 

2.  How It Works #

The Lookup Filter accepts a partial SOQL WHERE clause — exactly the condition portion of a SOQL query, without the WHERE keyword itself.

When a user opens a lookup dropdown at runtime, the system automatically appends this clause to the underlying query, narrowing the returned record set.

Behavior at runtime #

• Filter is empty → standard lookup behavior (all records returned, subject to object permissions)
• Filter is provided → only records matching the filter are shown in the dropdown

⚠  Important:  The filter is applied in addition to any built-in permission or sharing rules — it does not bypass security.

 

3.  Configuring a Lookup Filter #

3.1  Accessing the Setting #

1. Open the Form Editor for the relevant form.
2. Select the Lookup component on the canvas.
   

3. In the right-hand Properties panel, locate the Lookup Filter field.
   

4. Enter your filter expression (see Section 4 for syntax).
   

 

5. Save the form.
   

 

6. Create a Form Request and check the result — the Lookup field should display only the filtered values.

3.2  Field Details #

 

Property	Value
Field Name	Lookup Filter
Field Type	Text (string)
Required	No — field is optional
Default Value	Empty (no filter applied)
Format	Partial SOQL WHERE clause — the condition expression only, without the WHERE keyword

 

4.  Filter Syntax Reference #

The filter expression follows the same syntax as the condition clause in a SOQL query. Do not include the SELECT, FROM, or WHERE keywords — enter only the filtering conditions.

4.1  Supported Operators #

 

Operator	Description	Example
=	Exact match	Status = ‘Active’
!=	Not equal	Type != ‘Prospect’
<	Less than	AnnualRevenue < 500000
>	Greater than	AnnualRevenue > 1000000
<=	Less than or equal	CreatedDate <= TODAY
>=	Greater than or equal	CreatedDate >= LAST_YEAR
LIKE	Pattern match (% wildcard)	Name LIKE ‘%Corp%’
AND	Both conditions must be true	IsActive = true AND Type = ‘Partner’
OR	Either condition must be true	Rating = ‘Hot’ OR Rating = ‘Warm’
( )	Group / precedence	(A OR B) AND C

4.2  Syntax Rules #

• String values must be wrapped in single quotes: Type = ‘Customer – Direct’
• Boolean values use bare true / false (no quotes): IsActive = true
• Numeric values are unquoted: AnnualRevenue > 1000000
• Date literals use SOQL keywords (no quotes): CreatedDate >= LAST_YEAR, CloseDate <= TODAY
• ID values are quoted strings: OwnerId = ‘005XXXXXXXXXXXX’
• The % wildcard in LIKE matches zero or more characters — it can appear at either end of the pattern.
• Use parentheses to control logical precedence when mixing AND and OR.

 

5.  Filter Examples #

The table below shows practical filter expressions covering common use cases.

 

Use Case	Filter Expression
Simple equality	Type = ‘Customer – Direct’
Text wildcard (contains)	Name LIKE ‘%Oil%’
Multiple LIKE (OR)	Name LIKE ‘%Oil%’ OR Name LIKE ‘%Grand%’
Multi-field AND	Industry = ‘Energy’ AND BillingCountry = ‘USA’
Date literal	CreatedDate >= LAST_YEAR
Boolean field	IsActive = true
Grouped conditions	(Industry = ‘Finance’ OR Industry = ‘Banking’) AND Rating = ‘Hot’
Specific owner ID	OwnerId = ‘005XXXXXXXXXXXX’
Numeric comparison	AnnualRevenue > 1000000
Starts-with + boolean	Name LIKE ‘A%’ AND IsDeleted = false

 

6.  Best Practices #

6.1  Keep filters simple #

Complex multi-level filters can be harder to maintain and may impact query performance. Use parentheses to make precedence explicit rather than relying on operator priority.

6.2  Avoid hardcoded IDs when possible #

Filters like OwnerId = ‘005XXXXXXXXXXXX’ work correctly but are environment-specific. A hardcoded User ID from sandbox will not be valid in production. Prefer field-based conditions when feasible.

6.3  Remember that filters add to, not replace, security #

The Lookup Filter narrows the displayed record list, but Salesforce object-level and record-level security still applies. A record hidden by a filter can still be accessed through other means if permissions allow it.

 

7.  Troubleshooting #

 

Symptom	Likely Cause & Fix
Lookup dropdown shows no results	Filter may be too restrictive, or the expression contains a syntax error. Try clearing the filter temporarily to confirm base lookup works.
All records appear despite having a filter	Check that the form has been saved after editing the filter field, and that the page has been refreshed.
Error on lookup open	An invalid SOQL expression (e.g. missing quote, unknown field name) will cause a query error. Verify the field API names and string quoting.
LIKE filter returns unexpected records	Ensure the % wildcard is correctly positioned. ‘%Oil’ matches records ending in ‘Oil’; ‘%Oil%’ matches records containing ‘Oil’ anywhere.

 

8.  Quick Reference Card #

✓  Tip:  Copy these patterns as a starting point and adjust the field names and values to match your object schema.

 

Filter by account type #

Type = ‘Customer – Direct’

 

Filter by name pattern #

Name LIKE ‘%Oil%’

 

Filter by name (multiple patterns) #

Name LIKE ‘%Oil%’ OR Name LIKE ‘%Grand%’

 

Filter by industry AND country #

Industry = ‘Energy’ AND BillingCountry = ‘USA’

 

Filter by date #

CreatedDate >= LAST_YEAR

 

Filter active records only #

IsActive = true

 

Filter with grouped OR conditions #

(Industry = ‘Finance’ OR Industry = ‘Banking’) AND Rating = ‘Hot’

 

Filter by owner #

OwnerId = ‘005XXXXXXXXXXXX’

 

Filter by revenue threshold #

AnnualRevenue > 1000000

 

Filter by name prefix and boolean #

Name LIKE ‘A%’ AND IsDeleted = false