Synchronization Service - Step Handlers


We just recently implemented the Active Roles Synchronization Service in our organization to aid in employee onboarding.

I am wondering what the "Step Handlers" can be used for? The documentation says the following:

"Sync workflow step handlers allow you to automatically perform custom actions either before running a workflow step or after the workflow step run results have been committed (written) to the data system. Out of the box, Synchronization Service includes a single predefined handler type that can automatically execute your custom PowerShell script and thus perform the desired action."


I was hoping to be able to use this to read the data collected from our HR software, check a specific attribute we are receiving from that system, and if it is set to a specific value, trigger an alert.

I tried using the $Srcobj hash table that is detailed in the documentation, but this appears to be only be available in the "Creation Rules".

Is there a way to reference objects in the source location from scripts running in the "Step Handlers" step?



  • #1. AR Sync Services support MSDTG related data sources (AD, AAD, SQL DB etc…) In general the list of platforms used to change in past.
    #2. Challenge point: is customized data structure on HR platform side
    #3. CSV input. Probably the most easiest and robust way to start: ask HR to provide \\SHARE\HR.CSV with user records. AR Sync Service supports user create/update/terminate from CSV to ARS/AD OOB. Limitation: it will be one-way sync from CSV to AD.
    In case you need to have more detailed discussion on the matter, please let me know.

  • Step handlers are generally used to perform some kind of special processing on the data coming from the source connected system or in some cases to add to that data based on a lookup in another system that is separate from the source.

    If you could provide us some more detail on the type of change or addition you want to make, perhaps we can suggest an implementation approach.

  • Hi Aidar,

    The sync process is actually completely setup. We are connecting to an SQL database currently.

    Everything is working as expected, I am just now looking to expand the functionality.

    This is why I am asking what the purpose of these Step Handlers are. I am wondering if they give me the ability to work with the data and pre and post commit. From their description, it seems like I should be able to. But maybe I am wrong. I am just trying to understand if there is a hast table that is created that I can access from the Step Handler steps.

  • Global action for the step. As JohnyQuest pointed above, I used Step Handles to do global Pre-Step action / Post-Step action for all records processed in the step (for example, massage the HR.CSV file input before/after processing the step).

    Per-record pre-commit/post-commit steps: I’m not sure that you can do this (though it is a great question).  Though, you can access in-process user data on both side (ARS/AD, and HR/SQL) via $Srcobj, $DirObj.

    Trick. Try to sync some hidden attribute (Write <TimeStamp> in CA-15, or Virtual Attribute like MY_ARS_SYNC) and fit in the attribute sync a script to process $Srcobj, $DirObj, calculate result and “hit” QAD-Users (ARS/AD) and SQL SELECT UPDATE (HR). It is not exactly pre/post commit per record, but close enough.

    If the trick above does not help and you need *during the sync* a status of the record from outside of the current values (old and new) to be calculated based on complex logic data combined in AD and HR *together*: maybe it would be beneficial to rethink whole sync process logistics and dependencies which comes first and latter.

    • Thank you for your incredibly detailed response. I am not going to lie, it went a little over my head.
    • The "source" or "HR" data is a DB. I unfortunately do not have any control over the data coming from the DB. 
    • I wish I could post screenshots easily as it would be slightly easier to explain, I will try and give additional details below.

    • Cool name!
    • I will try and provide more detail below.

    Details about our environment

    • Source: Database
    • Target: ARS/AD

    Creation Step

    • We have a step that takes users from the DB and creates them in ARS/AD.
    • This step has a filter. Attribute_A = Employed, Attribute_B = true

    What I would like to do

    • Any user that has the following: 
      • Attribute_A = Employed
      • Attribute_B = false
      • This means the user will not be created
    • A notification will be sent to the HR department with details about the user explaining that there is an issue with the provided details and it will not be created.

    I thought I might be able to use a Step Handler to trigger this alert. Preferably, if I could send the alert prior to any commits, that would be great. But it could also happen after the fact.

    I am just looking for a way to trigger some sort of alert based on the data that the Sync Service is reading from the source. If this can also be accomplished while the "creation step" is actually running. That would be great as well.

    I created a simple script to basically demonstrate what I would want to do collect and then send:

    $body = "First Name: " + $strSourceFname
    $body += "Last Name: " + $strSourceLname
    $body += "Office: " + $strSourceOffice
    $body += "EmployeeID: " + $strSourceEmployeeID
    If ( $strSourceDataV -eq "false" )
         Send-MailMessage -From "some email" -To "some email" -Subject "Clean Data" -SmtpServer 'some server' -Body $body

    Maybe Step Handler isn't the right place to do something like this?

  • One approach to this is to clear all other Synchronization Scope filtering (at the connection level) as well as Creation Criteria conditions (at the Provisioning step level) and write a customer PowerShell script to analyze the source data and make the determination if the object should be created or skipped and an alter sent out.

    Here is a very crude sample script I wrote to demonstrate how you might accomplishing this. You add this script to the Source section in the Provisioning workflow step. Expand Creation Criteria and click Add condition in the "Source objects must meet these conditions". Click the down arrow next to Attribute and select "PowerShell Script". Use the script below modified with your script to get the results you want. My script simply logs to a file, but use your Send-MailMessage cmdlet to send an email. Just be sure to set the proper return value. Then back on the "Add Condition" screen, select "Is Exactly" and enter the return value that the script is returning if you want the object to be created, "True" in my example. Otherwise, if the value is not True then the record will be skipped.

    # Retrieve the data validation from the source object
    $DataValidation = $srcobj["extensionAttribute1"]
    if ( $DataValidation -eq "True" )
       # This object is to be created, set provision filter value to True
       $ProvisionCondition = "True"
       # Value is something other than True, obtain other object data and send alert, or log to file...
       $FN = $srcobj["givenName"]
       $LN = $srcobj["sn"]
       # Log to output file, send alert... and set provision filter to False to skip this record
       $FN + " " + $LN + " has been skipped" | Out-File "C:\Logging\SyncService_usersskipped.log" -append
       $ProvisionCondition = "False"
    # Return Creation Criteria value
  • This is a very intriguing solution and is fairly easy to implement.

    I will definitely give this a try.

    Give me a little time to implement and I will update this thread once tested.


    Side note, One Identity should allow screenshots to be directly uploaded to their forums. It would make communicating issues and solutions a lot easier in my opinion!

  • That's correct. Provision (Update, Terminate) Job Step | "Source Object Must Meet the Criteria" filtering. Example IF "Contract End Date" < Today THEN do not create, do not update, Deprovsion.

  • Hi Richard,

    Sorry I haven't responded in forever, I am just curious if there is a way to reference the target object?

    You reference the source object using "$srcobj". I am curious if there is something similar to reference the target object?


  • You can use $dstobj in a similar fashion for mapped target objects.