C.5 Windows PowerShell (IDMLib.ps1) Reference

The scripts are written using Windows PowerShell. They are located in the scripts\powershell folder below the folder where the driver was installed (C:\Program Files\Novell\WSDriver by default).

Subscriber events are submitted to Subscriber.ps1, which then calls the script for the event. Modify the ps1 file corresponding to the event type: Add.ps1, Modify.ps1, ModifyPassword.ps1, Delete.ps1, Move.ps1, Rename.ps1. Queries of the external system should be handled in Query.ps1.

The Publisher calls Poll.ps1 periodically. The frequency of the poll is determined by the Polling Interval driver parameter (60 seconds by default). Edit Poll.ps1 to allow the driver to respond to events in the external account management system.

The Publisher calls Heartbeat.ps1 periodically to determine whether the external account management system is responding correctly.

Topics discussing the built-in functions in IDMLib.ps1 are categorized as follows:

C.5.1 General Functions

function idm_getdriverparam($paramname)

Returns the string value for the Driver parameter specified by the string $paramname.

function idm_trace($message)

Appends the specified message to the user-defined trace file.

function idm_status($level, $message)

Set the status level and message to return to the Identity Manager engine when the script completes.

function idm_statussuccess($message)

Set the status success message to return to the Identity Manager engine when the script completes.

function idm_statuswarning($message)

Set the status warning message to return to the Identity Manager engine when the script completes.

function idm_statusretry($message)

Set the status retry message to return to the Identity Manager engine when the script completes.

function idm_statuserror($message)

Set the status error message to return to the Identity Manager engine when the script completes.

function idm_statusfatal($message)

Set the status fatal message to return to the Identity Manager engine when the script completes.

C.5.2 Subscriber Functions

function idm_getsubscriberparam($paramname)

Returns the string value for the Subscriber parameter specified by the string $paramname.

function idm_setcommand($command)

Sets the command that the Subscriber returns to the Identity Manager engine. This function must be called before using idm_writevalue functions. If only a status needs to be returned, use one of the idm_status functions (see above).

function idm_geteventvalues($name)

Returns an array of string values for the item specified by $name. If no values exist, $null is returned.

function idm_geteventvalue($name)

Returns the string value for the item specified by $name. If no values exist, $null is returned.

function idm_geteventvaluenames

Returns an array containing each value name for the event. This function can be used to iterate over every value.

function idm_geteventattrnames

Returns an array containing each attribute item for the event. This includes ADD_attrname, REMOVE_attrname and PASSWORD values.

function idm_writevalues($name, $values)

Sets an array of string values for the item specified by $name to be returned to the driver engine when the script completes. You must call idm_setcommand or one of the idm_status functions before calling this function.

function idm_writevalue($name, $value)

Sets a single string value for the item specified by $name to be returned to the driver engine when the script completes. You must call idm_setcommand or one of the idm_status functions before calling this function.

function idm_subgetnamedpassword($name)

Returns a named password specifed by $name from the Identity Manager engine. The value $null is returned if no such password exists.

C.5.3 Publisher Functions

function idm_getpublisherparam($paramname)

Returns the string value for the Publisher parameter specified by the string $paramname.

function idm_publishinit($command)

Sets the Publisher command specified by $command to return to the driver engine when idm_publish is called.

function idmpublishvalues($name, $values)

Sets an array of string values for the item specified by $name to be returned to the driver engine when idm_publish is called.

function idm_publishvalue($name, $value)

Sets a single string values for the item specified by $name to be returned to the driver engine when idm_publish is called.

function idm_publish

Submit the command and item values specified above to the driver engine for Publication to the identity vault.

function idm_pubgetnamedpassword($name)

Returns a named password specified by $name from the Identity Manager engine. The value $null is returned if no such password exists.

C.5.4 Query Functions

function idm_queryinit

Initializes a query to be submitted to the identity vault with the idm_doquery call. NOTE: Currently only queries that query a single object are supported.

function idm_querysetassociation($association)

Specifies the association of the identity vault object to query.

function idm_querysetsearchroot($searchroot)

Specifies the DN of the identity vault object to query. Either the object’s association or DN must be specified. If both are specified, the association value is used by the Identity Manager engine.

function idm_queryaddsearchattr($name, $value)

Specifies a search condition to be used for the query, of the form $name=$value. $name specifies an attribute, and $value specifies a value it must match. The query will return only objects matching all specified conditions.

function idm_queryaddreadattr($name)

Specifies an attribute name whose values should be returned by the query. By default, all attributes are returned.

function idm_querysetreadparent($readparent)

Specifies whether the association and DN of the parent of the queried object should be returned ($readparent is boolean). The default is $False.

function idm_doquery

Executes the query with the parameters specified by idm_querysetXXX calls. The function returns $True if an object (called an instance) is returned.

function idm_getqueryinstanceassociation

Returns the association for the returned instance.

function idm_getqueryinstancedn

Returns the DN for the returned instance. The DN is in slash format, for example: \ACME\Users\Bob.

function idm_getqueryinstanceclass

Returns the class name for the returned instance.

function idm_getqueryinstanceparentassociation

Returns the association for instance’s parent object, if the $readparent flag was specified.

function idm_getqueryinstanceparentDN

Returns the DN for instance’s parent object, if the $readparent flag was specified.

function idm_getqueryinstanceattrnames

Returns an array containing the names of the attributes retrieved for the instance. Returns $null if no attributes were retrieved.

function idm_getqueryinstanceattrcount

Returns the number of attributes retrieved for the instance.

function idm_getqueryinstanceattrvalues($attrname)

Returns an array of values for the attribute with the specified $attrname. Returns $null if no values are available.

function idm_getqueryinstanceattrvalue($attrname)

Returns a string value for the attribute with the specified $attrname. If multiple values are available for the attribute, the first one is returned. If no values are available, $null is returned.

C.5.5 Heartbeat Functions

function idmheartbeatsuccess($message)

Use this function in the heartbeat.ps1 script to indicate a success status of the external application.

function idmheartbeaterror($message)

Use this function in the heartbeat.ps1 script to indicate an error status of the external application.

function idmheartbeatwarning($message)

Use this function in the heartbeat.ps1 script to indicate a warning status of the external application.