Powershell script trigger

Summary

AutoSync provides administrators the ability to create their own custom triggers using Powershell scripts. Anything you can script in PowerShell can be turned into a trigger. PowerShell triggers are not restricted to running import oeprations - any run profile type can be triggered.

Configuration

The PowerShell script trigger is available to use on any MA. From the triggers page, select Add trigger... and the PowerShell script trigger will be available from the drop down list. Each management agent can have an unlimited number of PowerShell triggers.

Setting	Value
Powershell Script	The path to the script. You can create a new empty template using the New script from template button, or launch the default system Powershell editor using the Edit script button
Wait for the following duration after the script compeltes before invoking it again	The trigger engine will continually call Get-RunProfileToExecute at the interval specified here
Error handling	If the PowerShell throws an error, you can either terminate the script, or reset the PowerShell enviroment and restart the script. If email settings are enabled, an email will be sent when the trigger encounters an error

Trigger script template

Triggering a run profile by name

At its simplest form, a trigger is just a PowerShell script file that contains a single function Get-RunProfileToExecute. The script writes out the name of the run profile to execute, and AutoSync queues the job to run on the management agent

# Sleep for 5 minutes, then trigger a delta import using the run profile name
function Get-RunProfileToExecute 
{
    Sleep (5 * 60);
    Write-output "DI";
}

This example executes the run profile DI after sleeping for 5 minutes. AutoSync will call Get-RunProfileToExecute every 5 seconds by default, so it is important to set this value to one that is appropriate for your script.

AutoSync will read and execute run profiles received from the pipeline using the Write-Output. A single call can return multiple run profiles, which will be executed in order. It is also acceptable to not return any run profile name at all.

Of course, your scripts will do a lot more than sleep and specify a static run profile. You can query databases, web services, make API calls, run executables - anything you can think of. If there is nothing you want AutoSync to run after performing your analysis, then just let the Get-RunProfileToExecute function exit without writing anything to the pipeline. AutoSync will call the function again at the next specified interval.

Simple triggers need only return the name of the run profile to execute, but more advanced triggers can specify additional execution options by returning an Lithnet.Miiserver.Autosync.ExecutionParameters object. This object provides the ability to execute a run profile by 'type' rather than by name, as well as specifying that a run profile should be run exclusively.

Running a profile exclusively

The following example specifies an ExecutionParameters object that contains the Exclusive = $true parameter. When an exclusive run profile is queued

• AutoSync prevents any new jobs from starting

• AutoSync waits for all existing jobs to finish

• AutoSync executes the exclusive job

• When the exclusive job finishes, AutoSync resumes normal operations

# Sleep for 5 minutes, then trigger a full sync to run exclusively
function Get-RunProfileToExecute 
{
    Sleep (5 * 60);

    $p = New-Object Lithnet.Miiserver.Autosync.ExecutionParameters;
    $p.RunProfileName = "FS";
    $p.Exclusive = $true;
    write-output $p
}

Executing a run profile by type

If you are writing trigger scripts for extensibility across environments, or for distribution with software you have written, you may not know the name of the run profile in the target environment you want to execute, but you know what type needs to be executed. In the example below, we specify only that we want to perform a 'DeltaImport' every 5 minutes. AutoSync will find the appropriate run profile and execute it.

# Sleep for 5 minutes, then trigger a delta import using the run profile type
function Get-RunProfileToExecute 
{ 
    Sleep (5 * 60);

    $p = New-Object Lithnet.Miiserver.Autosync.ExecutionParameters;
    $p.RunProfileType = "DeltaImport";
    write-output $p
}

Allowed values for RunProfileType:

• DeltaImport

• FullImport

• Export

• DeltaSync

• FullSync

Passing credentials from the UI

You can obtain a PSCredential object that contains the credentials provided in the configuration UI for the PowerShell trigger, but including a parameter called $credentials in your function definition as shown below.

function Get-RunProfileToExecute($credentials) 
{
...
}

Passing the MA name into the script

You can have autosync pass in the name of the MA by adding a $maname parameter to the signature of the method.

function Get-RunProfileToExecute($maname) 
{
...
}

Storing variables between runs

The PowerShell session state is saved between runs, so you can set variables outside of the Get-RunProfileToExecute function and they will persist between calls.

Trigger Gallery

Visit the Powershell Script trigger gallery to see pre-made triggers that you can use in your projects.