Examples Of Obtaining Event Data

Example 1:

command='IDMGETVAR "COMMAND"'
# check for an add event
if [ "$command" = "add" ]; then
  # call the add script
  add.sh
fi

Example 2:

# obtain the event's association and CN attribute
ASSOCIATION=‘IDMGETVAR "ASSOCIATION"‘
CN='IDMGETVAR "ADD_CN"'
if [ "$CN" = "bob" ]; then
  # for "bob", check to see if he's been enabled
  ENABLE=‘IDMGETVAR "REMOVE_Login Disabled"‘
  if [ "$ENABLE" = "true" ]; then
    # bob is enabled again
    cmd="appenable -association $ASSOCIATION"
    EXEC "$cmd"
  fi
fi

Handling Associations

The association value indicates which identity has been changed. If the identity has no association, an association must be generated for it using an implementation-specific rule that you have adopted. When Identity Manager processes an event for an identity with no association, it executes the driver’s Matching policy. This policy attempts to match the event’s identity to an identity on the external application’s system. Usually doing this involves executing a query. The default Matching policy included with the Scripting driver queries for matching Users and Groups based on the CN attribute. If the event’s identity matches an identity on the external application, both identities must be assigned the new association. Assigning this association can be done as part of the query-handling script. (Handling queries is discussed in more detail in Handling Query Events.) If no identity matches, an Add event is issued, and the new association can be assigned as part of the Add event-handling script:

# Adding an association
IDMSETVAR "COMMAND" "ADD_ASSOCIATION"
IDMSETVAR "ASSOCIATION" "$MyAssociation"
IDMSETVAR "EVENT_ID" "$EVENT_ID"
IDMSETVAR "DEST_DN" "$SRC_DN"
IDMSETVAR "DEST_ENTRY_ID" "$SRC_ENTRY_ID"

The above example demonstrates each name/value pair that must be set for an association to be assigned by the Identity Manager engine. The values of EVENT_ID, SRC_DN and SRC_ENTRY_ID are always sent by the engine during an add event, and therefore, are available for your add script to obtain using IDMGETVAR. The example above also illustrates the IDMSETVAR function. For detailed information on how to use IDMSETVAR, see Section C.1, UNIX Shell (idmlib.sh) Reference. This function sets a name and value which indicates what action Identity Manager should perform. For example, the pair COMMAND and ADD_ASSOCIATION instructs the shim to create an add-association document to assign an association to an identity, as discussed above. The pair EVENT_ID and $EVENT_ID instruct the shim to assign add-association document an event-id described by the variable $EVENT_ID. This is important for the engine to match documents sent and returned on the subscriber channel.

The Subscriber can also issue MODIFY_ASSOCIATION and REMOVE_ASSOCIATION commands:

# Removing an association
IDMSETVAR "COMMAND" "REMOVE_ASSOCIATION"
IDMSETVAR "ASSOCIATION" "$MyAssociation"
IDMSETVAR "EVENT_ID" "$EVENT_ID"
IDMSETVAR "DEST_DN" "$SRC_DN"
IDMSETVAR "DEST_ENTRY_ID" "$SRC_ENTRY_ID"

# Modifying an association
IDMSETVAR "COMMAND" "MODIFY_ASSOCIATION"
IDMSETVAR "ASSOCIATION" "$OldAssociation"
IDMSETVAR "ASSOCIATION" "$NewAssociation"
IDMSETVAR "EVENT_ID" "$EVENT_ID"
IDMSETVAR "DEST_DN" "$SRC_DN"
IDMSETVAR "DEST_ENTRY_ID" "$SRC_ENTRY_ID"

Returning an Event Status

On the Subscriber channel, you often do not need Identity Manager to perform an action, but simply need to report a status. The STATUS_ subroutines noted below can be used to indicate a status to Identity Manager. They take a message to be logged as their parameter.

Examples Using the STATUS Functions

Example 1:

EXEC "$cmd"
if [ $? -eq 0 ]; then
  STATUS_SUCCESS "Command was successful"
fi

Example 2:

EXEC "$cmd"
if [ $? -eq 0 ]; then
  if [ -z "$password" ]; then
    # created, but no password
    STATUS_WARNING "User added without password"
  fi
fi

Example 3:

EXEC "$cmd"
if [ $? -ne 0 ]; then
  STATUS_ERROR "Command failed"
fi

Writing Values

IDMSETVAR is used to set values to return to Identity Manager. For detailed information on how tus IDMSETVAR, see Section C.1, UNIX Shell (idmlib.sh) Reference. It is passed a name and value. In the previous ADD_ASSOCIATION example, IDMSETVAR is used to set the ASSOCIATION value. You can specify values for items listed in the table above. Generally, the only time IDMSETVAR is used is to add, modify and delete associations or return information for a query operation. Other information returned to the shim by the scripts is done through other command functions, such as STATUS_SUCCESS, which use IDMSETVAR indirectly.

Handling Query Events

For Query events, Identity Manager submits values that define the parameters of a search of the external application’s identity management system. Queries are usually issued from the Policies you have defined for your system. The table below specifies values that can be specified in queries. Not all values are relevant to your external application.

Execute the query against the external application using application-provided tools. Then return each identity by setting an INSTANCE command, followed by relevant values from the list below.

After returning all identities, call STATUS_SUCCESS to indicate a successful query.

Subscriber Summary and Examples

Below is a more detailed summary of the actions to take for a non-Query event.

Below is an example add.sh, which forms an association from an identity’s CN and class name, and uses a hypothetical tool called appadd.

#!/bin/sh
ClassName=`IDMGETVAR "CLASS_NAME"` CN=`IDMGETVAR "CN"`
EVENT_ID=`IDMGETVAR "EVENT_ID"`
SRC_DN=`IDMGETVAR "SRC_DN"`
SRC_ENTRY_ID=`IDMGETVAR "SRC_ENTRY_ID"`
PhoneNumber=`IDMGETVAR "Telephone"`

if [ -z "$ClassName" -o -z "$CN" ]; then
  STATUS_ERROR "Add event: missing CLASS_NAME and/or CN"
else
  Command="appadd -n $CN -t $PhoneNumber"
  EXEC $Command
  if [ $? -eq 0 ]; then 
    IDMSETVAR "COMMAND" "ADD_ASSOCIATION"
    IDMSETVAR "ASSOCIATION" $CN $ClassName
    IDMSETVAR "EVENT_ID" "$EVENT_ID"
    IDMSETVAR "DEST_DN" "$SRC_DN"
    IDMSETVAR "DEST_ENTRY_ID" "$SRC_ENTRY_ID"

    STATUS_SUCCESS "Add event succeeded"
  else
    STATUS_ERROR "Add event failed with error code $RC"
  fi
