Export script

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

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,
  $ExportType

)

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

All objects are passed in the pipeline as complete objects with their values populates / shaped like the Sync Service expects to read them back.

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?

On the configuration for the management agent, you can specify whether you want simple objects or plain connector space objects 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 with control values. If this is left unchecked, the export script will receive objects of type CSEntryChange.

If you opt for simple objects instead of CSEntryChange objects, you will get objects of type PSCustomObject where all existing attributes will available on the objects as note properties (NoteProperty). If an attribute is null (non-existing), it will not exist as a property on the PSCustomObject either. Also, the simple object will have 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,
 $OperationType

)

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