08 Apr 2014

Linking SMA Runbooks to Azure Pack VM Cloud Events and get Job Parameters

One of the awesome capabilities in Service Management Automation I like very much, is the ability to link SMA Runbooks with VM Cloud action events. Action events are triggered when SPF executes actions against Windows Azure or System Center Virtual Machine Manager. There are a lot of actions you can choose to trigger and fire up a particular SMA Runbook. Refer to this link for a complete list of action events and their related objects.

So to give you an example for possible use cases we are going to link a SMA Runbook to the “VMM Virtual Machine” object on “Create” action. The runbook reads out the parameters that SPF passed to SMA when calling the Runbook. After this. the runbook calls a second Runbook, which waits for the SCVMM job to complete. If the job completed successfully, a third runbook is fired up, which enables the created VM for Hyper-V Replica.


  • SMA must be registered to VM Clouds in the Windows Azure Pack Admin Portal
  • The machine running the SPF (Service Provider Foundation) framework must trust the SSL certificate bound to SMA Web Service Endpoint
  • The Runbooks we want to link with VM Cloud Action events have to be tagged with “SPF”
  • For the whole example to work end to end, you need to deploy the SMA_HVR_Toolkit (SMA Runbooks for Hyper-V Replica). But you can create your own example of course.

The main trick to collect the Job Parameters

SMA Jobs have a variable called $PSPrivateMetaData . (Thanks to Jim Britt, MSFT for this hint). Usually this parameter includes private job data like JobID and JobContextID and you can easily output the content of this variable or work with the members of it. Runbooks jobs, as triggered from VM Cloud action events, have much more information like the target object, the objects parameter, the tenant information etc.


Ok let’s start..

  • Assuming, we already have the HVRToolkit Runbooks imported and Assets configured accordingly
  • Create a new Runbook called Get-VMMJobState
  • Edit the Runbook and paste the following code
WorkFlow Get-VMMJobState

    #Get VMM Connection Object
    $vmmcon = Get-AutomationConnection -Name "SCVMM"

    #Construct the VMM Credential
    $securepw = ConvertTo-SecureString -AsPlainText -String $vmmcon.Password -Force
    $VMMMgmtcred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $vmmcon.Username, $securepw

        Get-SCVMMServer -computername $USING:vmmcon.ComputerName  -Credential $USING:VMMMgmtcred

        While ((Get-SCJob -ID $USING:VMMJobId).Status -eq 'Running')
            $jobProgress = (Get-SCJob -ID $USING:VMMJobId).ProgressValue
            Start-Sleep -Seconds 3

        $JobFinalState = (Get-SCJob -ID $USING:VMMJobId).Status
        Return $JobFinalState
  • Save and Publish the Runbook
  • Next, create a new Runbook called Get-VMCreatedInfo, add the Tag SPF

  • We edit the Runbook and paste the following code
 workflow Get-VMCreatedInfo
    #Get Job Parameters and object information
    $objectname = $PSPrivateMetaData.Name    
    $sourceobj = $PSPrivateMetaData.resourceObject
    $action = $PSPrivateMetaData.Action
    $params = $PSPrivateMetaData.params
    $VMMJobID = $PSPrivateMetaData.VMMJobId

    #Format the parameters and create a hash table with keys and values because we get it as a string first
    #We use an inline script because (add) method to hashtabke is not supported natively in workflows
    $params = $params -split (',') -replace ('"','') -replace ('{','') -replace ('}','')
    $sourceobj = $sourceobj -split (',') -replace ('"','') -replace ('{','') -replace ('}','')
    $params = InlineScript
        $paramhashtable = @{}
        Foreach ($p in $USING:params)
            $key = ($p -split (':'))[0]
            $value = ($p -split (':'))[1]

        #Return the hashtable back to the Workflow
        return $paramhashtable

    #Call Childrunbook to wait for VMM Job Completion
    Write-Output "Calling Child Runbook to wait for VMM Job Completion with JobID: $VMMJobID "
    $JobResult = Get-VMMJobState -VMMJobId $VMMJobID
    If ($JobResult.Value -eq 'Completed')
        Write-Output "Calling Child Runbook to enable Hyper-V Replica for the new VM"
        HVR-Enable-VMReplication -VMName $params.Name -ReplicaServer HV03 -ReplicationHistory 4 -ReplicationVSSHistory 1 -ReplicationFrequency 30
        throw "VMM Job came back with an Error: $JobResult . Aborting Runbook."
  • Next we link the runbook to a VM Cloud Action

So when a tenant creates a new VM for his subscription, Get-CMCreatedInfo is being kicked off Asynchronously. Therefore we wait inside the Runbook, until the SVMM job has completed by synchronously calling “Get-VMMJobState” Runbook. If the job on SVMM completed successfully, we call a child runbook called “HVR-Enable-VMReplication”, which enables Hyper-V Replica for this VM.

The whole process produces an output similar to this one…

The report at the end is also part of the SMA_HVR_Toolkit and produces results like this:

Of course you can do a lot more. This is just a small example to demonstrate the power of SMA.

If you want to know more about SMA in general, I’d recommend to read my SMA White Paper on TechNet Gallery as well as the Microsoft Building Clouds Blog

Happy automating!