fi

Handling a query is a similar process, except that you return INSTANCE items rather than using other commands. Below is an example query.sh that searches an external application for a telephone number. It uses a hypothetical tool called appsearch.

#!/bin/sh
SearchName=`IDMGETVAR "SEARCH_ATTR_CN"`
EVENT_ID=`IDMGETVAR "EVENT_ID"`
ASSOCIATION=`IDMGETVAR "ASSOCIATION"`
CLASS_NAME=`IDMGETVAR "CLASS_NAME"`

if [ -z "$SearchName" ]; then
  STATUS_ERROR "Query: no search value"
else
  Command="appsearch -n $SearchName"
  Results=`$Command`
  if [ -n "$Results" ]; then
  Phone=`echo $Results | awk '{print $1}'`
  IDMSETVAR "COMMAND" "INSTANCE"
  IDMSETVAR "EVENT_ID" "$EVENT_ID"
  IDMSETVAR "CLASS_NAME" "$CLASS_NAME"
  IDMSETVAR "ASSOCIATION" "$ASSOCIATION"
  IDMSETVAR "ATTR_Telephone" "$Phone"

  STATUS_SUCCESS "Query succeeded"
  else
    # Return success with no results
    STATUS_SUCCESS "Query succeeded (no matches)"
  fi
fi

Polling for Application Events

The Driver calls poll.sh to detect application events. Implement poll.sh as follows:

The following is an example of a poll.sh that checks for a password change. It uses a hypothetical application tool called appchg.

#!/bin/sh
# look for password changes
Results=`appchg --passwd-changes`
for Result in $Results; do
  # Entries are in the format "association:password"
  Association=`echo $Result | awk -F: '{print $1}'`
  Password=`echo $Result | awk -F: '{print $2}'`

  # submit a password change event
  usclh -t modify-password -a $Association <<EOF
$Password
EOF
done

# look for attribute values being added to each user
Results=`appchg --add-attr-changes`
for Result in $Results; do
  # Entries are in the format "association:attribute:value"
  Association=`echo $Result | awk -F: '{print $1}'`
  Attribute=`echo $Result | awk -F: '{print $2}'`
  Value=`echo $Result | awk -F: '{print $3}'`

  # submit the added attribute value
  usclh -t modify -c User -a $Association <<EOF
ADD_$Attribute=$Value
EOF
done

# look for attribute values being removed from each user
Results=`appchg --remove-attr-changes`
for Result in $Results; do
  # Entries are in the format "association:attribute:value"
  Association=`echo $Result | awk -F: '{print $1}'`
  Attribute=`echo $Result | awk -F: '{print $2}'`
  Value=`echo $Result | awk -F: '{print $3}'`

  # submit the removed attribute value
  usclh -t modify -c User -a $Association <<EOF
REMOVE_$Attribute=$Value
EOF
done

In the above example, three separate events are submitted to the publisher change log using the change log tool, usclh. The first invocation submits a modify-password event to be published. The second event submits a modify event to be published for an attribute add. The third invocation submits another modify event to be published for an attribute removal. The second and third invocations can be combined into a single modify event, if desired.

Events submitted using usclh are processed through your driver’s Publisher channel policies. See your Identity Manager 4.5 Policy guides for more information.

Using the Heartbeat Script

Another script executed in the Publisher Channel is heartbeat.sh. This script is executed when the Publisher Channel is idle for the interval specified in the Driver parameters. (You can set the interval to 0 so no heartbeat is issued.) You can use the heartbeat to check the availability of the external system or do “idle state” tasks. The HEARTBEAT_SUCCESS, HEARTBEAT_WARNING, and HEARTBEAT_ERROR subroutines can be used to indicate the result of the heartbeat. Below is an example based on a hypothetical tool called apphealth.

  apphealth
  RC=$?
  if [ $RC -eq 0 ]; then
    HEARTBEAT_SUCCESS "Heartbeat succeeded"
  else
    HEARTBEAT_ERROR "Heartbeat failed with error code $RC"
  fi

The response to the heartbeat is implementation-dependent, and can be defined in Policies or in the script itself. You could send a message to auditing using NetIQ Audit. You could store a value in a file, and have Subscriber scripts read the file and call STATUS_RETRY if they find that value in the file.

Driver Parameters

A driver has values known as driver parameters. The driver parameters are divided into driver settings applicable to the whole driver, and Subscriber and Publisher settings for their respective channels. The IDMGETDRVVAR, IDMGETSUBVAR, and IDMGETPUBVAR functions can be used to retrieve these values. The table below shows parameters in the default Scripting driver. Other parameters can be added to the driver’s XML configuration file see “Managing Identity Manager Drivers” in the Identity Manager Administration Guide).

In the following example, a script retrieves the Publisher polling interval.

  PollingInterval=`IDMGETPUBVAR "pub-polling-interval"`

Querying the Identity Vault

Scripts might need to retrieve information from the Identity Vault. They can do this by issuing a query.

Query support is currently limited. It only returns one instance based on the specified association or DN. (If both association and DN are specified, association is used.) The functions below allow you to retrieve information from the instance.

The following is an example of a query of the Identity Vault that retrieves the address and ZIP code for user Bob.

  IDMQUERY "User" "Bob" "SA,Postal Code"

  Address=`IDMGETQVAR "SA"`
  ZIPCode=`IDMGETQVAR "Postal Code"`
  # ... etc. ...

Tracing and Debugging

The IDMTRACE function allows you to write a message to the Trace Log. Tracing is useful for script debugging and auditing.

  IDMTRACE "Trace message"

When developing scripts, you might need to do some debugging to track down problems. The following list indicates some facilities for debugging.

Although it is best to start the driver in production environments from the startup script, you can run usdrv manually. When you do so, any text written to standard output from scripts is displayed in the interactive shell.

Examples Of Obtaining Event Data

Example 1:

my $idmlib = new IDMLib();
my $command = $idmlib->idmgetvar("COMMAND");
# check for an add event
if ($command eq "add") {
  # call the add script
  do add.pl;
}

Example 2:

my $idmlib = new IDMLib();
# obtain the event's association and CN attribute
my $association = $idmlib->idmgetvar("ASSOCIATION");
my $CN = $idmlib->idmgetvar("CN");
if ($CN eq "bob") {
  # for "bob", check to see if he's been enabled
  my $ENABLE = $idmlib->idmgetvar("REMOVE_Login Disabled");
  if ($ENABLE eq "true") {
    # bob is enabled again
    cmd="appenable -association ". $ASSOCIATION
    $idmlib->exec($cmd);
  }
}

