Skip to main content

Generate managed group list

You can control who can view and select which managed groups by using a group list generation plugin. By default, end users and product administrators can select any managed group for a user. You may want to set up a restriction, for example, to allow a certain requester to select from a particular set of managed groups.

The group list generation plugin is a whitelist of accepted groups to manage. The filter plugin excludes groups like a blacklist.

If business logic can dictate an explicit list of groups that a user can select, then you can use the group list generation plugin. If the group list generated is significantly small in comparison to the groups that would be filtered out, this plugin is also preferred.

To use a group list generation plugin:

  1. Click Modules > Options.

  2. Type the name of the plugin program or PSLang script in the GENERATE GROUP PLUGIN field.

  3. Click Update.

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

Write a custom group list generation 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 managed group list is displayed. It is called once when a group select page is first rendered. Only groups that are returned by the plugin are available for selection. If the set of groups is empty, the end user is not able to select a group for anyone.

Groups list generation is similar to the filter plugins. This plugin supports synchronous calling. There are two forms of synchronous calling:

GENERATE GROUP PLUGIN Standard input/output mode

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

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

  2. When the CGI program is ready to receive an object, it sends an empty KVGroup ( "" "" = { }) to the plugin program.

  3. The plugin program sends a KVGroup that includes an object ID, or is empty to indicate end of list.

  4. 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|ida>"
                     
  "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 managed groups 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:

"" "" = {
  "groupiD" = "<group ID>"
      # Optional; This indicates the next managed group to add to the list of managed groups.
      # If omitted, this indicates there are no more managed groups to add.
  "grouptarget" = "Target ID>"
      # The target system on which the group membership is managed
  "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 GROUP PLUGIN callback mode

In callback mode the managed group list generation plugin uses two functions:

  • OnGeneratorInit( $inkvg ) This function retrieves the initial information about the request, requester and viewer.

  • GetGenList( $list ) This function returns an array of managed groups that the CGI will display.

Example

A simple example is as follows:

  function OnGeneratorInit( input $inkvg )
  {
      log( "inkvg: " + kvgToString($inkvg ));
  }
  function GetGenList( output $list )
  {
      var $include_group[]
      $include_group[ size( $include_group ) ] = "GROUP7";
      $include_group[ size( $include_group ) ] = "GROUP1";
      $list = $include_group;
  }
In this section: