Windows Azure Pack, Products, VConnect

How to invoke System Center Orchestrator Runbooks from VConnect?

VConnect Operations Templates, Custom Operation and Orchestrator Runbooks

Introduction:

VConnect Operation Templates™ (OT) define set of steps performed during provisioning and de-provisioning of a Virtual Machine. These templates are simple .JSON files that can be modified by the administrators to add additional custom steps to enable automation of any IT process. VConnect Deployment Engine running on an agent provides a reliable execution framework for these templates along with supporting synchronous and asynchronoussc step executions.

Operation Templates support adding any PowerShell script or .Net code as a step. This scenario takes advantage of that to create a PowerShell script that invokes a Runbook asynchronously and wait until the Runbook completes.

Invoking a Runbook

A quick look at how the flow of events look end to end from Windows Azure Pack Tenant portal to Runbook

è Tenant User Creates VM in Azure Pack Portal

à VConnect Deployment Task is created based on the customized Operation Template™

à VConnect Operation step invokes the custom script that invokes a Runbook

à Microsoft System Center Orchestrator starts Runbook Execution

à VConnect Operation returns with the asynchronous wait status

à VConnect releases any resources held while the runbook is executing asynchronously

à VConnect periodically checks if the Runbook job completed

à Once the Runbook status is marked completed, VConnect moves to next steps

à VConnect Completes all the Steps defined in the Operation Template™

è Virtual Machine is created and marked as Ready for Tenant User

è Admin User can monitor and take corrective actions if required from Windows Azure Pack Admin portal. VConnect Admin extension displays the deployments and Operation steps

Asynchronous Invocation Overview

VConnect Operation Templates™ supports asynchronous operation steps. Asynchronous operation steps, as the name implies, starts executing a long running operation and returns back immediately. This frees VConnect resources. VConnect automatically persists any asynchronous job data returned from the operation, it then periodically calls back the Operation using prescribed async Call back mechanism, passing the previously persisted async job data to check the async completion status.

The sample runbook mentioned below and the sample scripts provided demonstrates the steps and process involved.

Download Sample Scripts and Sample Runbook:

You can download all the sample scripts and runbook example used from here.

Do it Your Self: Invoke Sample Runbook from Operations Templates during VM Provisioning

Step 1: Prepare the Runbook

Scenario:

-        Runbook take a input parameter called ‘Param1’, which is passed from VConnect

-        Runbook executes asynchronously – to simulate this, there is a Sleep added in the .net script activity

-        When completed Runbook will return a result (out) parameter called ‘ResuldData’

Screen 1: Runbook overview

 

Screen 2: Define Returned Data ‘ResultData’ by

-        Right-click the specific runbook tab

-        And click ‘Properties’

-        And choose ‘Returned Data’

-        Click Add button to add the ‘ResultData’

Screen 3: Add a ‘Initialize Data’ activity, click ‘Details’ and add a parameter called ‘Param1’

Screen 4: Add a new ‘Run .Net Script’ activity, click ‘Details’ select the Language Type as ‘PowerShell’ and enter the ‘Script’ and add Published Data as shown below.

Script:

# Define function to add entry to trace log variable

function AppendLog ([string]$Message)

{

$script:CurrentAction = $Message

$script:TraceLog += ((Get-Date).ToString() + "`t" + $Message + " `r`n")

}

 

$Param1 = "\`d.T.~Ed/{97D972DB-472C-4E6C-B6EA-238F4EBC0B87}.{957EF51D-9912-4454-84B6-C83854120E6A}\`d.T.~Ed/"

AppendLog "Parameter Received: [$Param1]"

start-sleep -seconds 25

 

$ResultData = "Runbook Processed VM: \`d.T.~Ed/{97D972DB-472C-4E6C-B6EA-238F4EBC0B87}.{957EF51D-9912-4454-84B6-C83854120E6A}\`d.T.~Ed/"

 

Published Data.

 

Screen 5: Add a ‘Return Data’ activity and ensure that in ‘Details’ ‘ResultData’ is seen as below.

 

Finally test the runbook by executing in Runbook Tester and see that the result

Expand the ‘Show Details’ for Activity Name ‘Run .Net Script’ and check that ‘ResultData’ is set.

