Execution-controller-scripts

Execution controller scripts are an optional feature for very advanced scenarios. They provide the capability to

• Intercept the execution queue and determine if you want AutoSync to execute a run profile or not

• Receive the results of a run profile after execution and perform follow up actions, that can including asking the AutoSync service to terminate itself.

ShouldExecute

The controller script can implement a function called ShouldExecute that takes a single string as a parameter. Immediately prior to AutoSync executing the run profile, this function will be called. If no result, or $true is returned, the run profile will be executed.

If $false is returned, the run profile will not be exected

function ShouldExecute
{
	param([string]$runProfileName)

	Write-Object $true;
}

While the primary purpose of this is to allow you to prevent AutoSync from executing a run profile, it can also be used to give advanced notice of a pending operation and perform some preparatory action. For example, if a delta import is about to execute, you can call into the target system and have it prepare the delta import.

ExecutionComplete

If implemented in the controller script, this function called by AutoSync after a run profile finishes execution. The function is passed an argument called $lastRunDetails which contains an object describing the results from the last run. This function can be used for several purposes

• Performing follow up actions after a run profile has completed (e.g deleting a delta file)

• Sending an email report based on the outcome of a run profile

• Detecting if the number of pending changes from an import or synchronization, exceeds a particular threshold. The option exists to terminate the AutoSync service under these conditions.

The following example shows how to terminate the AutoSync service if more than 1000 changes are detected in a run profile.

function ExecutionComplete
{
	param([Lithnet.Miiserver.Client.RunDetails]$lastRunDetails)
        
	# If the run was an import that returned more than 1000 changes, throw an exception that will terminate the service
	foreach ($step in $lastRunDetails.StepDetails)
	{
	if ($step.StepDefinition.Type -eq 'DeltaImport' -or
		$step.StepDefinition.Type -eq 'FullImport')
		{
			if ($step.StagingCounters.StageChanged -gt 1000)
			{
				$maName = $lastRunDetails.MAName;
				$runProfile = $lastRunDetails.RunProfileName;

				$message = "The management agent $maname has over 1000 pending import changes from run profile $runProfile and has been stopped. Perform a manual synchronization if these changes are expected and restart the auto sync service"
				Send-MailMessage `
								-to $mailTo `
								-from $mailFrom `
								-subject "AUTOSYNC SERVICE STOPPED - $maName" `
								-SmtpServer $smtpServer `
								-Body $message
				
				# Throwing the exception with a $true parameter will force the service to stop
				# Throwing the exception with a $false parameter will stop further runs on this MA only until the service is restarted.

				throw [Lithnet.Miiserver.AutoSync.UnexpectedChangeException] $true;
			}
		}
		elseif ($step.StepDefinition.Type -eq 'Synchronization')
		{
			foreach($flows in $step.OutboundFlowCounters)
			{
				if ($flows.OutboundFlowChanges -gt 100)
				{
					$maName = $lastRunDetails.MAName;
					$runProfile = $lastRunDetails.RunProfileName;
					$outboundMAName = $flows.ManagementAgent
					$message = "The synchronization operation $runProfile on management agent $maname triggered over 100 pending export operations on $outboundMAName and has been stopped. Perform a manual export if these changes are expected and restart the auto sync service"
					Send-MailMessage `
									-to $mailTo `
									-from $mailFrom `
									-subject "AUTOSYNC SERVICE STOPPED - $maName" `
									-SmtpServer $smtpServer `
									-Body $message
				
					# Throwing the exception with a $true parameter will force the service to stop
					# Throwing the exception with a $false parameter will stop further runs on this MA only until the service is restarted.

					throw [Lithnet.Miiserver.AutoSync.UnexpectedChangeException] $true;
				}
			}
		}
	}
}

$mailTo = "[e-mail]";
$mailFrom = "$env:[e-mail]";
$smtpServer = "smtp.lithnet.local";

The object passed to the function is the same object returned by the Get-LastRunDetails PowerShell cmdlet in the MIIS PowerShell module. This can be used to writing and troubleshooting the script outside of the AutoSync engine