Refactoring PowerCLI scripts or functions for PowerActions

If Carlsberg is “probably the best beer in the world“, then PowerActions is more than probably the best VMware fling in the world.

It brings PowerCLI automation goodness directly within the vSphere Web Client in 2 ways : a PowerShell/PowerCLI console and the ability the extend the Web Client context menu actions with your custom actions based on your PowerCLI scripts.

This article is not intended as a general how-to guide for PowerActions, everything you need is here : presentation, video tutorial, documentation and installer download links.

In this article, we are going to focus on how to modify existing scripts or functions to add them as context menu actions in the Web Client.

Refactoring a script

 
Let’s say we have a basic PowerCLI script (a .ps1 file) to list all the VIBs installed on a ESXi host, its content looks like this :

param(
    [VMware.VimAutomation.ViCore.Impl.V1.Inventory.VMHostImpl]$VMhost
)

$EsxCli = Get-EsxCli -VMHost $VMhost
$EsxCli.software.vib.list() | Select-Object -Property Name,CreationDate,InstallDate,Version

 
We want the same functionality when we right-click on a ESXi host in the Web Client and we want to play with it like it’s a just-unboxed toy from the Christmas tree. So, let’s get to it.

From the Web Client home page, we click “PowerCLI Scripts” and we see this :

PowerCLI Scripts

We click on the icon with a green “+” to add a new script to the PowerActions script library. Then, we need to specify the type of object(s) that our custom action can target. This is very important because this defines the type of PowerCLI object that the script takes as input parameter. Our script targets ESXi hosts so we choose “Host”.

To make our custom action even more powerful, we can potentially act on multiple objects (of the same type) at once. In this case, we would check the box “Expects multiple objects”. As we can see above, our original script expect only one VMHost object so we don’t need to do this.

Argument type
 
In the next screen, we give our script a name and a optional description. More importantly, we choose an “Output format” : “Action” or “Report”. Essentially, we choose “Action” for scripts performing an action on (or modifying) one or more vSphere object(s) and we choose “Report” for scripts obtaining information (similar to a Get-* cmdlet). In our case, it obtains a list of VIBs, so we choose “Report”.

What we are presented with in the next screen is the basic structure of the script which will be used by PowerActions :

Add script

The most important point here is that the vSphere object on which we right-click in the Web Client will be used as the input parameter called vParam. In other words, the target of the context menu action will be stored as the variable $vParam in the script. Don’t try to change the parameter name, it has be $vParam to work with PowerActions.

You might be under the impression that we are limited to a single parameter, but it is not the case. Let’s add -Vendor as a mandatory parameter to filter the VIBs on their vendor. We will see later, when we run the custom action in the Web Client that we are prompted to enter a value for this parameter.

Here is our final PowerActions script :

<#
.MYNGC_REPORT
#>

param
(
   [Parameter(Mandatory=$true)]
   [VMware.VimAutomation.ViCore.Types.V1.Inventory.VMHost]
   $vParam,
   [Parameter(Mandatory=$true)]
   [string]$Vendor
);

$EsxCli = Get-EsxCli -VMHost $vParam
$VibList = $EsxCli.software.vib.list()
$FilteredVibList = $VibList | Where-Object { $_.Vendor -eq $Vendor }
$FilteredVibList | Select-Object -Property Name,CreationDate,InstallDate,Version

 
Now, let’s run it !
To do that, we right-click on a ESXi host in the Web Client, at the bottom of the context menu, we choose “PowerCLI”, and then “Execute Script” :

Execute Script
 
In the next screen we select our new script and OK. Now, we are prompted to enter values for any mandatory parameter (other than vParam) :

Vendor Parameter

The Web Client displays the result in a nice table :

Report Result
 

Refactoring a function

 
Now, let’s say we are good PowerShell citizens and we encapsulate our PowerCLI tools as advanced functions to facilitate reusability. How can we reuse our existing PowerCLI functions with PowerActions ?
It is very straightforward.

As an example, we are going to use the function Audit-vCenterOperation, available here. The idea is to be able to right-click a vSphere object in the Web Client to get a list of events and operations related the selected object. This could be a workaround for the “Export Events” feature not working well in the Web Client (http://kb.vmware.com/kb/2071612).

Looking at the param(...) block, we see that it has many parameters :

param(
    [string]$VIServer = "localhost",
    [Parameter(ValueFromPipeline = $True,Position=0)]
    [ValidateScript({ $($_[0].GetType()).Namespace -eq "VMware.VimAutomation.ViCore.Impl.V1.Inventory" })]
    $Entity,
    [string]$Username,
    [datetime]$Start,
    [datetime]$Finish,
    [ValidateSet("Create","Reconfigure","Remove","DRS","HA","Password","Migration","Snapshot","Power","Alarm","Datastore","Permission")]
    [string]$OperationType
    )

 
Fortunately, none of these parameters is mandatory so we can leave them as they are.

Looking at the line just above “$Entity,“, we see that the parameter Entity is designed to work with any type of vCenter inventory object. A given PowerActions script can take only one object type as input parameter, so we’ll need to choose what kind of vSphere object we want to target with our custom action. Let’s go for VMs.

So, we add a new script in PowerActions and this time, we choose “Virtual Machine” as the target type. For the output format, we select “Report” because the script is getting information, not modifying anything.

Again, in the next screen, we are presented with a blank script structure.
At the end of it, we add the whole function definition, unchanged. By itself, this whole function {...} block does nothing, it merely defines the function. So, to make our script actually run the code encapsulated in our function, we need to call the function.

Remember, the VM we right-click in the Web Client will be stored by PowerActions in the variable $vParam. So, all we have to do is to feed $vParam as the value for the -Entity parameter of our function :

<#
.MYNGC_REPORT
#>

param
(
   [Parameter(Mandatory=$true)]
   [VMware.VimAutomation.ViCore.Types.V1.Inventory.VirtualMachine]
   $vParam
);

function Audit-vCenterOperation {

    # Content of the existing function

}
Audit-vCenterOperation -Entity $vParam

 
That’s it.
Now, we can run the custom action in the Web Client.
Aha, we see that our friend “RogueAdmin” has reconfigured the VM named “New-VM”.

Audit result
 
By the way, when we have this “Report Results” page, we can resize, reorder and sort the columns to our heart’s content.

Leave a Reply

Your email address will not be published. Required fields are marked *