Here we will see a sample script that starts execution of Orchestrator runbook and returns immediately. This script has the sample methods for handling asynchronous calls from VConnect.

Before going into the main script, you need to get the Runbook Id that you want to invoke from your environment and the Param Id. If you have imported the sample runbook provided, then the Param Id most likely stays the same as used in the script, but you need to get the Runbook Id from your Orchestrator.

Find out the runbook id and param id

Use the ‘OrchestratorServiceModule.psm1’ provided along with the sample scripts.

$scomServer = 'SCOM'

$scomUserDomain = 'wapdemo'

$scomUserName = 'administrator'

$scomUserPassword = 'XXXXXXXXX'

 

 

Import-Module C:\inetpub\MgmtSvc-CloudAssert-VConnect\OrchestratorServiceModule.psm1

 

if (!$?)

{

$errorMessage = "Failure loading the module.`nError Message:`n"

$errorMessage += $error[0].ToString()

$result = @{

IsSuccess = $false

Message = "Error: " + $errorMessage

ErrorCode = 0

}

New-Object PSObject -Property $result

return

}

 

 

$creds = Get-Credentials $scomUserDomain $scomUserName $scomUserPassword

$url = Get-OrchestratorServiceUrl -server $scomServer

 

$runbook = Get-OrchestratorRunbook -serviceurl $url -credentials $creds -RunbookPath "\ProcessAndReturnData" -Verbose

$rbId = $runbook.Id

$inputParam = $runbook.Parameters | Where-Object {$_.Direction -eq "In" }

$paramName = $inputParam.Name

$paramId = $inputParam.Id

 

 

 

SampleInvokeRunbookWithAsync.PS1

Following script has comments inline and self-explanatory method names. The starting point of the script is found at the bottom, where either the  ‘ProcessAsyncCallback’ or ‘ProcessMain’ is called depending on whether VConnect has called the script with ‘IsAsyncCallback’ or not.

Another important snippet to note is the result format. For Completion results (Success or Failure) the format must be like the following:

$resultDataJson = ConvertTo-Json -InputObject $resultData -Compress

$result = @{

IsSuccess = $true

Message = $message

Details = $resultDataJson

ErrorCode = 0

}

 

For asynchronous results it must of the following format:

$asyncResultDataJson = ConvertTo-Json -InputObject $resultData -Compress

$asyncResult = @{

IsSuccess = $true

IsWaitingForAsyncCompletion = $true

Message = "Completed async. " + $asyncResultDataJson

ErrorCode = 0

Details = $asyncResultDataJson

}

 

Note: It is important to use ‘-Compress’ in ConvertTo-Json. And the ‘Details’ field can only contain string results.

 

###########################################################################

# SampleInvokeRunbookWithAsync.PS1

###########################################################################

 

## Following parameters will be passed by VConnect and available for your script

 

#$HostServerName = @(HostServerName)

#$HostServerPort = @(HostServerPort)

#$UserName = @(UserName)

#$Password = @(Password)

#$Datacenter = @(Datacenter)

#$Cluster = @(Cluster)

#$HostName = @(HostName)

#$SubscriptionId = @(SubscriptionId)

#$VMName = @(VMName)

#$ResourcePoolName = @(ResourcePoolName)

#$FolderName = @(FolderName)

###########################################################################

 

$scomServer = '[YOUR ORCHESTRATOR SERVER]'

$scomUserDomain = '[YOUR DOMAIN]'

$scomUserName = '[YOUR ADMIN USER]'

$scomUserPassword = '[YOUR PASSWORD]'

 

# This is for the sample runbook. Use your Runbook Guid

$runBookId = [guid]"32cee37d-bada-4cc6-9f69-bc85e0e08100"

# This is for the sample runbook param. you should look up for your runbook in the $runbook.Parameters

$param1GUID = "957ef51d-9912-4454-84b6-c83854120e6a"

 

Import-Module C:\inetpub\MgmtSvc-CloudAssert-VConnect\OrchestratorServiceModule.psm1

 

if (!$?)

