Author: Ravi C Kolandaiswamy/Wednesday, September 30, 2015/Categories: Windows Azure Pack, Products, VConnect
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.
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
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.
You can download all the sample scripts and runbook example used from here.
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.
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
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
IsSuccess = $true
Message = $message
Details = $resultDataJson
For asynchronous results it must of the following format:
$asyncResultDataJson = ConvertTo-Json -InputObject $resultData -Compress
$asyncResult = @{
IsWaitingForAsyncCompletion = $true
Message = "Completed async. " + $asyncResultDataJson
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"
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
if($runBookjob -eq $null -or ($_ -ne $null -and $_.Exception -ne $null))
return $null;
if(IsErrorStatus($runBookjob.Status))
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)
ErrorCode = 1
return $result
function GetSuccessResult($message, $resultData)
function GetAsyncResult($resultData)
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."
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 }
$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;
function ProcessAsyncCallback()
$RunBookJobId = GetAsyncDataRunBookJobId
if($RunBookJobId -ne $null) {
$job = CheckJobStatus $RunBookJobId 3
$result = GetResultToReturn $job;
else
$errorResult = GetErrorResult "Error: Async Call Back did not receive the required input param: RunBookJobId"
New-Object PSObject -Property $errorResult
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;
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;
$result = GetErrorResult "Exception while getting Runbook. Errors: " + $msg;
return New-Object PSObject -Property $result
### Main Entry ###
# get credentials (set to $null to UseDefaultCredentials)
# create the base url to the service
if($IsAsyncCallback)
ProcessAsyncCallback
ProcessMain
###################
You can test this script standalone from a PowerShell windows to ensure that it works.
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": "CreateResourcePoolOp",
"Label": "Create Resource Pool",
"MaxRetryAttempts": 3
"Name": "DeployVMFromTemplateOp",
"Label": "Clone and Create VM",
"Name": "GetNetworkSettingsOp",
"Label": "Add Default Network Settings",
"Name": "CustomizeVMOp",
"Label": "Customize VM",
"NicSettings": ""
"Label": "Execute AfterVMCustomizationScript.ps1",
"scriptfilename": "AfterVMCustomizationScript.ps1"
"Name": "FinishCreateVMOp",
"Label": "Finalize and Mark VM Ready",
]
Save the changes and now everything is set for your custom step to be invoked everytime a tenant user creates a new VM.
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.
Number of views (18471)/Comments (7)
Roy
5/17/2018 4:13 AM
I've read and I have bookmarked your article since this site contains significant data in it. I am truly content with articles quality and introduction. You're composing challenge is look so pleasant to me and I trust this dissertation writing service likewise exceptionally modest bunch to every one of you for your writing help. Thank you for sharing this post, I am looking forward to see more article from you.
custom essay
10/11/2018 3:07 AM
I was looking for this answer about invoking system center orchestration. There was a doubt in my mind preventing me to go forward. Great explanation and I really owe you one.
Essay
10/18/2018 3:27 AM
There HAD to be warnings heretofore. So for me this isn't at all about circumcision. It is about her lying and deceiving OP, about her playing extremely imbecilic amusements. The circumcision is only a manifestation.
minesweeper 10/29/2018 4:29 AM
10/29/2018 4:29 AM
Play online free minesweeper,this is a classic original card game,now this is right time so play with any waste time,i hope you enjoyed free online minesweeper games,i have play the different many mode game,but minesweeper is batter.
essay
11/3/2018 6:59 AM
This solution is very helpful for revoking for central system from users can easily handle the required features. People get lots of benefits with use of career booster resume online that is written according to professional bases.
google.com/
11/13/2018 10:18 AM
This is a great inspiring article.I am pretty much pleased with your good work.You put really very helpful information
game
11/24/2018 12:04 AM
the nice game