Executor Scripts

A quick reference to write your own executor scripts

Script Template

Controller "ArbitraryControllerName" {
    Init {
        # Init is called before any action. Use it to initialize your controller script.

        # TODO: implement controller setup

        # import modules
        Import-Module $env:GOV_HELPER_MODULES\MicrosoftGraph.Helper.psm1

        # fetch executor environment
        $tenantId = $env:GOV_TENANT_ID # "eeeef6f0-2dd7-4f7f-84d1-a23d9d1a7acc"
        $clientId = $env:GOV_CLIENT_ID # "819cf1fa-51ff-4b4a-9ef3-a668c97cf1eb"
        $certificateFile = $env:GOV_CERTIFICATE_FILE # "F:/governor789287-Governor-Executor-DEV-ClientCertificate-20220408.pfx"
        $certificatePassword = Get-Content $env:GOV_CERTIFICATE_SECRET -Raw | ConvertTo-SecureString -AsPlainText -Force
        $certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($certificateFile, $certificatePassword)
        #$env:GOV_ORGANIZATION_NAME # "csccdemo.onmicrosoft.com"

        # get access token with client certificate
        Connect-MgGraph -TenantId $tenantId -ClientId $clientId -Certificate $certificate
    }

    Shutdown {
        # Shutdown is called after any successful or non-successful action
        Disconnect-MgGraph
    }

    Action "Create" {
        param($Order)

        # TODO: Implement "apply" action for new objects (= some conditions not true yet)
        $targetObject = Get-GovernedObject -Id $Order.GovernedObjectId -ConfigurationType "YourConfigType"
        $targetObject | ConvertTo-Json -Depth 10

        return New-ExecutionResult `
          -ConfigurationType "YourConfigType" `
          -Action $Order.Action `
          -ObjectId $Order.ObjectId `
          -ItemId "OPTIONAL_INVENTORY_ITEM_ID" `
          -Reason "OPTIONAL_REASON" `
          -Updates @{ OPTIONAL_KEY_VALUE_PAIRS: "..." } `
          -Cooldown OPTIONAL_COOLDOWN_SECS

        return New-ExecutionError `
          -ExecutionType $Order.Action `
          -ObjectId $Order.ObjectId `
          -Message "MANDATORY_MESSAGE" `
          -Reason "MANDATORY_REASON" `
          -Repeat:OPTIONAL_SWITCH -Cooldown COOLDOWN_SECS
    }

    Action "Update" {
        param($Order)

        # TODO: Implement "apply" action for existing objects (= all conditions already true)
    }

    Action "Destroy" {
        param($Order)

        # TODO: Implement "destroy" action (= some conditions not false yet)
    }

    Action "Delete" {
        param($Order)

        # TODO: Optional. Implement "delete" action (= move to recycle bin)
    }

    Action "Restore" {
        param($Order)

        # TODO: Optional. Implement "restore" action (= restore from recycle bin)
    }

    Action "ArbitraryActionHere" {
        param($Order)
        # ... use imagination here ...
    }

}

Execution Orders

Sample

{
  "OrderId": "d75d37a5-7485-42e0-a0a5-4a8de216e651",
  "Action": "AzureADUser/Create",
  "GovernedObjectId": "47d904de-b62a-4b78-b552-93d3c5e7737b",
  "NativeItemId": "aef5275a-38bf-41d2-944c-cd2411e5ce1f"
}