Quite a long time ago, one of my customers expressed a need for a custom PowerShell script that could be run as a scheduled task that would allow them to run a Full Import and Sync once weekly. I created a script that would allow that functionality, however once I did there were quite a few additional features requested.
The script has now evolved into a much larger animal, capable of nearly everything short of self-awareness, so I decided to blog about it on the off chance that someone else is looking for similar behavior.
The options
-Schedule : used to automatically create the script as a scheduled task
-Loop : when run interactively, causes the script to run in a loop every X minutes, as specified by the -Minutes switch
-Minutes : number of minutes between each iteration of the -Loop option
-DayForFulls : define the 1 day of the week when Full Import and Fully Syncs will occur. Will only accept full day names (eg. Monday, Tuesday)
-DoFullsBetween : used to specify two hours, in military time, during which the Fulls will occur. Default is 0 and 2, with 0 being midnight.
-AlwaysDoWeeklyFull : tells the scheduler to do Fulls every weekend
-SkipECMAs : tells the script to ignore ECMA management agents when processing imports / syncs / exports
-SkipAAD : tells the script to ignore the Azure Active Directory connector when processing imports / syncs / exports
-SkipAD : tells the script to ignore Active Directory connectors when processing imports / syncs / exports
-SkipImports : tells the script not to process ANY imports on any connector
-SkipExports : tells the script not to process ANY exports on any connector
-SkipSyncs : tells the script not to process ANY syncs on any connector
-AllowExportToECMAs : tells the script to process exports to ECMA style connectors that might be otherwise skipped in Staging mode
-NoEventLogging : tells the script not to log any events to the Application event log. Normally, the script will write out all progress to the log.
-StagingModeTimeout : tells the script how long to try (in seconds) to determine if the server is in staging mode. This option was added due to issues with the Get-ADSyncScheduler PowerShell cmdlet timing out on some systems. The default value for this switch is 45 seconds. If the 45 seconds elapses without returning the status, the script fails SAFE and assumes staging mode is enabled.
-SkipRunCheck : tells the script not to bother checking if any connectors are currently running. Run checking normally occurs to ensure that if run interactively, the script will not attempt to run while other import / sync or export operations are in progress. Handy if the built-in scheduler is enabled and the script is run manually.
-IgnoreStaging : tells the script to ignore the status of staging mode and perform exports, regardless of the status of the StagingModeEnabled property.
-ExportECMAFirst : tells the script, when processing exports, to perform exports to ECMAs before any other connector. The default is ECMAs are exported last. This is handy if you are using a custom AAD Connect implementation where the UPN-Fixer connector has been added, since UPN changes should happen before AAD changes to avoid the federated rename errors.
-IgnoreLoadBalancing : tells the script to ignore the LoadBalancing module, in the event it is installed on the system.
-SafetyMargin : number of hours to wait before automatically becoming the active node. Default is 3. This switch is used with the LoadBalancing module, if the module is not present the switch has no impact.
-Thumbprint : the certificate thumbprint that aligns with the certificate created on the system to encrypt the credentials. This option requires the CredentialVault module.
-CredFilePath : path to the XML file which contains the encrypted password used by the CredentialVault module.
-AllowedDeletes : tells the script the maximum number of deletes allowed to ECMA connectors before the script will skip exports. If the number pending exceeds this number, nothing is done.
-AllowedAdds : tells the script the maximum number of adds allowed to ECMA connectors before the script will skip exports. If the number pending exceeds this number, nothing is done.
-AllowedChanges : tells the script the maximum number of changes allowed to ECMA connectors before the script will skip exports. If the number pending exceeds this number, nothing is done.
More info about the script
It’s important to note that the script can be used without the LoadBalancing module, if you do use the AADCLoadBalancing module (found here) then you must also have the CredentialVault module (found here) because you will need to encrypt and store credentials for the script to use to reach Azure for the load balancing data.
If you have load balancing enabled, but don’t want to use it, you can override the behavior with the -IgnoreLoadBalancing switch.
If you do not have the AADCLoadBalancing module on your system, the script will honor the Staging mode set via the AAD Connect wizard and behave just like the built-in scheduler, with the added features.
If you are honoring the staging mode setting, but want to override it on one or more occasions to force exports, you can use the -IgnoreStaging switch.
By default, the script, due to it’s design, will perform Full Imports and Full Syncs once weekly. If for any reason you want to prevent that behavior one time, you can simply create a file named nofulls.txt in the same location as the script.
The script will detect this file when it is time to do Fulls, skip Fulls and then delete the file. This eliminates the need to stop the script, or modify it for a single case where Fulls should be skipped.
Alternatively, if you have a particular day / time of week configured for Fulls, however you want to force a Full import and sync during a particular cycle, you can create a file named DoFullImport.txt in the same location as the script.
The script will detect the file when it runs, and force Full Imports and Syncs during that iteration, then delete the file and return to Deltas thereafter.
The script can be located here.