{

$errorMessage = "Failure loading the module.`nError Message:`n"

$errorMessage += $error[0].ToString()

$result = @{

IsSuccess = $false

Message = "Error: " + $errorMessage

ErrorCode = 0

}

New-Object PSObject -Property $result

return

}

 

 

function CheckJobStatus()

{

param([guid] $JobId,[int] $MaxIteration)

$runBookjob = Get-OrchestratorJob -JobId $JobId -ServiceUrl $url -Credentials $creds

$iterationCount = 0;

while($runBookjob -ne $null -and !(IsCompleted $runBookjob.Status) -and ($iterationCount++ -lt $MaxIteration))

{

start-sleep -seconds 10

$runBookjob = Get-OrchestratorJob -JobId $JobId -ServiceUrl $url -Credentials $creds

if($runBookjob -eq $null -or ($_ -ne $null -and $_.Exception -ne $null))

{

return $null;

}

 

if(IsErrorStatus($runBookjob.Status))

{

return $runBookjob;

}

}

return $runBookjob;

}

 

function IsErrorStatus($RunBookstatus)

{

return $RunBookstatus.StartsWith("Error") -or $RunBookstatus.StartsWith("Fail") -or $RunBookstatus.StartsWith("Cancelled");

}

 

function IsSuccessStatus($RunBookstatus)

{

return $RunBookstatus.Equals("Completed");

}

 

function IsCompleted($RunBookstatus)

{

$isSuccess = IsSuccessStatus $RunBookstatus;

$isFailed = IsErrorStatus $RunBookstatus;

return ($isSuccess -or $isFailed);

}

 

function GetErrorResult($message, $resultData)

{

$resultDataJson = ConvertTo-Json -InputObject $resultData -Compress

$result = @{

IsSuccess = $false

Message = $message

Details = $resultDataJson

ErrorCode = 1

}

return $result

}

 

function GetSuccessResult($message, $resultData)

{

$resultDataJson = ConvertTo-Json -InputObject $resultData -Compress

$result = @{

IsSuccess = $true

Message = $message

Details = $resultDataJson

ErrorCode = 0

}

return $result

}

 

function GetAsyncResult($resultData)

{

$asyncResultDataJson = ConvertTo-Json -InputObject $resultData -Compress

$asyncResult = @{

IsSuccess = $true

IsWaitingForAsyncCompletion = $true

Message = "Completed async. " + $asyncResultDataJson

ErrorCode = 0

Details = $asyncResultDataJson

}

return $asyncResult;

}

 

function GetAsyncDataRunBookJobId()

{

if($asyncStateJson -ne $null) {

$asyncInput = ConvertFrom-Json -InputObject $asyncStateJson

return [guid]$asyncInput.RunBookJobId;

}

 

return $null

}

 

function GetResultToReturn($job)

{

if($job -eq $null)

{

$msg = "Error: Runbook execution didnt happen." + $error[0]

$errorResult = GetErrorResult $msg

return $errorResult;

}

if(IsErrorStatus $job.Status)

{

$errorResult = GetErrorResult "Error: Runbook error."

return $errorResult;

}

if(IsSuccessStatus $job.Status)

{

$ri=Get-OrchestratorRunbookInstance $job -Credentials $creds

 

# NOTE: change these based on your Runbook Out Parameters. This sample runbook publishes 1 out string param

$params=@(Get-OrchestratorRunbookInstanceParameter -RunbookInstance $ri -Credentials $creds)

$resultOut = $params | where {$_.Name -eq 'ResultData'}

$resultData = @{ ResultData = $resultOut[0].Value }

$resultDataJson = ConvertTo-Json -InputObject $resultData -Compress

$message = "Job: " + $job.id + ".Status: " + $job.Status + ". Result: " + $resultOut[0].Value

$successResult = GetSuccessResult $message $resultData;

return $successResult;

}

if(!(IsCompleted $job.Status))

{

$asyncResultData = @{ RunBookJobId = $job.Id }

 

$asyncResult = GetAsyncResult $asyncResultData;

return $asyncResult;

}

}

 

function ProcessAsyncCallback()

