Export

This script is run once for each export step in a Run Profile with an Export step. All pending exports are put in the pipeline and that pipeline is passed to the export script. Depending on the batch size for the Run Profile, your export script may get called multiple times on every export run.

The export script should be able to handle one or more objects sent in the pipeline and the recommended template for the export script is -

PARAM
(
  $Username,
  $Password,
  $Credentials,
  $AuxUsername,
  $AuxPassword,
  $AuxCredentials,
  $ExportType,
  $ExportPageNumber,
  $Schema
)

BEGIN
{
}
PROCESS
{
}
END
{
}

The export script is given the following parameters -

• $Username - this is the username specified on the management agent
• $Password - this is the password specified for the user on the management agent (sent in cleartext, so take appropriate security measures to protect this)
• $Credentials - the username and password above as a PSCredential object
• $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
• $ExportType - this will be either 'Full' or 'Delta' depending on the configured Export Run Profile (this parameter is supported from build 5.5.3501 and later)
• $ExportPageNumber - an integer that denotes the current page number during export operations. It begins at 0 and is suitable for executing initialization tasks exclusively needed for the first export iteration. All objects are passed in the pipeline as complete objects with their values populates / shaped like the Sync Service expects to read them back.
• $Schema - a PSCustomObject specifying the schema for the MA

All objects are sent in the pipeline as 'object replacements'. This means that you're getting the exported objects exactly as FIM expects to read it back. Therefore, you'll only get attributes that have values. If an attribute is not present on the object (in the ChangedAttributenames list), you must clear it (set it to null) and/or not return it in import. For more information, you can refer to sample scripts and comments within these.

Simple or complex export objects?

In the configuration for the management agent, you can specify whether you want simple objects or plain connector space objects to be sent to your export script.

If you select the checkbox 'Export simple object' (default) on the Global Parameters configuration page, the MA populates the export pipeline with objects of type PSCustomObjects containing control values. If left unchecked, the export script will receive objects of type CSEntryChange.

Opting for simple objects instead of CSEntryChange objects will yield objects of type PSCustomObject, where all existing attributes will be available as note properties (NoteProperty) on the objects. If an attribute is null (non-existent), it will not be present as a property on the PSCustomObject. Additionally, the simple object will include some control values. -

• [Identifier] - the GUID (type string) of the connector space object; use this as identifier to return status for export objects
• [IdentifierAsGuid] - the same {"[Identifier]"} as above; only as a type GUID.
• [Anchor] - the anchor of the exported object
• [DN] - the DN of the exported object
• [RDN] - the RDN of the exported object
• [ObjectType] - the object class of the exported object
• [ChangedAttributeNames] - a collection of attribute name that has changed for this object
• [AttributeNames] - a collection of available attribute names for this object
• [ObjectModificationType] - type of change (Add, Replace or Delete)

Returning error message for export objects

You can return error message to the FIM Synchronization Service Manager if an export operation fails for some reason.

Each export object in the pipeline has a control value called [Identifier] which is a GUID (as a string). This identifier can be used to send a status about about the result of an export operation for a specific export object. If you want to return an error message to FIM about an export operation, you put a hashtable with three values ([Identifier], [ErrorName] and [ErrorDetail]) in the pipeline. Below you can see a sample script that returns an error object to FIM -

PARAM (
  $Username,
  $Password,
  $Credentials,
  $ExportType,
  $Schema
)

BEGIN
{
}

PROCESS
{
 $DN = $_.'[DN]'
 $Identifier = $_.'[Identifier]'
 $ObjectType = $_.'[ObjectType]'
 $ObjectModificationType = $_.'[ObjectModificationType]'
  
  if ( ...a freak error occurred... )  {
   $obj = @{}
   $obj.Add("[Identifier]", $Identifier)
   $obj.Add("[ErrorName]", "strange-error")
   $obj.Add("[ErrorDetail]", "A little more information about this strange error that occurred")
   $obj
  }
  else  {
    $obj = @{}
    $obj.Add("[Identifier]", $Identifier)
    $obj.Add("[ErrorName]", "success")
    $obj
  }
}

END
{
}

Your export script must always return a status for the export operation.

Returning constructed anchors

If your datasource manages the anchor (i.e. SQL server's IDENTITY column type), you can return this anchor to the MA. On your export return object, simply return the value as a hash table element as you would with a import object, i.e.

$obj = @{}
$obj.Add("[Identifier]", $Identifier)
$obj.Add("[ErrorName]", "success")
$obj.Add("<name of anchorid attribute>", <datasource value>)
$obj