Automatic assignment filtering
You can use a plugin to filter automatic resource assignment requests on a per-user basis.
To use an automatic assignment filter plugin:
Click Manage the system > Workflow > Options > Automation .
Type the name of the plugin program or PSLang script in the AUTO ASSIGNMENT VARIANCE FILTER field.
Click Update.
There are no shipped plugins for the automatic assignment filter plugin point.
Execution points
The automatic assignment filter plugin is run when the user attempts to view automatically assigned resources. The plugin is also run when the autores program executes.
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.
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
# See Navigation data.
"recipient" "<user|empty>" = {
# The "recipient" group contains standard information about the
# subject of the request.
# See Request data for details.
}
"viewer" "user" = {
# The "viewer" group contains standard information about the
# person using the CGI.
# See User data for details.
}
"request" "" = {
# The "request" group contains standard information about the
# the request.
# See Request data for details.
}
} 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. The automatic assignment filter plugin receives, for example:
"User" "" = {
"userid" = "AWaygood"
"Variance" "" = {
"type" = "group"
"id" = "1d05cb04-b2b7-4f09-9af9-e1b6733a98dc"
"hostid" = "AD"
"longid" = ""
"surplus" = "false"
"throttle" = "true"
}
"Variance" "" = {
"type" = "group"
"id" = "f1192163-80cc-47e3-9fc7-775af4173002"
"hostid" = "AD"
"longid" = ""
"surplus" = "true"
"throttle" = "true"
}
} 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.
The automatic assignment filter can optionally add and remove resources that will be requested in an additional request.
Returning the "User" "" = {} KVGroup with the desired modifications will alter the potential request. When this option is used any calculated variances will be discarded and the returned KVGroup will be used.
"" "" = {
"User" "" = {
"userid" = "AWaygood"
"Variance" "" = {
"type" = "group"
"id" = "f1192163-80cc-47e3-9fc7-775af4173002"
"hostid" = "AD"
"longid" = ""
"surplus" = "true"
"throttle" = "true"
}
"Variance" "" = {
"type" = "role"
"id" = "ROLE1"
"surplus" = "false"
"throttle" = "false"
}
}
} In callback mode the resource filter plugin uses two functions:
OnFilterInit(const $inkvg, output $detail)This function is called once to retrieve initial information about the request, requester, and viewer.$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 resource the user can view or manage.$inkvg – the resource to filter (each item is as found in Listing 8.4.4.1)
$msg – error message
$allow – if 1, this user is displayed and available
– if 0, this user is not displayed and is unavailable
Example
A simple example is as follows:
function OnFilterInit( const $inkvg, output $detail )
{
log ( kvgToString( $inkvg ))
$detail = 0;
return 0;
}
function OnItemFilter(const $inkvg, output $msg, output $allow )
{
log ( "OnItemFilter:" );
log ( kvgToString( $inkvg ))
$msg = ""; # Error message
$allow = 0; # not allowed
# $allow = 1; # allowed
return 0;
}