Skip to main content

Filtering search results

You can configure a plugin program to filter search results based on the type of search engine. You can use this plugin to set up some search criteria for an engine so that only search results that satisfy the criteria will be visible to the user.

To enable this plugin:

  1. Click Manage the system > Modules > Options .

  2. Type the name of the plugin in the SEARCH FILTER PLUGIN field.

  3. Type a comma-delimited list of engines from which to call the plugin in SEARCH FILTER PLUGIN ALLOWED ENGINES.

Allowable engines are listed here.

A component extension is shipped for use with this plugin point.

Write a custom search filter plugin

Requirements

See Writing plugins for general requirements.

Execution points

This plugin is called by all search engines defined in Modules > Options > SEARCH FILTER PLUGIN ALLOWED ENGINES. It is called after a user submits a search request.

Input

The input presented to the plugin is a KVGroup that includes the viewer information, module, search type, transaction ID, CGI name, a list of advanced search keys and session ID.

"" "" = {
  "viewer" "user" = { ... }
  "module" = "ajaxsvc"
    # Where the plugin is being run from
  "searchType" = "<ROLE|NOSGROUP|MANAGER|USER|ACCOUNT|HOST|...>";
        # The search engine calling the filter plugin
  "clientIp" = "<Client IP address>"
        # The requester's client IP address
         
  "proxyIp" = "<Proxy IP address>"
        # The requester's proxy IP address (empty if there is no proxy)
  "transactionId" = "<Transaction ID>"
    # The transaction ID where the search engine is being run
  "searchName" = "<App search name>"
   # The app search name where the search engine is being run (optional,
   # used only in apps)
  "filterName" = "<App filter ID>"
   # The app filter name where the search engine is being run (optional,
   # used only in apps)
  "cginame" = "<psa|ajax|idr|ids|...>"
   # "recipient" "user" = { ... }
         
   # Recipient's data present only when cginame=psa
   # or when cginame=ajax and searchType=HOST .
  "ValidKeys" "" = {
    "<advance search key>" = "" # 1 or more keys to filter on
    "<dynamic group>" "" = {
         
        "<field key>" = "" # 1 or more field keys to filter on
    } # 0 or more dynamic groups available to filter fields on
  }
  # request data present only when cginame=psa. .
  # "requestID" = <request ID> present only when cginame=ajax.
  # "prequest" = "_UPDATE_ATTRS_" present only when searchType=HOST.
  # "wizardDisplayPageId" = "<wizard display Page ID" present only when searchType=HOST.
  # "wizardDisplayPageType" = "<page Type>" present only when cginame=ajax.
  "sessionid" = "<Session ID>"
    # The session ID for the viewer
}

Output

The plugin provides a criteria KVGroup to the search engine.

 "" ""  = {
        "criteria" "" = {
                "filter" "" = {
                        "position" = "<N>"; # Mandatory and must be an
                            # increasing sequence of filter items beginning at 1.
                        "key" = "<search engine advance key>";
                        "comparator" = "<comparator value>"; # See below for more detail
                        "value" = "<value>"; # Mandatory; Includes the value used in the comparison.
                        "operator" = "<operator value>" #Required when "position" > 1
                        "field" = "<field value>" #Required when using a key from a dynamic group.
                        "negate" = "0|1"; # "1" generates the logical NOT of "filter"
                }; # Must include one or more filter groups.
        ...
        };
  };

In a "criteria" group, each filter includes the following key-value pairs:

  • key Search engine advanced keys.

  • comparator Must be one of:

    • "EQUAL" (or "EQ")

    • "LESS_THAN" (or "LT")

    • "LESS_THAN_OR_EQUAL" (or "LTE")

    • "GREATER_THAN" (or "GT")

    • "GREATER_THAN_OR_EQUAL" (or "GTE")

    • "CONTAIN" (or "CT")

    • "START_WITH" (or "SW")

    • "IS"

    • "ON"

    • "BEFORE" (or "BF")

    • "BEFORE_OR_ON" (or "BFO")

    • "AFTER" (or "AF")

    • "AFTER_OR_ON" (or "AFO")

  • value What is compared by comparator. When comparator is "IS", <value> must be "SET" or "EMPTY". When comparator is "CT" or "SW", <value> can contain wildcards "*" and "?". Otherwise, <value> is a wide string (can contain unicode characters).

  • operator Required when "position" is greater than 1. Must be "OR" or "AND". The logical operator is applied before "filter", in order to logically connect "filter"s together, in order of "position" value. AND always has precedence over OR.

  • field Optional key to specify field when the key is not sufficient; for example, when dealing with attributes, field = attribute key; when dealing with resource groups, field = resource group id.

  • negate When "1", this generates the logical NOT of "filter".

The following example of criteria instructs the search engine to find records such that:

  • advanced key "userid" EQUALS string "ADMIN"

    OR

  • advanced key "rolesearch" does NOT CONTAIN substring "MANAGER"

    "search" "" = {
    "criteria" "" = {
        "filter" "" = {
            "position" = "1"
            "key" = "userid"
            "comparator" = "EQ"
            "value" = "ADMIN"
        }
        "filter" "" = {
            "operator" = "OR"
            "position" = "2"
            "key" = "rolesearch"
            "negate" = "1"
            "comparator" = "CT"
            "value" = "MANAGER"
        }
    }
}

Group recommendations

If the searchType is MANAGEDGROUP, the search filter can also return a recommend KVGroup to the search engine:

 "recommend" "" = {
            "attributeGroup" = "<Attribute group ID>" #Existing profile attribute
         
                 # group. If included, this overrides GROUP_APP_MATCHING_ATTRIBUTE_GROUP
            "showOnly" = "0|1" #If enabled, filter out results where
                 # matching users are less than the cutoff
            "cutOff" = "<0..100>" #Sets the lower threshold to filter on.
            #If included, this overrides SEARCH_FILTER_RECOMMENDATION_CUTOFF.
        }
In this section: