FSM Article Filtering and Search Caching
This topic is intended for administrators and developers who work with article filtering and search result reuse.
Use article.filterby to filter mapped articles after retrieval. This topic explains how filtering interacts with search-result reuse.
This topic includes the following sections:
Filtering Mapped Articles with filterby
Use article.filterby to select a subset of articles after their search results have been retrieved and mapped. Each property name must identify a top-level property in the mapped article, such as id or asset. The article is retained only when every specified property matches its comparison value.
The following table compares the stages at which filters and filterby apply.
|
Property |
Names Used |
Effect |
|---|---|---|
|
|
NetSuite search fields or mapped filter names. |
Restricts the records retrieved by the NetSuite search, using search operators. |
|
|
Top-level mapped article property names. |
Matches the retrieved articles against the supplied values. It doesn't add a NetSuite search condition or group results. |
Use individual values for matching. The filterby property doesn't accept NetSuite filter operators, conditions joined with and or or, or a list of alternative values for one property. A property containing a nested Select object should be mapped to an individual value before using it for this matching.
For example, the standard Consumables resource searches for the current event's Consumable records belonging to the current employee. Its article.map returns the linked asset as asset, and its article.filterby selects the records for the requested asset:
{
"filterby": {
"asset": "${ options.asset || event.asset }"
}
}
This fragment belongs within routes/mobile.consumables.article. FSM uses the request's asset when supplied. Otherwise, FSM uses the current event's asset. The fragment reproduces the standard property, rather than defining the complete resource. Preserve its existing filters and map when configuring related behavior. Omitting filterby from custom JSON retains any inherited standard definition.
This separation allows the same underlying search results to be reused for different asset selections when caching is available. Changing only filterby doesn't change the search cache key. Moving the asset condition into filters changes the underlying search and its cache key. The more selective search may retrieve less data, and filterby may avoid repeating a shared search. Measure the effect for the intended use.
Continue to use filters for the required event, employee, customer, and other record restrictions. Because filterby runs after retrieval, it doesn't reduce the rows searched or extend the retrieval limit. It can return fewer articles than the search retrieved. It applies to article record models, including individual named sources. This property is not applied by a resolved element options or value search.
Reusing Search Results
FSM can reuse previously retrieved results when search caching is enabled and matching results remain available to the server execution. The search cache compares the record type, processed filters, map, saved-search identifier where used, raw or mapped result mode, and all setting. The filterby property is applied after cache retrieval and is not part of this key.
For resolved searches, such as element options and value searches, caching defaults to true. Setting cache: false on that search bypasses both reading and writing its search-cache entry. Standard resource article loading also requests cached search results. Adding cache to a direct article definition doesn't control caching for that loading operation.
Preserve common search definitions that provide the required behavior. Avoid changing filters or maps between otherwise identical calls unnecessarily. For repeated asset requests that need different subsets of the same eligible records, retain the standard filterby relationship. Use an alternative only if measurements show that it improves performance and preserves the behavior.
The server search cache and the data already loaded into FSM Mobile are separate mechanisms. Don't assume that search-cache reuse eliminates an FSM Mobile request, persists between requests, or guarantees fresh data after a record changes. For guidance on capturing performance data, see Capturing FSM Performance Data.