Plan a Salesforce filter (Admins)
Organization administrators use Org settings → Salesforce filters to turn Salesforce queries into reusable filters. Reps then use them from Add filter without rebuilding the Salesforce criteria, in Tools → Discover (Accounts and Contacts tabs), Prospecting → Signals, Prospecting → Tasks, account and contact lists, Active sequences, and Build contact list when adding contacts to a sequence, operator, or list. For example, a filter can find accounts in a target segment, or contacts and leads that belong to a campaign.
Your organization needs a working Salesforce connection with access to the objects and fields you want to query. For help connecting Salesforce, see Integrate more platforms.
Each filter is a block with a label, a Salesforce source (an object and a return field), and conditions. For each condition, decide whether you fix the value for everyone or reps choose it. Salesforce filters only narrow search results. To choose which Salesforce fields appear on records, see Layout configuration. For sync mappings, see CRM sync and troubleshooting.
Create a single-query filter block
- Open Org settings → Salesforce filters and select New (or Add your first block). Replace Untitled block with a label your team will recognize.
- Leave Query mode set to Single query.
- Under Source, select the Salesforce object to query and the Return field. For an account filter on
Account, returnId. When you query related records, such asOpportunityorCampaignMember, return the field that identifies the account, contact, or lead, such asAccountId,ContactId, orLeadId. - Check Where it appears. Auto places the block under Account or Contact filters based on what the query returns. Choose Account filters, Contact filters, or Both only when the return field is a custom lookup that Auto can't read.
- Under Conditions, select Add, then Condition or an ALL, ANY, or NONE group. For each condition, choose the Salesforce field, Type, Operator, and Filled by:
- You: you set a fixed value. Reps see the condition but can't change it.
- Rep: reps fill in the value in Discover or Signals. Select Edit condition details to set the Label shown to reps and the choices.
- To apply a condition without showing it to reps, select its eye icon (Hide this condition from reps). A hidden condition always applies, with a value you fix.
Type sets the kind of value: Text, Number, Date, Checkbox, Dropdown, Searchable dropdown, Multi-select picklist (Salesforce), or User. For a User condition, turn on Matches the current user (me) in the condition details to match the person running the search.
Disable turns off the whole block: reps don't see it, and it stops applying. The block list marks it Disabled, and Enable turns it back on. Block changes take effect when you save the page.
Set up dropdown choices and Salesforce picklist sync
For a rep-filled condition with a Dropdown, Searchable dropdown, or Multi-select picklist (Salesforce) type, open Edit condition details and choose where the options come from in Choices come from:
- A list I type in: select Add option and fill in each option's Label (shown to user) and Value (sent to Salesforce). For example, show a campaign's name and send its 18-character Salesforce ID. If the condition's Salesforce field is a picklist, Sync from Salesforce replaces the whole typed list with the field's active picklist values. Review the list before saving.
- A value set: choose a saved value set to fill the options from live data, such as currently active campaigns. Keep suitable Fallback options; reps see them until the value set has produced values. Use Open this value set to check its source, or Create a value set to build a new one.
For a Dropdown or Searchable dropdown, turn on Allow selecting multiple values to let reps pick more than one option. A Multi-select picklist (Salesforce) condition always accepts several values. Shared inputs in a multi-query block can also use value sets, but they aren't tied to one Salesforce field, so they can't use Sync from Salesforce.
Choose a date range when searching
A Salesforce date filter can focus a search on a preset period or a specific window, such as records created during an event.
- In Discover or Signals, open the Salesforce filter, then open its date control.
- Select a preset, such as Last 30 days or This quarter, or choose Custom range and set both the start and end dates. Custom range is offered only when the condition uses the = operator on a Salesforce date or date/time field. Other date conditions, including shared inputs in multi-query blocks, offer presets only.
- For a date-and-time field, check the time zone shown under the range. The range includes the whole end date in that time zone.
- Select Apply, then review the active filter and matching records.
A custom range keeps the dates you chose. Use a preset when the window should move with time. If an older saved range is no longer available, reopen the filter and choose a valid range before relying on its results.
Create and refresh a value set
- Below the condition's Choices come from menu, select the Create a value set link next to the Options or Fallback options heading. While your organization has no value sets, it's also a choice in the menu. The value-set editor opens in a new tab.
- In its chat, describe the choices: the Salesforce object, which records to include, the label reps should see, and the value Salesforce expects. For example: “Return the Name as label and Id as value for active Salesforce campaigns created this year.”
- Review the plan Athean proposes and approve it. Saving the value set also asks for your approval.
- Open the value set's Values tab and check the values, Last refreshed, and Last run. Use Filter values to find a choice.
- Return to Org settings → Salesforce filters, select the value set under Choices come from, then test and save the filter.
A new value set runs on its own shortly after it's created, and it refreshes automatically while filters use it. Until it has produced values, filters use the typed fallback options. If a run fails, filters keep the values from the last successful run, and the Values tab shows the failure.
Organization administrators and configuration managers can select Refresh now to start a new run. The current values stay in use until that run finishes, so check Last refreshed and Last run afterward.
The Values tab also reports when a set's results were capped, and which values were left out because a filter can't use them. Editing a value set in its chat saves a new version, which isn't used until you activate it on the Versions tab.
Combine multiple Salesforce queries in one filter block
Use Multiple queries (advanced) when one filter needs to combine separate Salesforce queries. For example, campaign membership can identify contacts through one return field and leads through another, while reps choose the campaign only once.
- Change Query mode to Multiple queries (advanced). An existing single query becomes the first query, and its rep-filled conditions become shared inputs.
- Under Shared inputs, select Add input. Set its Label shown to reps, Input type, and options or value set.
- Select Add query for each query, and choose its Salesforce object, Return field, and conditions.
- In each query, set a condition's Value source to a shared input to connect it. Each shared input must be used in every query. Use Fixed value for restrictions that apply to only one query.
- Check the block with Test selections, Test, and Rep preview, then save the page.
The filter matches records returned by any of its queries and includes each record once. A record doesn't need to match every query. Other active filters still narrow the results.
To switch back to Single query, remove the extra queries and use each shared input exactly once in the remaining query.
Test and save a filter block
- Check Rep preview. It shows the exact panel reps get, including inputs, choices, and locked conditions. Hidden conditions aren't shown, but they still apply.
- Review Compiled SOQL and select Test to run the query against Salesforce. For a block with multiple queries, set representative Test selections first. They apply only to the test, and blank inputs are left out of every query.
- Review the match count and any error. Multiple queries show the combined unique IDs and a count for each query. A count ending in + is capped, not an exact total. Change the selections and test again if the result is unexpected.
- Fix the validation messages on every block, then select Save changes and wait for Salesforce filter settings saved. Testing alone doesn't save anything.
- Open Tools → Discover or Prospecting → Signals, find the block in the Account or Contact section of Add filter, choose its values, and check the matching records.
To reuse a useful combination of filters, save it as a view (see Saved views). Saving the filter configuration makes the block available to reps. It doesn't create a list or change any Salesforce records.
Troubleshooting
| Issue | Resolution |
|---|---|
| Save changes is blocked | Read the block's validation message. Check the source object and return field, field and input types, operators, required values, and, in a multi-query block, that every shared input is used in every query. Every block on the page must be valid before you can save. |
| The Salesforce test fails | Read the returned error. Check the Salesforce connection, the field API names (a field's label and API name can differ), value types (such as a name where an ID is expected), and whether your Salesforce integration user can access the object and fields. |
| Reps can't find the block in Discover or Signals | Check that the block is saved, isn't marked Disabled, and that Where it appears matches where reps look (Account filters, Contact filters, or Both). Hidden conditions never appear, but they still apply. |
| Dropdown choices are out of date or show fallback options | Use Open this value set and check Last refreshed and Last run on the Values tab. A run may still be in progress, or a failed run left the last successful values in place. Organization administrators and configuration managers can select Refresh now. |
| The value set is missing, not resolved yet, or empty | Read the message under Choices come from; it says what reps see right now. When the value set no longer exists or hasn't run yet, reps see the typed fallback options. Choose another value set, or correct the rule in the value set's chat. |
| Too many or too few matches | Check hidden fixed conditions, the selected values, the return field, and other active filters. A multi-query block combines matches from any of its queries. Use representative Test selections to find the difference. |
For help, contact support@athean.com with the filter label, the search you ran, the test error or result, and one record you expected to match.