Handling Associations

The association value indicates which identity has been changed. If the identity has no association, an association must be generated for it using an implementation-specific rule that you have adopted. When Identity Manager processes an event for an identity with no association, it executes the driver’s Matching policy. This policy attempts to match the event’s identity to an identity on the external application’s system. Doing this usually involves executing a query. The default Matching policy included with the Scripting driver queries for matching Users and Groups based on the CN attribute. If the event’s identity matches an identity on the external application, both identities must be assigned the new association. Assigning this association can be done as part of the query-handling script. (Handling queries is discussed in Handling Query Events.) If no identity matches, an Add event is issued, and the new association can be assigned as part of the Add event-handling script:

# Adding an association
my $idmlib = new IDMLib();
$idmlib->idmsetvar("COMMAND", "ADD_ASSOCIATION");
$idmlib->idmsetvar("ASSOCIATION", $MyAssociation);
$idmlib->idmsetvar("EVENT_ID", $EVENT_ID);
$idmlib->idmsetvar("DEST_DN", $SRC_DN);
$idmlib->idmsetvar("DEST_ENTRY_ID", $SRC_ENTRY_ID);

The above example demonstrates each name/value pair that must be set for an association to be assigned by the Identity Manager engine. The values of EVENT_ID, SRC_DN and SRC_ENTRY_ID are always sent by the engine during an add event, and therefore, are available for your add script to obtain using $idmlib->idmgetvar(). The example above also illustrates the $idmlib->idmsetvar() function. For detailed information on how to use $idmlib->idmsetvar(), see Section C.2, Perl (IDMLib.pm) Reference. This function sets a name and value which indicates what action Identity Manager should perform. For example, the pair COMMAND and ADD_ASSOCIATION instructs the shim to create an add-association document to assign an association to an identity, as discussed above. The pair EVENT_ID and $EVENT_ID instruct the shim to assign add-association document an event-id described by the variable $EVENT_ID. This is important for the engine to match documents sent and returned on the subscriber channel.

The Subscriber can also issue MODIFY_ASSOCIATION and REMOVE_ASSOCIATION commands:

# Removing an association
my $idmlib = new IDMLib();
$idmlib->idmsetvar("COMMAND", "REMOVE_ASSOCIATION");
$idmlib->idmsetvar("ASSOCIATION", $MyAssociation);
$idmlib->idmsetvar("EVENT_ID", $EVENT_ID);
$idmlib->idmsetvar("DEST_DN", $SRC_DN);
$idmlib->idmsetvar("DEST_ENTRY_ID", $SRC_ENTRY_ID);

# Modifying an association
my $idmlib = new IDMLib();
$idmlib->idmsetvar("COMMAND", "MODIFY_ASSOCIATION");
$idmlib->idmsetvar("ASSOCIATION", $OldAssociation);
$idmlib->idmsetvar("ASSOCIATION", $NewAssociation);
$idmlib->idmsetvar("EVENT_ID", $EVENT_ID);
$idmlib->idmsetvar("DEST_DN", $SRC_DN);
$idmlib->idmsetvar("DEST_ENTRY_ID", $SRC_ENTRY_ID);

Returning an Event Status

On the Subscriber channel, you often do not need Identity Manager to perform an action, but simply need to report a status. The STATUS_ subroutines noted below can be used to indicate a status to Identity Manager. They take a message to be logged as the parameter.

Examples Using the Status() Functions

$idmlib->exec($cmd);
if ($? == 0) {
  $idmlib->status_success("Command was successful");
}
$idmlib->exec($cmd);
if ($? == 0) {
  if ($password eq '') {
    # created, but no password
    $idmlib->status_warning("User added without password");
  }
}
$idmlib->exec($cmd);
if ($? != 0) {
  $idmlib->status_error("Command failed");
}

Writing Values

$idmlib->idmsetvar() is used to set values to return to Identity Manager. It is passed a name and value. For detailed information on how to use $idmlib->idmsetvar(), see Section C.2, Perl (IDMLib.pm) Reference. In the previous ADD_ASSOCIATION example, $idmlib->idmsetvar() is used to set the ASSOCIATION value. You can specify values for items listed in the table above. Generally, $idmlib->idmsetvar() is used is to add, modify and delete associations or return information for a query operation. Other information is returned to the shim through other command functions, such as status_success(), which use IDMSETVAR indirectly.

Handling Query Events

For Query events, Identity Manager submits values that define the parameters of a search of the external application’s identity management system. Queries are usually issued from the Policies you have defined for your system. The table below specifies values that can be specified in queries. Not all values are relevant to your external application.

Execute the query against the external application using application-provided tools. Then return each identity by setting an INSTANCE command, followed by relevant values from the list below.

After returning all identities, call $idmlib->status_success() to indicate a successful query.

Subscriber Summary and Examples

Below is a more detailed summary of the actions to take for a non-Query event.

Below is an example add.pl, which forms an association from an identity’s CN and class name, and uses a hypothetical tool called appadd.

#!/usr/bin/perl

use IDMLib;
my $idmlib = new IDMLib();
my $ClassName = $idmlib->idmgetvar("CLASS_NAME");
my $CN = $idmlib->idmgetvar("CN");
my $PhoneNumber = $idmlib->idmgetvar("Telephone");
my $EVENT_ID = $idmlib->idmgetvar("EVENT_ID");

if (($ClassName eq '') || ($CN eq '')) {
  $idmlib->status_error( "Add event: missing CLASS_NAME and/or CN" );
} else {
  my $Command = "appadd -n $CN -t $PhoneNumber";
  my $rc = $idmlib->exec( $Command ); 
  if ( $rc == 0 ) {
    $idmlib->idmsetvar("COMMAND", "ADD_ASSOCIATION");
    $idmlib->idmsetvar("ASSOCIATION", $CN . $ClassName);
    $idmlib->idmsetvar("EVENT_ID", $EVENT_ID);
    $idmlib->idmsetvar("DEST_DN", $SRC_DN);
    $idmlib->idmsetvar("DEST_ENTRY_ID", $SRC_ENTRY_ID);

    $idmlib->status_success( "Add event succeeded" );
  } else {
    $idmlib->status_error( "Add event failed with error code" . $rc );
  }
}

Handling a query is a similar process, except that you return INSTANCE items rather than using other commands. Below is an example query.pl that searches an external application for a telephone number. It uses a hypothetical tool called appsearch.

#!/usr/bin/perl

use IDMLib;
my $idmlib = new IDMLib();
my $SearchName = $idmlib->idmgetvar("SEARCH_ATTR_CN");
my $EVENT_ID = $idmlib->idmgetvar("EVENT_ID");
my $ASSOCIATION = $idmlib->idmgetvar("ASSOCIATION");
my $CLASS_NAME = $idmlib->idmgetvar("CLASS_NAME");