{

$RunBookJobId = GetAsyncDataRunBookJobId

 

if($RunBookJobId -ne $null) {

$job = CheckJobStatus $RunBookJobId 3

$result = GetResultToReturn $job;

New-Object PSObject -Property $result

return

}

else

{

$errorResult = GetErrorResult "Error: Async Call Back did not receive the required input param: RunBookJobId"

New-Object PSObject -Property $errorResult

return

}

}

 

function ProcessMain()

{

# Use runbook id

$runbook = Get-OrchestratorRunbook -serviceurl $url -runbookid $runBookId -credentials $creds

if ($runbook -ne $null)

{

$childParams = @{ $param1GUID=$VMName }

$job = Start-OrchestratorRunbook -runbook $runbook -credentials $creds -Parameters $childParams

if ($job -ne $null)

{

$jobId = [guid]($job.Id);

$job = CheckJobStatus $jobId 3;

$result = GetResultToReturn $job;

}

else

{

if($_ -ne $null -and $_.Exception -ne $null)

{

$response = $($_.Exception.Response)

if ($response -ne $null -and $response.ContentLength -gt 0)

{

$reader = [IO.StreamReader] $response.GetResponseStream()

$output = $reader.ReadToEnd()

$reader.Close()

}

}

$msg = $error[0] | out-string

$result = GetErrorResult "Exception while calling execute Runbook: " + $rbarray.Name + ". Errors: " + $output + '. ' + $msg;

}

}

else

{

$msg = $error[0] | out-string

$result = GetErrorResult "Exception while getting Runbook. Errors: " + $msg;

}

return New-Object PSObject -Property $result

}

 

### Main Entry ###

 

# get credentials (set to $null to UseDefaultCredentials)

$creds = Get-Credentials $scomUserDomain $scomUserName $scomUserPassword

# create the base url to the service

$url = Get-OrchestratorServiceUrl -server $scomServer

 

if($IsAsyncCallback)

{

ProcessAsyncCallback

}

else

{

ProcessMain

}

###################

 

 

 

You can test this script standalone from a PowerShell windows to ensure that it works.

Update VConnect Operation Template to add Script Op

Now that we have the Runbook, and a script to execute the runbook, next step is to add an Operation Step to the VConnect Operation Template that will invoke the script.

Open the template file: C:\inetpub\MgmtSvc-CloudAssert-VConnect\bin\Templates\VCenterStandAloneVMCreateTemplate.json

Add the following step:

-        Make sure the script name matches the sample script file you have created

-        You can add the step at the starting of Operations array for test, but practically it can be added at any place

{

"Name": "VMScriptOp",

"Label": "Invoke Custom Operation",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3,

"Params": {

"IsSkipIfFileNotExist": true,

"scriptfilename": "SampleInvokeSMARunbookWithAsync.ps1"

}

}

 

The entire template will look like the following:

{

"Version": "1.7.1",

"Name": "DeployVMTemplate",

"Operations": [

{

"Name": "VMScriptOp",

"Label": "Invoke Custom Operation",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3,

"Params": {

"IsSkipIfFileNotExist": true,

"scriptfilename": "SampleInvokeSMARunbookWithAsync.ps1"

}

},

{

"Name": "CreateResourcePoolOp",

"Label": "Create Resource Pool",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3

},

{

"Name": "DeployVMFromTemplateOp",

"Label": "Clone and Create VM",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3

},

{

"Name": "GetNetworkSettingsOp",

"Label": "Add Default Network Settings",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3

},

{

"Name": "CustomizeVMOp",

"Label": "Customize VM",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3,

"Params": {

"NicSettings": ""

}

},

{

"Name": "VMScriptOp",

"Label": "Execute AfterVMCustomizationScript.ps1",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3,

"Params": {

"IsSkipIfFileNotExist": true,

"scriptfilename": "AfterVMCustomizationScript.ps1"

}

},

{

"Name": "FinishCreateVMOp",

"Label": "Finalize and Mark VM Ready",

"Provider": "VConnectOperationsProvider",

"MaxRetryAttempts": 3

}

]

}

 

Save the changes and now everything is set for your custom step to be invoked everytime a tenant user creates a new VM.

View Deployments and Operation Steps from Admin Portal

Admin Portal à VConnect à Deployments

Hope you have enjoyed this post. If you have any questions please add it in the comments section, we will get back to you.