Import

The role of the import script is to retrieve objects from the data source and pass them to the PowerShell MA / FIM.

This import script runs 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. These objects passed from the script will be handed over to FIM.

To see complete implementations of import scripts and potentially discover tips and tricks, you should download some of the sample scripts. You may also find useful information in the FAQ section

The import script takes twelve 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

• $Username - the username specified in the Connectivity section of the MA

• $AuxUsername - the auxilary username specified in the Connectivity section of the MA

• $AuxPassword - the auxilary password specified in the Connectivity section of the MA (send in clear text)

• $AuxCredentials - the auxilary username and auxilary password above as a PSCredential object

• $ConfigurationParameter - a collection of key/value of values specified in Configuration parameters for the MA

  • Each value should be on a seperate line and key and value seperated by a comma or equal sign, i.e.
    • Environment=PROD
    • Servername=sx01.contoso.com

• $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)

• $ImportPageNumber - an integer that signifies the current page number during import operations. It starts at 0 and can be utilized for initializing tasks specifically required for the first import iteration. Mostly relevant for paged imports (available from version 5.6.0327.2024).

• $PageSize - an integer value specifying how many objects to return if it is a paged import (supported from version 5)

• $Schema - a PSCustomObject specifying the schema for the MA

The recommended template for the import script is -

PARAM
(
  $Username,
  $Password,
  $Credentials,
  $AuxUsername,
  $AuxPassword,
  $AuxCredentials,
  $OperationType,
  $UsePagedImport,
  $PageSize,
  $ImportPageNumber,
  $Schema
)

BEGIN
{
}
PROCESS
{
}
END
{
}

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 the message that 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). The expected import type is provided as a parameter ($OperationType) to the import script.

In the import script, you have the option to set the value of the global variable 'RunStepCustomData' (must be 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 value 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 and object class 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 number of objects 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 fewer if needed). The value passed in $PageSize is the page size 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 global variable $PageToken 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.