Filter users

You can restrict access to certain user profiles by using the appropriate user filter or list generation plugin.

For example, the FILTER USER PLUGIN and KEEP USER PLUGIN controls who can view and manage which users. By default, regular users and help desk users can make access change requests for any user with a profile ID in the database. You may want to set up a filter, for example, to allow users to manage only their subordinates or members of their own group. The GENERATE USER PLUGIN generates a white list of accepted users to manage; whereas the filter plugin excludes users.

FILTER USER PLUGIN, KEEP USER PLUGIN, and GENERATE USER PLUGIN can also utilize user classes as filter criteria. You can do this instead of using a plugin, or in conjunction with a plugin. You may want to set up a relational user class to allow users to manage only their subordinates or members of their own group. See more information on using user classes with these plugin points .

FILTER USER PLUGIN and KEEP USER PLUGIN take precedence over GENERATE USER PLUGIN if they are both in use. For example, if GENERATE USER PLUGIN is set to list User01 and User02, but FILTER USER PLUGIN is set to filter out all users, then no users are listed.

Configure these plugins via the Manage the system > Modules > Options menu:

FILTER USER PLUGIN
KEEP USER PLUGIN
GENERATE USER PLUGIN

There are no shipped plugins for use with these plugin points. Advanced sample plugin scripts, filter-user.psl and filter-user-callback.psl are located in the samples\plugin directory.

See also

Filter resources show you how to write and configure plugins to filter resources such as template accounts and groups.

Write a custom user filter plugin

Requirements

See Writing plugins for general requirements.

Execution points

The plugin is called by the View and update profile (IDR) module and Help users (IDA) modules before the user list is displayed. It is called multiple times if there are more users than the value of the RECORDS PER PAGE setting. The plugin runs with the number of users determined by the RECORDS PER PAGE at a time.

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 reduce processing time in environments with large numbers of users.

FILTER USER PLUGIN Standard input/output mode

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

An event triggers a CGI program to call the plugin program or script and sends it standard user data.
The calling program continues to stream input from stdin, one item at a time until there are no more items.
For each item, the plugin returns the filter result to stdout.
The calling program receives the final standard output and continues.

Input

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

"" "" = {
  "sessionid" = "<session ID>" # The session ID of the request.
  "module" = "<idr|ids|idp|idwfm>"
                     
  "accountID" = "<account ID>" # The account ID of the recipient.
                     
  "template = "<template ID>" # The selected template ID.
  "targetid" = "<target ID>" # The target ID for the recipient.
  "navigation" "" = { ... } # User navigation data
  "recipient" "<user|empty>" = {
     # The "recipient" group contains standard information about the
                     
     # subject of the request.
   }
  "viewer" "user" = {
     # The "viewer" group contains standard information about the
     # person using the CGI.
   }
  "request" "" = {
     # The "request" group contains standard information about the
     # the request.
   }
 }

Some of the values above may be empty, due to the stage and type of the request.

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

"user" "" = {
    "id" = "Dave-Appla"
    "name" = "Dave Appla"
    "filter" = "<true|false>"
    # true, if the user has been excluded by this plugin
    # false, otherwise
}

See User data for a description of the user KVGroup.

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
    "needitemdetail" = "1|0"
           # If 1, all details are displayed in the input of the next user.
           # If 0, only ID is displayed in the input of the next user. By
           # default, it is set to 1.
}

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 USER PLUGIN Callback mode

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

In callback mode the user 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, see the example below

OnItemFilter(const $inkvg, output $msg, output $allow) This function is called once per item to determine who the user can view or manage.

$inkvg – the user to filter
$msg – error message
$allow – if 1, this user is displayed and available
– if 0, this user is not displayed and is unavailable

Examples

Using integer for $detail:

 function OnFilterInit( const $inkvg, output $detail ) 
 { 
    $detail = 0; // 0 means no need for detail info, if 1, detail info will be in inkvg for OnItemFilter 
 } 
                           
 function OnItemFilter( const $inkvg, output $msg, output $allow ) 
 { 
     $allow = 0; 
     var $id; 
     kvgGetValue( $inkvg, "id", $id ); 
     if( $id[0] == "w" ) 
     { 
         $allow = 1; 
     } 
     return 0; 
 }

Using KVGroup for $detail:

function OnFilterInit( const $inkvg, output $detail ) 
{ 
                           
    $detail = kvgCreate( "", "" ); 
    kvgAddValue( $detail, "needitemdetail", "1" ); 
} 
                           
function OnItemFilter( const $inkvg, output $msg, output $allow ) 
{ 
    $allow = 0; 
    var $id; 
    kvgGetValue( $inkvg, "id", $id ); 
    if( $id[0] == "w" ) 
    { 
        $allow = 1; 
    } 
    return 0; 
}

Write a custom keep user filter plugin

Requirements

See Writing plugins for general requirements.

Execution points

The plugin is called by the View and update profile (IDR) module and Help users (IDA) module before the user list is displayed. It is called multiple times if there are more users than the value of the RECORDS PER PAGE setting. The plugin runs with the number of users determined by the RECORDS PER PAGE at a time.

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.

KEEP USER FILTER Standard input/output mode

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

An event triggers a CGI program to call the plugin program or script and sends it standard user data.
The calling program continues to stream input from stdin, one item at a time until there are no more items.
For each item, the plugin returns the filter result to stdout.
The calling program receives the final standard output and continues.

Input

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