if ($SearchName eq "") {
  $idmlib->status_error( "Query: no search value" );
} else {
  my $Command = "appsearch -n ". $SearchName;
  $Results = `$Command`;
  if ($Results ne "") {
    my @phoneinfo = split(" ", $Results);
    my $Phone = $phoneinfo[0]; 

    $idmlib->idmsetvar("COMMAND", "INSTANCE");
    $idmlib->idmsetvar("CLASS_NAME", $CLASS_NAME);
    $idmlib->idmsetvar("EVENT_ID", $EVENT_ID);
    $idmlib->idmsetvar("ASSOCIATION", $ASSOCIATION);
    $idmlib->idmsetvar("ATTR_Telephone", $Phone);

    $idmlib->status_success( "Query succeeded" );
  } else {
    # Return success with no results
    $idmlib->status_success( "Query succeeded (no matches)" );
  }
}

Polling for Application Events

The Driver calls poll.pl to detect application events. poll.pl should be implemented as follows:

Below is an example of a poll.pl that checks for a password change. It uses a hypothetical application tool called appchg.

  #!/usr/bin/perl
  
  use IDMLib;
  $my idmlib = new IDMLib();
   my $Results = `appchg --passwd-changes`;
  foreach $Result ( split("\n", $Results) ) {
    # Entries are in the format "association:password"
    ($Association, $Password) = split(":", $Result);
    `usclh -t modify-password -a $Association <<EOF
$Password
EOF`;
  }

  # look for attribute values being added to each user
  $Results = `appchg --add-attr-changes`;
  foreach $Result ( split("\n", $Results) ) {
    # Entries are in the format "association:attribute:value"
    ($Association, $Attribute, $Value) = split(":", $Result);
    `usclh -t modify -c User -a $Association <<EOF
ADD_$Attribute=$Value
EOF`;
  }

  # look for attribute values being removed from each user
  $Results = `appchg --remove-attr-changes`;
  foreach $Result ( split("\n", $Results) ) {
    # Entries are in the format "association:attribute:value"
    ($Association, $Attribute, $Value) = split(":", $Result);
    `usclh -t modify -c User -a $Association <<EOF
REMOVE_$Attribute=$Value
EOF`;
  }

In the above example, three separate events are submitted to the publisher change log, using the change log tool, usclh. The first invocation submits a modify-password event to be published. The second event submits a modify event to be published for an attribute add. The third invocation submits another modify event to be published for an attribute removal. The second and third invocations can be combined into a single modify event, if desired.

Events submitted using usclh are processed through your driver’s Publisher Channel’s policies. See the Identity Manager policy guides on the Identity Manager 4.5 Documentation Web site for more information.

Using the Heartbeat Script

Another script executed in the Publisher Channel is heartbeat.pl. This script is executed when the Publisher Channel is idle for the interval specified in the Driver parameters. (You can set the interval to 0 so no heartbeat is issued.) You can use the heartbeat to check the availability of the external system or do “idle state” tasks. The $idmlib->heartbeat_success(), $idmlib->heartbeat_warning(), and $idmlib->heartbeat_error() subroutines can be used to indicate the result of the heartbeat. Below is an example based on a hypothetical tool called apphealth.

my $idmlib = new IDMLib();
my $rc = `apphealth`;
if ($rc == 0) {
  $idmlib->heartbeat_success("Heartbeat succeeded");
} else {
  $idmlib->heartbeat_error("Heartbeat failed with error code " . $rc);
}

The response to the heartbeat is implementation-dependent, and can be defined in policies or in the script itself. You could send a message to auditing using NetIQ Audit. You could store a value in a file and have Subscriber scripts read the file and call $idmlib->heartbeat_retry() if they find that value in the file.

Driver Parameters

A driver has values known as driver parameters. The driver parameters are divided into driver settings applicable to the whole driver, and Subscriber and Publisher Settings for their respective channels. The $idmlib->idmgetdrvvar(), $idmlib->idmgetsubvar()and $idmlib->idmgetpubvar() functions can be used to retrieve these values. The table below shows parameters in the default Scripting driver. Other parameters can be added to the driver’s XML Configuration file (see the NetIQ Identity Manager Administration Guide).

In the following example, a script retrieves the Publisher polling interval.

  my $PollingInterval = $idmlib->idmgetpubvar("pub-polling-interval");

Querying the Identity Vault

Scripts might need to retrieve information from the Identity Vault. They can do this by issuing a query.

Query support is currently limited. It returns only one instance based on the specified association or DN. If both association and DN are specified, association is used. The functions below allow you to retrieve information from the instance.

The following is an example of a query of the Identity Vault that retrieves the address and ZIP code for user Bob.

my $idmlib = new IDMLib();
$idmlib->idmquery("User", "Bob", "SA,Postal Code");

my $Address = $idmlib->idmgetqvar( "SA" );
my $ZIPCode = $idmlib->idmgetqvar( "Postal Code" );
# ... etc. ...

Tracing and Debugging

The function IDMTRACE allows you to write a message to the Trace Log. Tracing is useful for script debugging and auditing.

  $idmlib->trace("Trace Message");

When you develop scripts, you might need to do some debugging to track down problems. The following list indicates some facilities for debugging.

Although it is best to start the driver in production environments from the startup script, you can run usdrv manually. When you do so, any text written to standard output from scripts is displayed in the interactive shell.

Examples Of Obtaining Event Data

Example 1:

from idmlib import *

command = idmgetvar("COMMAND")
# check for an add event
if command = "add":
  # call the add script
  os.system("add.py")

Example 2:

from idmlib import *

# obtain the event's association and CN attribute
association = idmgetvar("ASSOCIATION")
CN = idmgetvar("CN")
if CN = "bob":
  # for "bob", check to see if he's been enabled
  ENABLE = idmgetvar("REMOVE_Login Disabled")
  if ENABLE = "true":
    # bob is enabled again
    cmd = "appenable -association " + ASSOCIATION
    exec(cmd)

Handling Associations

The association value indicates which identity has been changed. If the identity has no association, an association must be generated for it using an implementation-specific rule that you have adopted. When Identity Manager processes an event for an identity with no association, it executes the driver’s Matching policy. This policy attempts to match the event’s identity to an identity on the external application’s system. Doing this usually involves executing a query. The default Matching policy included with the Scripting driver queries for matching Users and Groups based on the CN attribute. If the event’s identity matches an identity on the external application, both identities must be assigned the new association. Assigning this association can be done as part of the query-handling script. (Handling queries is discussed in Handling Query Events.) If no identity matches, an Add event is issued, and the new association can be assigned as part of the Add event-handling script:

