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 Novell Identity Manager 3.6.1 Policy guides 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 may 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 Novell 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 Novell Identity Manager 3.6.1 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 the address and ZIP code for users living in Provo, Utah.

  idm_queryinit
  idm_setqueryassociation (idm_geteventvalue "ASSOCIATION")
  idm_addsearchattr "City" "Provo"
  idm_addsearchattr "S" "UT"   # State
  idm_addreadattr "SA"          # Street Address
  idm_addreadattr "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 may need to do some debugging to track down problems. The following list indicates some facilities for debugging.

While 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.