How To: Leverage PowerCLI with Process Automation

Blog Post created by James_Keeler on Dec 22, 2014

The premium connector for VMWare is great for certain tasks, but sometimes it isn't flexible enough to do what you need. In those instances, PowerCLI can expose functionality that is not available through the premium connector. For example, let's suppose you need to reboot a virtual guest and wait for a few minutes to ensure the operating system is fully loaded. This simple task could easily be accomplished by using the available Control VM operator from the connector and following it with a Delay operator, but if this is a common task, required in numerous processes, it can be a bit simpler if both steps are consolidated into a single operator.



Before you can create operators that make calls to PowerCLI, it's important to know some of the prerequisites, the most important of which is that these calls must be made using a 32-bit operating environment. Without the ability to instantiate this 32-bit environment, the PowerCLI module will fail to load. Another major concern, as it is with any script or program, is how to process input and output. The input variables should be sufficient to provide the program with enough information that the programmer doesn't need to "hard code" values. This effectively decouples the code from the data and makes the resulting program more reusable, more readable, and more maintainable.


To determine what, and how many, input variables you need it is best to start by looking at the available methods exposed by the PowerCLI cmdlet you plan to use. The idea is to retain as much functionality of the cmdlet as possible. This information can be found in the VMWare vSphere 5.5 Command Line Documentation (https://pubs.vmware.com/vsphere-55/index.jsp). For our example, we are interested in the Restart-VMGuest cmdlet. The documentation shows that this cmdlet exposes the following parameters:


NameTypeDescriptionRequiredPipeline InputDefault Value
GuestVMGuest[]Specifies the virtual machine guest operating systems you want to restart.


true (ByValue)
VMVirtualMachine[]Specifies the virtual machines whose operating systems you want to restart. The specified virtual machines must have VMware Tools installed.falsetrue (ByValue)
ServerVIServer[]Specifies the vCenter Server systems on which you want to run the cmdlet. If no value is given to this parameter, the command runs on the default servers. For more information about default servers, see the description of Connect-VIServer.falsefalse
ConfirmSwitchParameterIf the value is $true, indicates that the cmdlet asks for confirmation before running. If the value is $false, the cmdlet runs without asking for user confirmation.falsefalse$true
WhatIfSwitchParameterIndicates that the cmdlet is run only to display the changes that would be made and actually no objects are modified.falsefalse


From this information, we can see that we need five input parameters for the new operator to be fully functional. Since Confirm and WhatIf are switch parameters that don't really lend themselves to a functional automation script we will eliminate these from our operator. We also notice that Guest and VM are very similar, only differing in that the VM parameter requires VMWare Tools to be loaded, while Guest has no such restriction. Since both parameters are defined as position 1 (this can be determined by reading the help documentation for the cmdlet), it is not necessary to include them both in the operator. We will use the more robust VM parameter which allows wildcards to be used. Thus, we are left with just two parameters: Server and VM.


Coding the Operator

We will use the "Run Script" operator as the base of our new custom operator, using the inline script block to execute our PowerCLI code.


In the Design pane of Process Auto, drop a "Run Script" operator on to your canvas, choose a script extension of ".ps1", enter the user name of password of the user account under which this PowerCLI script will run, and check the box next to "Post output to dataset variable".


Now it's time to write the actual PowerShell code that utilizes PowerCLI. Open the "Inline Script" editor and type the following:

    [Parameter(Mandatory = $true)]
    [string] $Server,
    [Parameter(Mandatory = $true)]
    [string[]] $VM

    #force this to run in 32 bit
    if ($env:Processor_Architecture -ne "x86")
        &"$env:WINDIR\syswow64\windowspowershell\v1.0\powershell.exe" -NonInteractive -NoProfile $myInvocation.Line

    # Connect to vCenter using PowerCLI
    cd "${env:ProgramFiles(x86)}\VMware\Infrastructure\vSphere PowerCLI"
    Add-PSSnapin -Name VMware.VimAutomation.Core | Out-Null
    Connect-VIServer -Server $Server | Out-Null

    # From: http://pubs.vmware.com/vsphere-55/index.jsp#com.vmware.powercli.cmdletref.doc/Restart-VMGuest.html
    $result = Get-VM $VM | Restart-VMGuest

    # Wait for 3 minutes to allow all services to start
    Start-Sleep -Seconds 180

    $result | Format-List *
    Exit 1


Lines 1 - 8 are the parameter definitions. As you can see here, we are requiring values to be passed in through the use of cmdlet binding and validation parameters. If either of the parameters is null or an empty string, the script will fail immediately. The next block of code (lines 12 - 17) forces PowerShell to run in 32-bit mode, a requirement for PowerCLI. Once this new environment is established, we load the PowerCLI module (lines 19 - 22). Then we make the actual call to PowerCLI to get the virtual machine objects (yes, there can be more than one value passed in for $VM since it is defined as a string array) and send those objects through the pipeline to the Restart-VMGuest cmdlet. We store the results of this action in a results variable so that it can be brought back to Process Auto. Lastly, we wait for three minutes while the computer reboots and loads all of its services.


The last thing to do is to add the parameters to the operator as in the image below (replace the values according to your environment).



As you can see, this methodology can be used to leverage any PowerCLI cmdlet in Process Automation, making your processes much more robust and reliable.