Skip to main content

Configure saved search plugin

You can use a plugin program to add or remove saved searches for users, based on the type of search engine. Saved searches created by plugin are known as Searches, and can be shared for all users.

Users can create saved searches for themselves from the user interface. My Searches cannot be shared across users. See Saved searches for more information about My Searches.

To enable this plugin:

  1. Navigate to Manage the system > Modules> Options.

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

Allowable engines

The plugin can be used with any search engine that supports advanced search, except for the old style advanced search pages in the Manage reports (RPT) module.

A sample component, hid_saved_search_sample, is shipped with Bravura Security Fabric for use with this plugin point.

Write a custom saved search plugin

Requirements

See Writing plugins for general requirements.

Execution points

The plugin is called by all allowable search engines when users selects the saved search drop-down menu.

Input

The input presented to the plugin is a KVGroup that includes the viewer information, module, clientIp, proxyIp, searchName, search type, cginame, a list of advanced search keys and session ID.

" " " " = {
  "viewer" "user" = { ... }
  "module" = "ajaxsvc"
  # Where the plugin is being run from
  "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)
  "searchName" = "<App search name>"
  # The app search name where the search engine is being run (optional,
  # used only in apps)
  "searchType" = "<ROLE|NOSGROUP|MANAGER|USER|ACCOUNT|HOST|...>";
  # The search engine calling the saved search plugin
  "cginame" = "<psa|ajax|idr|rpt|...>"
  "ValidKeys" "" = {
   "<advance search key>" = "" # 1 or more keys to filter on
 }
  "sessionid" = "<Session ID>"
  # The session ID for the viewer
}

Example

The following is an example of the input KVG file:

# KVGROUP-V1.0
"" "" = {
 "viewer" "user" = {
  "id" = "superuser"
         
  "name" = "superuser"
 }
 "module" = "ajaxsvc"
 "clientIp" = "::1"
 "proxyIp" = ""
 "searchName" = "IDC_C_SELECT_ROLE"
 "searchType" = "ROLE"
 "cginame" = "psa"
 "ValidKeys" "" = {
  "assignable" = ""
  "deprecated" = ""
  "description" = ""
  "enabled" = ""
  "entitlement" "" = {
        
  "groupid" = ""
  "groupname" = ""
  "roleid" = ""
  "rolename" = ""
  "tplid" = ""
  "tplname" = ""
  }
  "id" = ""
  "rbacenforce" = ""
  "user" = ""
 }
 "sessionid" = "S56d72485-354c-4ea5-a084-de52560cc6bd"
}

Output

The plugin provides a criteria KVGroup to the search engine.

# KVGROUP-V1.0
" "  " " = {
 "savedSearches" "" = {
  "savedSearch" "" = {
  "id" = "<saved search id>" # Characters <, >, /, &, " and ' are forbidden in plugin saved search IDs as they are significant characters in XML and/or HTML.
  "label" = "<saved search label>" # Any characters can be used in plugin saved search label, just "backslash" and "quotation" characters used in Python need to be escaped.
  "isDefault" = "0|1";# When set to '1', the saved search is auto-selected when corresponding engine page is open from UI. Note, there can be only one 'isDefault'='1' returned by plugin (per 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.
   "negate" = "0|1"; # "1" generates the logical NOT of "filter"
  } # Must include one or more filter groups.There is a hard limit of 5 filters for each saved search criteria.
   }
  }
  }
  "retval" = "0"
}

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 "EQ" or "EQUAL", <value> CAN be "(1—0—t—f—T—F) ". 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".

Example

The following is an example of the output KVG file:

  • Saved search name: "ROLE_DEV"

  • Filter: advanced key "Role ID" contains "DEV"

    # KVGROUP-V1.0
"output" "saved_search_plugin_sample" = {
 "savedSearches" "" = {
  "savedSearch" "" = {
  "id" = "plugin for ROLE2"
  "label" = "ROLE_DEV"
  "isDefault" = "1"
  "criteria" "" = {
  "filter" "" = {
   "position" = "1"
   "key" = "id"
   "comparator" = "CONTAIN"
   "value" = "DEV"
   "negate" = "0"
  }
   }
  }
  }
  "retval" = "0"
}

Example: Configure sample saved search component

This example demonstrates the processes of configuring the sample saved search component:

  1. On the Bravura Security Fabric instance server, locate the <instance>\samples\idmlib \component\Functional folder.

  2. Copy the hid_saved_search_sample folder to the <instance>\component\Custom\Functional folder.

  3. As a product administrator, log onto Bravura Security Fabric .

  4. From the main menu, click Manage components.

  5. Click the action Reload DB and wait for the component database to reload.

  6. Search for and install the Functional.hid_saved_search_sample component.

  7. Navigate to Manage the System > Resources > Target systems > Manually defined.

  8. Click the saved search drop-down list.

    The plugin saved search "AD Target" should be listed under the "Searches" section.

  9. Click the saved search ”AD Target”.

3825.png
3826.png

 

Configuration notes

Below are the important points when creating saved searches:

  • Plugin saved searches cannot be deleted from the UI (No trash can icon displays).

  • All saved searches have an ID (hidden) and a label (shown in drop-down list).

  • All saved searches must have unique IDs and labels. My Searches have unique, generated ”guid-like” IDs. Plugin saved search (Searches) IDs are defined by the plugin creator.

  • Plugin saved searches override my searches. When you have both a plugin and a my search with the same label, my search is not shown.

  • Characters <, >, /, &, " and ' are forbidden in plugin saved search IDs as they are significant characters in XML and/or HTML.

  • There is a hard limit of five criteria for each saved search. Extra criteria are simply dropped with a log warning.

  • Duplicate plugin labels are detected and rejected with a logged warning.

  • Plugin saved search labels are not case sensitive. Labels that are identical except for capitalization will be considered duplicates, and will be skipped and logged with warnings.

  • Label clashes between my searches and plugin saved searches are prevented. You cannot create a saved search with a label that already exists among plugin saved searches. On the contrary, you can create a plugin saved search with a label that already exists among my searches.

  • Saved searches are ordered alphabetically.

In this section: