Import script

THIS PAGE IS OBSOLETE - PLEASE VISIT http://psma.codeplex.com for latest version

The role of the import script is to return objects from the datasource to the PowerShell MA / FIM.

This import script is run once for each Run Profile that includes an import step. The script MUST send a hash table matching the schema of the MA with all objects to the pipeline. The objects passed from this script will be handed over to FIM.

You should download some of the sample scripts to see complete implementations of import scripts.

The import script takes five parameters -

• $Username - the username specified in the Connectivity section of the MA
• $Password - the password specified in the Connectivity section of the MA (send in clear text)
• $Credentials - the username and password above as a PSCredential object
• $OperationType - the value of this parameter is either 'Full' or 'Delta' and depends on the type of import specified in the Run Profile.
• $UsePagedImport - a boolean indicating whether or not this is a paged import (supported from version 5)
• $PageSize - an integer value specifying how many objects to return if it is a paged import (supported from version 5)

Control attributes on import objects

You can add three extra control attributes ([DN], [ErrorName] and [ErrorDetail]) to the hashtable object being returned. This mean that you can now give informational feedback to the Synchronization Manager besides just the attribute values.

A sample return hashtable with an import error might look like this -

$obj = @{}

$obj.Add("Id", "1")
$obj.Add("objectClass", "user")

$obj.Add("[DN]", "CN=Luke Skywalker,OU=Normal Users,DC=domain,DC=com")

$obj.Add("sAMAccountName", "LS")
$obj.Add("displayName", "Luke Skywalker")

$obj.Add("[ErrorName]", "read-error")

$obj.Add("[ErrorDetail]", "An permission error occurred during directory read")

$obj

If the import object doesn't have any errors, you can skip returning the [ErrorName] and [ErrorDetail] control attributes or you could return the value 'success' in the [ErrorName] control attribute.

You can simplify the construction of the return object (this return a success import object) -

$obj = @{}

$obj.Id = "1"
$obj.objectClass = "user"

$obj."[DN]" = "CN=Luke Skywalker,OU=Normal Users,DC=domain,DC=com"

$obj.sAMAccountName = "LS"
$obj.displayName = "Luke Skywalker"

$obj

Control attributes must be enclosed in brackets, i.e. [DN] and they cannot exist in the schema. The following control attributes are available in the import script -

• [DN] - value in this will be used as DN. This will appear in Connector Space searches and if you have reference attributes, you must also specify this value for reference objects/values. If you do not specify a DN, the MA will use the anchor as the DN. Even if you specify a DN, you must also return a value for the anchor attribute.  
• [ErrorName] - if specified on an import object, this is message will appear in the Synchronization Service Manager. It is recommended to keep this message short, i..e. 'read-error' or 'script-error'  
• [ErrorDetail] - if specified, the text here can be found in the details of the error message dialog in the Synchronization Manager

Supporting delta import from your import script

This MA supports delta imports. However, it's up to you as the author of the import script to write code to return either all objects (Full Import) or only changed objects (Delta Import).

In the import script, you have the option to set the value of the global variable 'RunStepCustomData' (string type) when returning from the import script. The value of RunStepCustomData will be passed back to the import script on next import run and is effectively used as a delta watermark.

When the MA is created, or the server configuration is imported with a new management agent, or a Full Import is performed, then the custom data is emptied/cleared.

You should set the value of this variable to the delta value of the last imported object, i.e. a directory synchronization cookie if your script imports from a directory (like Active Directory) that supports this or you could set it to the value of a timestamp column from a SQL record if you're returning objects from a SQL database. Maintaining the correct value in this value is up to the import script.

When setting the RunStepCustomData value, it is very important to mark the variable as global; otherwise, FIM cannot pick up the value and your delta imports wont' work correctly, i.e.

$global:RunStepCustomData = <your delta value>

Note - If you are only supporting Full Imports, you do not need to worry about the RunStepCustomData value.

Delta deletes

If you want to support delta imports of deletes, you should add an extra key/value pair to the hash table (object) that you are returning as a 'delete'. The key name should be 'changeType' and the value should be 'Delete' and the anchor value should also be included in the hash table returned, i.e.

if ($OperationType -eq 'Delta')

{

  ... <code to read objects from datasource> ....

  $Obj = @{}

  if ($MyObject.IsDeleted)

  {

    $Obj.Add('Id', $MyObject.AnchorValue)

    $Obj.Add('objectClass', 'user')

    $Obj.Add('changeType', 'Delete')

    $Obj 

  }

  else

  {

    ... <code to return normal object > ...

  }

}

If it's a delta delete, you don't have return any other properties than the anchor, the objectClass and the changeType. For Full Imports, do NOT return deleted objects and do NOT add the 'changeType' value as this is default set to 'Add' for non-deletes.

Paged imports

The MA supports paged imports as of version 5. If you specify on the MA, that the import script supports paged import then the import script will be called one or more times depending on the numbers of objects that it returns.

The import script is passed a value in the PageSize parameter which specifies the maximum number of objects that should be returned (you can return less if needed). The value passed in PageSize is the pagesize value from the current Run Profile. If there are more objects to return, you should set the global variable MoreToImport to true and save any needed paging information in the PageToken variable before returning. As long as the MoreToImport variable is set to true, your import script will be called again.

• $global:PageToken - holds paging token and is passed to import script on subsequent import calls. You should use this to keep track on which objects, you have returned to the MA/FIM.
• $global:MoreToImport - is a boolean that should be set to 'true' if there are more objects to be returned and it should be set to 'false' if the import script has returned the last objects for the import run.

If you choose to support paged imports, it is easier to stop an import run profile.