# Adding an association
from idmlib import *

idmsetvar("COMMAND", "ADD_ASSOCIATION")
idmsetvar("ASSOCIATION", MyAssociation)
idmsetvar("EVENT_ID", EVENT_ID)
idmsetvar("DEST_DN", SRC_DN)
idmsetvar("DEST_ENTRY_ID", SRC_ENTRY_ID)

The above example demonstrates each name/value pair that must be set for an association to be assigned by the Identity Manager engine. The values of EVENT_ID, SRC_DN and SRC_ENTRY_ID are always sent by the engine during an add event, and therefore, are available for your add script to obtain using idmgetvar(). The example above also illustrates the idmsetvar() function. For detailed information on how to use idmsetvar(), see Section C.3, Python (idmlib.py) Reference. This function sets a name and value which indicates what action Identity Manager should perform. For example, the pair “COMMAND" and “ADD_ASSOCIATION" instructs the shim to create an add-association document to assign an association to an identity, as discussed above. The pair "EVENT_ID” and EVENT_ID instruct the shim to assign add-association document an event-id described by the variable EVENT_ID. This is important for the engine to match documents sent and returned on the subscriber channel.

The Subscriber can also issue MODIFY_ASSOCIATION and REMOVE_ASSOCIATION commands:

# Removing an association
from idmlib import *

idmsetvar("COMMAND", "REMOVE_ASSOCIATION")
idmsetvar("ASSOCIATION", MyAssociation)
idmsetvar("EVENT_ID", EVENT_ID)
idmsetvar("DEST_DN", SRC_DN)
idmsetvar("DEST_ENTRY_ID", SRC_ENTRY_ID)

# Modifying an association
my idmlib import *

idmsetvar("COMMAND", "MODIFY_ASSOCIATION")
idmsetvar("ASSOCIATION", OldAssociation)
idmsetvar("ASSOCIATION", NewAssociation)
idmsetvar("EVENT_ID", EVENT_ID)
idmsetvar("DEST_DN", SRC_DN)
idmsetvar("DEST_ENTRY_ID", SRC_ENTRY_ID)

Returning an Event Status

On the Subscriber channel, you often do not need Identity Manager to perform an action, but simply need to report a status. The status_ subroutines noted below can be used to indicate a status to Identity Manager. They take a message to be logged as the parameter.

Examples Using the Status() Functions

rc = exec(cmd)
if (rc = 0):
  status_success("Command was successful")
rc = exec(cmd)
if (rc == 0):  
  if (password eq "")
    # created, but no password
    status_warning("User added without password")

rc = exec(cmd)
if (rc != 0):
  status_error("Command failed")

Writing Values

The idmsetvar() function is used to set values to return to Identity Manager. It is passed a name and value. For detailed information on how to use idmsetvar(), see Section C.3, Python (idmlib.py) Reference. In the previous ADD_ASSOCIATION example, idmsetvar() is used to set the ASSOCIATION value. You can specify values for items listed in the table above. Generally, idmsetvar() is used is to add, modify and delete associations or return information for a query operation. Other information is returned to the shim through other command functions, such as status_success(), which use idmsetvar() indirectly.

Handling Query Events

For Query events, Identity Manager submits values that define the parameters of a search of the external application’s identity management system. Queries are usually issued from the Policies you have defined for your system. The table below specifies values that can be specified in queries. Not all values are relevant to your external application.

When a query invokes your query script, use the parameter information to query your external application using application-provided tools. Then return each identity by setting an INSTANCE command, followed by relevant values from the list below.

After returning all identities, call status_success() to indicate a successful query.

Subscriber Summary and Examples

Below is a more detailed summary of the actions to take for a non-Query event.

Below is an example add.py, which forms an association from an identity’s CN and class name, and uses a hypothetical tool called appadd.

#!/usr/bin/python

from idmlib import *

ClassName = idmgetvar("CLASS_NAME")
CN = idmgetvar("CN")
PhoneNumber = idmgetvar("Telephone")
EventId = idmgetvar("EVENT_ID")
SrcDn = idmgetvar("SRC_DN")
SrcEntryId = idmgetvar("SRC_ENTRY_ID")
if ClassName = "" || CN = "":
  status_error("Add event: missing CLASS_NAME and/or CN")
else:
  Command = "appadd -n " + CN + -t " + PhoneNumber
  rc = exec(Command) 
  if rc = 0:
    idmsetvar("COMMAND", "ADD_ASSOCIATION")
    idmsetvar("ASSOCIATION", CN + ClassName)
    idmsetvar("EVENT_ID", EventId)
    idmsetvar("DEST_DN", SrcDn)
    idmsetvar("DEST_ENTRY_ID", SrcEntryId)
    status_success("Add event succeeded")
  else:
    status_error("Add event failed with error code" + rc)

Handling a query is a similar process, except that you return INSTANCE items rather than using other commands. Below is an example query.py that searches an external application for a telephone number. It uses a hypothetical tool called appsearch.

#!/usr/bin/python

import os
from idmlib import *

SearchName = idmgetvar("SEARCH_ATTR_CN")
EventId = idmgetvar("EVENT_ID")
Association = idmgetvar("ASSOCIATION")
ClassName = idmgetvar("CLASS_NAME")
if SearchName = "":
  status_error("Query: no search value")
else:
  Command = "appsearch -n " + SearchName
  Results = os.popen(Command, ‘r').readlines()
  if Results != "":
    phoneinfo = split(" ", Results)
    Phone = phoneinfo[0]
    idmsetvar("COMMAND", "INSTANCE")
    idmsetvar("CLASS_NAME", ClassName)
    idmsetvar("EVENT_ID", EventId)
    idmsetvar("ASSOCIATION", Association)
    idmsetvar("ATTR_Telephone", Phone)
    status_success("Query succeeded")
  else:
    # Return success with no results
    status_success("Query succeeded (no matches)")

Polling for Application Events

The Driver calls poll.py to detect application events. poll.py should be implemented as follows:

Below is an example of a poll.py that checks for a password change. It uses a hypothetical application tool called appchg.

#!/usr/bin/python

import os
from idmlib import *

# look for password changes with our ficticious app, appchg
results = os.popen("appchg --passwd-changes", 'r').readlines()
for result in results:
  fields = result.split(":")
  Association = fields[0]
  Password = fields[1]
  # submit event to the publisher changelog
  usclh = os.popen(usclh -t modify-password -a " + Association, 'w')
  usclh.write(Password)
  usclh.close()

# look for attribute values being added to each user
results = os.popen("appchg --add-attr-changes")
for result in results:
  # Entries are in the format "association:attribute:value"
  fields = result.split(":")
  Association = fields[0]
  Attribute = fields[1]
  Value = fields[2]
  # submit event to the publisher changelog
  local_usclh = os.environ.get('INSTALL_PATH') + "bin/usclh"
  usclh = os.popen(local_usclh + " -t modify -c User -a " + Association, 'w')
  usclh.write("ADD_" + Attribute + "=" + Value)
  usclh.close()
 
# look for attribute values being removed from each user
results = os.popen("appchg --add-attr-changes")
for result in results:
  # Entries are in the format "association:attribute:value"
  fields = result.split(":")
  Association = fields[0]
  Attribute = fields[1]
  Value = fields[2]
  # submit event to the publisher changelog
  local_usclh = os.environ.get('INSTALL_PATH') + "bin/usclh"
  usclh = os.popen(local_usclh + " -t modify -c User -a " + Association, 'w')
  usclh.write("REMOVE_" + Attribute + "=" + Value)
  usclh.close()

In the above example, three separate events are submitted to the publisher change log, using the changelog tool, usclh. The first invocation submits a modify-password event to be published. The second event submits a modify event to be published for an attribute add. The third invocation submits another modify event to be published for an attribute removal. The second and third invocations can be combined into a single modify event, if desired.

Events submitted using usclh are processed through your driver’s Publisher Channel’s policies. See the Identity Manager policy guides on the Identity Manager 4.5 Documentation Web site for more information.

Using the Heartbeat Script

Another script executed in the Publisher Channel is heartbeat.py. This script is executed when the Publisher Channel is idle for the interval specified in the Driver parameters. (You can set the interval to 0 so no heartbeat is issued.) You can use the heartbeat to check the availability of the external system or do “idle state” tasks. The heartbeat_success(), heartbeat_warning(), and heartbeat_error() subroutines can be used to indicate the result of the heartbeat. Below is an example based on a hypothetical tool called apphealth.

from idmlib import *

rc = os.sytem("apphealth")
if (rc = 0):
  heartbeat_success("Heartbeat succeeded")
else:
  heartbeat_error("Heartbeat failed with error code " + rc)

Driver Parameters

A driver has values known as driver parameters. The driver parameters are divided into driver settings applicable to the whole driver, and Subscriber and Publisher Settings for their respective channels. The idmgetdrvvar(), idmgetsubvar()and idmgetpubvar() functions can be used to retrieve these values. The table below shows parameters in the default Scripting driver. Other parameters can be added to the driver’s XML Configuration file (see the NetIQ Identity Manager 3.6.1 Administration Guide).

In the following example, a script retrieves the Publisher polling interval:

 PollingInterval = idmgetpubvar("pub-polling-interval")

Querying the Identity Vault

Scripts might need to retrieve information from the Identity Vault. They can do this by issuing a query.

Query support is currently limited. It returns only one instance based on the specified association or DN. If both association and DN are specified, association is used. The functions below allow you to retrieve information from the instance.

The following is an example of a query of the Identity Vault that retrieves the address and ZIP code for user Bob.

from idmlib import *

idmquery("User", "Bob", "SA,Postal Code")
Address = idmgetqvar("SA")
ZIPCode = idmgetqvar("Postal Code")
# ... etc. ...

Tracing and Debugging

The function trace() allows you to write a message to the Trace Log. Tracing is useful for script debugging and auditing.

from idmlib import *

trace("Trace Message")

When you develop scripts, you might need to do some debugging to track down problems. The following list indicates some facilities for debugging.

Although it is best to start the driver in production environments from the startup script, you can run usdrv manually. When you do so, any text written to standard output from scripts is displayed in the interactive shell.

Handling Associations

The association value indicates which identity has been changed. If the identity has no association, an association must be generated for it using an implementation-specific rule that you have adopted. When Identity Manager processes an event for an identity with no association, it executes the driver’s Matching policy. This policy attempts to match the event’s identity to an identity on the external application’s system. Doing this usually involves executing a query. The default Matching policy included with the Scripting driver queries for matching Users and Groups based on the CN attribute. If the event’s identity matches an identity on the external application, both identities must be assigned the new association. Assigning this association can be done as part of the query-handling script. (Handling queries is discussed in Handling Query Events.) If no identity matches, an Add event is issued, and the new association can be assigned as part of the Add event-handling script:

   IDMSetCommand "ADD_ASSOCIATION"
   IDMWriteValue "ASSOCIATION", MyAssociation
              (etc.) 

The example above also illustrates the IDMSetCommand function. This function sets a command value which indicates what action Identity Manager should perform. The ADD_ASSOCIATION command assigns an association to an identity, as discussed above. The Subscriber can also issue MODIFY_ASSOCIATION and REMOVE_ASSOCIATION commands.

Returning an Event Status

On the Subscriber channel, you often do not need Identity Manager to perform an action, but simply need to report a status. The IDMStatus subroutines noted below can be used to indicate a status to Identity Manager. They take a message to be logged as the parameter.

Writing Values

IDMSetCommand and/or a status subroutine must be called before specifying values with IDMWriteValues. IDMWriteValues (or its single-valued version IDMWriteValue) is used to set values to return to Identity Manager. It is passed a value name and an array of values. In the ADD_ASSOCIATION example above, IDMWriteValue is used to set the ASSOCIATION value. You can specify values for items listed in the table above.

Handling Query Events

For Query events, Identity Manager submits values that define the parameters of a search of the external application’s identity management system. Queries are usually issued from the policies you have defined for your system. The table below specifies values that can be specified in queries. Not all values are relevant to your external application.

Execute the query against the external application using application-provided tools. Then return each identity by setting an INSTANCE command, followed by relevant values from the list below.

After returning all identities, call IDMStatusSuccess to indicate a successful query.

Subscriber Summary and Examples

Below is a more detailed summary of the actions to take for a non-Query event.

Below is an example of the Add.vbs script, which forms an association from an identity’s CN and class name, and uses a hypothetical tool called appadd.

Sub ADD
  ClassName = IDMGetEventValue("CLASS_NAME")
  CN = IDMGetEventValue("CN")
  PhoneNumber = IDMGetEventValue("Telephone")
  If IsEmpty(ClassName) Or IsEmpty(CN) Then
    IDMStatusError "Add event: missing CLASS_NAME and/or CN"
  Else 
    Command = "appadd -n """ & CN & """ -t """ & PhoneNumber & """"
    ExitCode = IDMExecute(Command)
    If ExitCode = 0 Then
      IDMSetCommand "ADD_ASSOCIATION"
      IDMWriteValue "ASSOCIATION", CN & ClassName    
      IDMWriteValue "DEST_DN", IDMGetEventValue("SRC_DN")
      IDMStatusSuccess "Add event succeeded"
    Else
      IDMStatusError "Add event failed with error code " & ExitCode
    End If
  End If
End Sub

Handling a query is similar, except you return INSTANCE items rather than use other commands. Below is an example Query.vbs that searches an external application for a telephone number. It uses a hypothetical tool called appsearch.

Sub QUERY
  SearchName = IDMGetEventValue("SEARCH_ATTR_CN")
  If IsEmpty(SearchName) Then
    IDMStatusError "Query: no search value"
  Else
    Command = "appsearch -n " & SearchName
    Results = IDMExecuteIO(Command, Empty)
    If Results(0) = 0 Then
      Phone = Results(1)
      IDMSetCommand "INSTANCE"
      IDMWriteValue "CLASS_NAME", IDMGetEventValue("CLASS_NAME")
      IDMWriteValue "ASSOCIATION", IDMGetEventValue("ASSOCIATION")
      IDMWriteValue "ATTR_Telephone", Phone
      IDMStatusSuccess "Query succeeded"
    Else
      ' Return success with no results
      IDMStatusSuccess "Query succeeded (no matches)"
    End If
  End If
End Sub

Polling for Application Events

The Driver calls Poll.wsf to detect application events. Poll.wsf should be implemented as follows:

IDMPublishInit takes a command name as its single parameter. Below is a list of valid command names for IDMPublishInit.

Below is an example of a Poll.wsf that checks for a password change. It uses a hypothetical application tool called apppwd.

  Results = IDMExecuteIO("apppwd --changes", Empty)
  For I = 1 To UBound(Results)
    ' Entries are in the format "association=password"
    Association = Left(Results(I), InStr(Results(I), "=")-1)
    Password = Mid(Results(I), InStr(Results(I), "=")+1)
    IDMPublishInit "MODIFY_PASSWORD"
    IDMPublishValue "ASSOCIATION", Association
    IDMPublishValue "PASSWORD", Password
      
    IDMPublish
  Next
  
  IDMStatusSuccess "Poll succeeded"

Events submitted using IDMPublish are processed through your driver’s Publisher channel policies. See the Identity Manager policy guides on the Identity Manager 4.5 Documentation Web site for more information.

Using the Heartbeat Script

Another script executed in the Publisher Channel is Heartbeat.wsf. This script is executed when the Publisher channel is idle for the interval specified in the driver parameters. (You can set the interval to 0 so no heartbeat is issued.) You can use the heartbeat to check the availability of the external system or do “idle state” tasks. The IDMHeartbeatSuccess, IDMHeartbeatWarning, and IDMHeartbeatError subroutines can be used to indicate the result of the heartbeat. Below is an example based on a hypothetical tool called apphealth.

  ExitCode = IDMExecute("apphealth")
  If ExitCode = 0 Then
    IDMHeartbeatSuccess "Heartbeat succeeded"
  Else
    IDMHeartbeatError "Heartbeat failed with error code " & ExitCode
  End If

The response to the heartbeat is implementation-dependent, and can be defined in policies or in the script itself. You could send a message to auditing using NetIQ Audit. You could store a value in a file, and have Subscriber scripts read the file and call IDMStatusRetry if they find that value in the file.

Driver Parameters

A driver has values known as driver parameters. The driver parameters are divided into driver settings applicable to the whole driver, and Subscriber and Publisher Settings for their respective channels. The IDMGetDriverParam, IDMGetSubscriberParam, and IDMGetPublisherParam functions can be used to retrieve these values. The table below shows parameters in the default Scripting driver. Other parameters can be added to the driver’s XML Configuration file (see “Managing Identity Manager Drivers” in the NetIQ Identity Manager Administration Guide).

In the following example, a script retrieves the Publisher polling interval.

  PollingInterval = IDMGetPublisherParam("pub-polling-interval")

Querying the Identity Vault

Scripts might need to retrieve information from the Identity Vault. On the Subscriber channel only, they can do this by issuing a query.

The following is an example of a query that retrieves an object’s address and postal code.

  IDMQueryInit
  IDMQuerySetAssociation IDMGetEventValue("ASSOCIATION")
  IDMQueryAddReadAttr "SA"          ' Street Address
  IDMQueryAddReadAttr "Postal Code"

  If IDMQuery Then
    Address = IDMQueryGetInstanceAttrValue("SA")
    ZIPCode = IDMQueryGetInstanceAttrValue("Postal Code")
    ' ... etc. ...
  End If

Tracing and Debugging

The IDMTrace function allows you to write a message to the Script Trace File specified in the Driver Parameters. Tracing is useful for script debugging and auditing.

   IDMTrace "Trace message" 

When developing scripts, you might need to do some debugging to track down problems. The following list indicates some facilities for debugging.

Although it is best to run the driver as a service in production environments, you can run wsdriver.exe as a standard program. When you do so, a console window displays trace messages (see above) for the driver. Also, text written to standard output from scripts (such as using WScript.Echo in VBScript) is displayed in this window.

VBScript programs can be debugged using programs such as Microsoft Visual Studio and Microsoft Script Debugger. Change the Script Command driver parameter to use the //x option: cscript //nologo //x. When the driver shim executes a script, you are prompted to debug the script execution.

Handling Associations

The association value indicates which identity has been changed. If the identity has no association, an association must be generated for it using an implementation-specific rule that you have adopted. When Identity Manager processes an event for an identity with no association, it executes the driver’s Matching policy. This policy attempts to match the event’s identity to an identity on the external application’s system. Doing this usually involves executing a query. The default Matching policy included with the Scripting driver queries for matching Users and Groups based on the CN attribute. If the event’s identity matches an identity on the external application, both identities must be assigned the new association. Assigning this association can be included as part of the query-handling script. (Handling queries is discussed in Handling Query Events.) If no identity matches, an Add event is issued, and the new association can be assigned as part of the Add event-handling script:

   idm_setcommand "ADD_ASSOCIATION"
   idm_writevalue "ASSOCIATION" $my_association
              (etc.) 

The example above also illustrates the idm_setcommand function. This function sets a command value that indicates what action Identity Manager should perform. The ADD_ASSOCIATION command assigns an association to an identity, as discussed above. The Subscriber can also issue MODIFY_ASSOCIATION and REMOVE_ASSOCIATION commands.

Returning an Event Status

On the Subscriber channel, you often do not need Identity Manager to perform an action, but simply need to report a status. The IDMStatus subroutines noted below can be used to indicate a status to Identity Manager. They take a message to be logged as the parameter.

Writing Values

idm_setcommand and the status functions must be issued before specifying values with idm_writevalues. idm_writevalues (or its single-valued version idm_writevalue) is used to set values to return to Identity Manager. It is passed a value name and an array of values. In the ADD_ASSOCIATION example above, idm_writevalue is used to set the ASSOCIATION value. You can specify values for items listed in the table above.

Handling Query Events

For Query events, Identity Manager submits values that define the parameters of a search of the external application’s identity management system. Queries are usually issued from the policies you have defined for your system. The table below specifies values that can be specified in queries. Not all values are relevant to your external application.

Execute the query against the external application using application-provided tools. Then return each identity by setting an INSTANCE command, followed by relevant values from the list below.

After returning all identities, call idm_statussuccess to indicate a successful query.

Subscriber Summary and Examples

Below is a more detailed summary of the actions to take for a non-Query event.

Below is an example of the Add.ps1 script, which forms an association from an identity’s CN and class name, and uses a hypothetical tool called appadd.

function idm_add
{
  $classname = idm_geteventvalue "CLASS_NAME"
  $cn = idm_geteventvalue "CN"
  $phone = idm_geteventvalue "Telephone"
  if ($classname -eq "" -or $cn -eq "") {
    idm_statuserror "Add event: missing CLASS_NAME and/or CN"
  }
  else { 
    appadd -n "$cn" -t "$phone"
    if ($LASTEXITCODE -eq 0) {
      idm_setcommand "ADD_ASSOCIATION"
      idm_writevalue "ASSOCIATION" "$cn$classname"    
      idm_writevalue "DEST_DN" (idm_geteventvalue "SRC_DN")
      idm_statussuccess "Add event succeeded"
    }
    else {
      idm_statuserror "Add event failed with error code $LASTEXITCODE"
    }
  }
}

Handling a query is similar, except you return INSTANCE items rather than use other commands. Below is an example Query.ps1 that searches an external application for a telephone number. It uses a hypothetical tool called appsearch.

function idm_query
{
  $searchname = idm_geteventvalue "SEARCH_ATTR_CN"
  if ($searchname -eq "") {
    idm_statuserror "Query: no search value"
  }
  else {
    # the telephone number is output from the application
    appsearch -n "$searchname" | Set-Variable phone
    if ($phone -ne $null) {
      idm_setcommand "INSTANCE"
      idm_writevalue "CLASS_NAME" (idm_geteventvalue "CLASS_NAME")
      idm_writevalue "ASSOCIATION" (idm_geteventvalue "ASSOCIATION")
      idm_writevalue "ATTR_Telephone" $phone
      idm_statussuccess "Query succeeded"
    }
    else {
      # Return success with no results
      idm_statussuccess "Query succeeded (no matches)"
    }
  }
}

Polling for Application Events

The driver calls Poll.ps1 to detect application events. Poll.ps1 should be implemented as follows:

idm_publishinit takes a command name as its single parameter. Below is a list of valid command names for idm_publishinit.

Below is an example of a Poll.ps1 that checks for a password change. It uses a hypothetical application tool called apppwd.

  apppwd --changes | Set-Variable results
  foreach ($result in $results) {
    # Entries are in the format "association=password"
    $tokens = $result.split("=")
    $association = $tokens[0]
    $password = $tokens[1]
    idm_publishinit "MODIFY_PASSWORD"
    idm_publishvalue "ASSOCIATION" $association
    idm_publishvalue "PASSWORD" $password
      
    idm_publish
  next
  
  idm_statussuccess "Poll succeeded"

Events submitted using idm_publish are processed through your driver’s Publisher channel policies. See the Identity Manager policy guides on the Identity Manager 4.5 Documentation Web site for more information.

Using the Heartbeat Script

Another script executed in the Publisher Channel is Heartbeat.ps1. This script is executed when the Publisher channel is idle for the interval specified in the driver parameters. (You can also set the interval to 0 so no heartbeat is issued.) You can use the heartbeat to check the availability of the external system or do “idle state” tasks. The idm_heartbeatsuccess, idm_heartbeatwarning, and idm_heartbeaterror subroutines can be used to indicate the result of the heartbeat. Below is an example based on a hypothetical tool called apphealth.

  apphealth
  if ($LASTEXITCODE -eq 0) {
    idm_heartbeatsuccess "Heartbeat succeeded"
  }
  else {
    idm_heartbeaterror "Heartbeat failed with error code $LASTEXITCODE"
  }

The response to the heartbeat is implementation-dependent, and can be defined in policies or in the script itself. You could send a message to auditing using NetIQ Audit. You could store a value in a file and have Subscriber scripts read the file and call idm_statusretry if they find that value in the file.

Driver Parameters

A driver has values known as driver parameters. The driver parameters are divided into driver settings applicable to the whole driver, and Subscriber and Publisher settings for their respective channels. The idm_getdriverparam, idm_getsubscriberparam, and idm_getpublisherparam functions can be used to retrieve these values. The table below shows parameters in the default Scripting driver. Other parameters can be added to the driver’s XML Configuration file (see “Managing Identity Manager Drivers” in the NetIQ Identity Manager Administration Guide).

In the following example, a script retrieves the Publisher polling interval.

  $pollinginterval = idm_getpublisherparam("pub-polling-interval")

Querying the Identity Vault

Scripts might need to retrieve information from the Identity Vault. They can do this by issuing a query.

This table lists functions for setting query search parameters.

Currently query support is limited. It will only return one instance based on the specified association or DN. (If both association and DN are specified, association is used.) The functions below allow you to retrieve information from the instance.

Following is an example of a query of the Identity Vault that retrieves an object’s address and postal code.

  idm_queryinit
  idm_querysetassociation (idm_geteventvalue "ASSOCIATION")
  idm_queryaddreadattr "SA"          # Street Address
  idm_queryaddreadattr "Postal Code"

  $result = idm_doquery
  if ($result) {
    $address = idm_querygetinstanceattrvalue "SA"
    $zipcode = idm_querygetinstanceattrvalue "Postal Code"
    # ... etc. ...
  }

Tracing and Debugging

The function idm_trace allows you to write a message to the Script Trace File specified in the Driver Parameters. Tracing is useful for script debugging and auditing.

   idm_trace "Trace message" 

If the driver shim is being run as a Windows Service, all output from scripts will also be recorded in the Script Trace File.

When developing scripts, you might need to do some debugging to track down problems. The following list indicates some facilities for debugging.

Although it is best to run the driver as a service in production environments, you can run wsdriver.exe as a standard program. When you do so, a console window displays trace messages (see above) for the driver. Also, text written to standard output from scripts is displayed in this window.