"" "" = {
  "sessionid" = "<session ID>" # The session ID of the requester.
                     
  "module" = "<idr|ids|idp|idwfm>"
                     
  "navigation" "" = { ... } # User navigation data
  "recipient" "<user|empty>" = {
                     
     # The "recipient" group contains standard information about the
                     
     # subject of the request.
   }
  "viewer" "user" = {
     # The "viewer" group contains standard information about the
     # person using the CGI.
   }
  "request" "" = {
     # The "request" group contains standard information about the
     # the request.
   }
 }

Some of the values above may be empty, due to the stage and type of the request.

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

"user" "" = {
    "id" = "Dave-Appla"
    "name" = "Dave Appla"
    "filter" = "<true|false>"
    # true, if the user has been excluded by this plugin
    # false, otherwise
}

See User data for a description of the user KVGroup.

Output

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

"" "" = {
    "keep" = "true|false"
           # If false, the user is displayed
           # If true, the user is not displayed
    "retval" = "<#>"
           # Optional, if non-zero returned, abort the plugin
    "needitemdetail" = "1|0"
           # If 1, all details are displayed in the input of the next user.
           # If 0, only ID is displayed in the input of the next user. By
           # default, it is set to 1.
}

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.

KEEP USER FILTER Callback mode

In callback mode the keep user plugin uses two functions:

OnKeepInit(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, see the example below

OnItemKeep(const $inkvg, output $msg, output $allow) This function is called once per item to determine who the user can view or manage.

$inkvg – the user
$msg – error message
$allow – if 1, this user is displayed and available
– if 0, this user is not displayed and is unavailable

Examples

Using integer for $detail:

function OnKeepInit( const $inkvg, output $detail ) 
 { 
    $detail = 0; // 0 means no need for detail info, if 1, detail info will be in inkvg for OnItemKeep 
 } 
                           
 function OnItemKeep( const $inkvg, output $msg, output $allow ) 
 { 
     $allow = 0; 
     var $id; 
     kvgGetValue( $inkvg, "id", $id ); 
     if( $id[0] == "w" ) 
     { 
         $allow = 1; 
     } 
     return 0; 
 }

Using KVGroup for $detail:

function OnKeepInit( const $inkvg, output $detail ) 
{ 
    $detail = kvgCreate( "", "" ); 
    kvgAddValue( $detail, "needitemdetail", "1" ); 
} 
                           
function OnItemKeep( const $inkvg, output $msg, output $allow ) 
{ 
    $allow = 0; 
    var $id; 
    kvgGetValue( $inkvg, "id", $id ); 
    if( $id[0] == "w" ) 
    { 
        $allow = 1; 
    } 
    return 0; 
}

Write a custom user list generator plugin

Requirements

See Writing plugins for general requirements.

Execution points

The plugin is called by the View and update profile (IDR) module and Help users (IDA) module before the user list is displayed. It is called once when a user select page is first rendered. Users that are returned by the plugin are only available for selection. If the set of users is empty, the end user is not able to submit a request for anyone.

User list generation is similar to the filter plugins. This plugin supports support synchronous calling. There are two forms of synchronous 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.

GENERATE USER PLUGIN Standard input/output mode

In standard input/output (stdio) mode, a synchronous list generation plugin works in the following way:

An event triggers a CGI program to call the plugin program or script and sends it standard use data.
When the CGI program is ready to receive an object, it sends an empty KVGroup ( "" "" = { }) to the plugin program.
The plugin program sends a KVGroup that includes an object ID, or is empty to indicate end of list.
Steps 2 and 3 continue until the plugin sends an empty KVGroup to indicate end of list, or the objects generated reaches the limit required by the calling program.

Input

Input sent to the plugin is as follows:

"" "" = {
  "module" = "<idr|psw|ida>"
                     
  "navigation" "" = { ... } # User navigation data.
                     
  "recipient" "<user|empty>" = {
                     
     # The "recipient" group contains standard information about the
                     
     # subject of the request.
   }
  "viewer" "<user|admin>" = {
     # The "viewer" group contains standard information about the
     # person using the CGI.
   }
 }

Output

The list of users is passed from the plugin on stdout. A KVGroup is sent for each user.

The output KVGroup sent from the plugin must be as follows:

"" "" = {
  "userid" = "<profile ID>"
                     
      # Optional; This indicates the next user to add to the list of users
      # If omitted, this indicates there are no more users to add.
  "abort"  = "<true|false>" #If true, bypass the list generation plugin
  "errmsg" = "<text message>" # A message sent on an error
  "retval" = "0" # Mandatory; non-zero indicates failure
}

GENERATE USER PLUGIN Callback mode

In call back mode, the user generator uses two functions:

OnGeneratorInit(input $inkvg) This function is called once to initialize the environment based on the cgi user.

$inkvg – the viewer and module

GetGenList( output $list ) This function returns users that the user is able to view or manage.

$list – the array of user profile IDs

Example

  function OnGeneratorInit( input $inkvg )
  {
      log( "inkvg: " + kvgToString($inkvg ));
  }
  function GetGenList( output $list )
  {
      var $include_user[]
      $include_user[ size( $include_user ) ] = "AUSER1";
      $include_user[ size( $include_user ) ] = "AUSER2";
      $include_user[ size( $include_user ) ] = "AUSER3";
      $list = $include_user;
  }

In this section:

Filter users

Write a custom user filter plugin

FILTER USER PLUGIN Standard input/output mode

FILTER USER PLUGIN Callback mode

Write a custom keep user filter plugin

KEEP USER FILTER Standard input/output mode

KEEP USER FILTER Callback mode

Write a custom user list generator plugin

GENERATE USER PLUGIN Standard input/output mode

GENERATE USER PLUGIN Callback mode

Search results