Skip to main content

Filter pre-defined requests

Bravura Security Fabric can filter pre-defined requests so that requesters only see requests that are relevant to them. Bravura Security Fabric can run a request filter plugin when users select options to request new resources or update their or another user’s profile.

This plugin is set by the Modules > Options > FILTER PREQUEST PLUGIN field.

It also affects the pre-defined requests that product administrators are allowed to manage if the PSA FILTERING option is enabled in the Modules > Manage the system (PSA) module menu.

There are no shipped plugins in use with this plugin point.

Write a custom pre-defined request filter plugin

Requirements

See Writing plugins for general requirements.

Execution points

This plugin is run by the View and update profile (IDR) module.

Filter plugins operate differently from most plugins, which are synchronous. All filter plugins support asynchronous calling. There are two forms of asynchronous calling:

  • Standard input/output mode that processes standard filter plugin input/output.

  • Callback mode that uses two functions to process the input/output.

    This mode can be used to reduce processing time in environments with large numbers of users.

FILTER PREQUEST PLUGIN Standard input/output mode

In standard input/output (stdio) mode, filter plugins work in the following way:

  1. An event triggers a CGI program to call the plugin program or script and sends it standard user data.

  2. The calling program continues to stream input from stdin, one item at a time until there are no more items.

  3. For each item, the plugin returns the filter result to stdout.

  4. The calling program receives the final standard output and continues.

Input

Input is similar to resource filter plugins. The plugin first receives standard data in the format:

"" "" = {
       "recipient" "user" = {
                     
           # The "recipient" group contains standard information about the
                     
           # subject of the request.
       }
       "module" = "idr"
                     
       "viewer" "user" = {
           # The "viewer" group contains standard information about the
           # person using the CGI.
       }
   }

The plugin then receives a series of KVGroups; one for each item.

For example:

# KVGROUP-V1.0
          "prequest" "" = {
            "description" = "PREQ1"
            "itemID" = "PREQ1"
          }
# KVGROUP-V1.0
          "prequest" "" = {
            "description" = "PREQ2"
            "itemID" = "PREQ2"
          }
# KVGROUP-V1.0
          "prequest" "" = {
            "description" = "PREQ3"
            "itemID" = "PREQ3"
          }
# KVGROUP-V1.0
          "prequest" "" = {
            "description" = "!!!_CUSTOM_REQUEST_"
            "itemID" = "_CUSTOM_"
          }

Output

For each item, one output KVGroup is expected on stdout, with an optional "filter" = "true" pair to indicate that the item should not be displayed:

"" "" = {
"filter" = "true|false"
       # If false, the user is displayed
       # If true, the user is not displayed
"retval" = "<#>"
       # Optional, if non-zero returned, abort the plugin
}

A plugin that encounters errors in its processing can add standard output pairs for individual items, which should cause the plugin execution to be aborted.

FILTER PREQUEST PLUGIN Callback mode

In callback mode the pre-defined request filter plugin uses two functions:

OnFilterInit(const $inkvg, output $detail) This function is called once to initialize the environment based on the cgi user.

  • $inkvg – the viewer

  • $detail

    • if 0, no detail provided on input kvg for each user

    • if 1, detail is provided on input kvg for each user

    • can also be expressed as a KVGroup

OnItemFilter(const $inkvg, output $msg, output $allow) This function is called once per item to determine what pre-defined requests the user can use.

  • $inkvg – the pre-defined request to filter

  • $msg – error message

  • $allow

    • if 1, this user is displayed and available

    • if 0, this user is not displayed and is unavailable

In this section: