Interacting with VMware vCO and the Rest API using PowerShell – getting a list of workflows

Recently I needed to get a list of VMware vCO workflows from a remote server using PowerShell. A colleague of mine pointed me in the right direction by providing me with a URL to access the vCO Rest API on, as well as letting me know what I needed to send in order to authenticate.

To connect and retrieve content back in the PowerShell example below, we’ll need to:

  • Access the Rest API URL for Orchestrator using a web client object
  • Send basic authentication in the header of our request

Notes:

One thing I did notice is that when you use your web browser to test the URL, the result is returned to you as XML, however when I used a web client object in PowerShell, I got a result returned to me in JSON. The PowerShell script below is therefore tailored to interpret the result as JSON. This being so, you’ll need to make sure you are using PowerShell 3.0 or above, as the ConvertFrom-Json cmdlet is only available using PowerShell 3.0 and above.

When sending your authentication details with the web client object request, make sure your username/password combo are used in this format:

Authorization: Basic username:password

This means that your header you add to your web client option, should be added with the string as per the above, but with the username:password part encoded using base64. The script below takes this all into account, and all you need to do is provide your username and password for vCenter Orchestrator to the PowerShell function, it will handle the base64 encoding and passing of the values to the web client itself.

Anyway, enough of that, let us get onto the actual script itself. This is presented as a PowerShell function. Load it into your session (copy-paste) or add it to your PS profile for future use. Apologies for the formatting – Syntax Highlighter really messes with the formatting and nice clean indentation I normally have in my scripts!

Here is a direct download of the PowerShell script if the script paste below doesn’t work for you:
[wpdm_file id=31]

 

Function Get-VcoWorkflow() 
{

<#
.SYNOPSIS
Fetches vCO Workflow information and details from a vCenter Orchestrator server

.DESCRIPTION
Fetches vCO Workflow information and details from a vCenter Orchestrator server

.PARAMETER Username
Username for the vCO server

.PARAMETER Password
Password for the vCO server

.PARAMETER Server
The vCO server hostname or IP address

.PARAMETER PortNumber
The port to connect on

.EXAMPLE
PS F:\> Get-VcoWorkflow -Username Sean -Password mypassword -Server 192.168.60.172 -PortNumber 8281

.LINK

http://www.shogan.co.uk

.NOTES
Created by: Sean Duffy
Date: 30/03/2014
#>

[CmdletBinding()]
param(
[Parameter(Position=0,Mandatory=$true,HelpMessage="Specify your vCO username.",
ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true)]
[String]
$Username,

[Parameter(Position=1,Mandatory=$true,HelpMessage="Specify your vCO password.",
ValueFromPipeline=$false,ValueFromPipelineByPropertyName=$true)]
[String]
$Password,

[Parameter(Position=2,Mandatory=$true,HelpMessage="Specify your vCO Server or hostname.",
ValueFromPipeline=$false,ValueFromPipelineByPropertyName=$true)]
[String]
$Server,

[Parameter(Position=2,Mandatory=$true,HelpMessage="Specify your vCO Port.",
ValueFromPipeline=$false,ValueFromPipelineByPropertyName=$true)]
[ValidateRange(0,65535)] 
[Int]
$PortNumber
)

process 
{
$Report = @() | Out-Null

# Craft our URL and encoded details note we escape the colons with a backtick.
$vCoURL = "https`://$Server`:$PortNumber/vco/api/workflows"
$UserPassCombined = "$Username`:$Password"
$EncodedUsernamePassword = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($UserPassCombined))
$Header = "Authorization: Basic $EncodedUsernamePassword"

# Ignore SSL warning
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}

# Create our web client object, and add header for basic authentication with our encoded details
$wc = New-Object System.Net.WebClient;
$wc.Headers.Add($Header)

# Download the JSON response from the Restful API, and convert it to an object from JSON.
$jsonResult = $wc.downloadString($vCoURL)
$jsonObject = $jsonResult | ConvertFrom-Json

# Create a blank Report object array
$Report = @()

# Iterate over the results and transform the key/value pair like formatting to a proper table.
# Note I use a hashtable to populate a new PSObject with properties, using values found in the original JSON result
foreach ($link in $jsonObject.link)
{
	$kvps = $link.attributes
	$HashTable = @{}
	$kvps | foreach { $HashTable[$_.name] = $_.value } # foreach item in the link object, populate the hashtable
	$NewPSObject = New-Object PSObject -Property $HashTable # Create a new PSObject and populate the properties/values using our hashtable

	# Add our populated object to our Report array
	$Report += $NewPSObject
}

return $Report

}
}

I hope that this script comes in handy, and gives you an idea as to how you can retrieve and convert data from vCO and its RESTful API for use in PowerShell 🙂

Results example after running the Function:
get-vcoworkflow-results

 

vExpert recognition for 2014

I am very honored to have received VMware vExpert recognition for 2014 (the third year running now). Keeping this blog updated with new content has proven a difficult task as of late with many more work and personal commitments on the go, in addition to a second blog I started relating to my hobby of game development (and coding).

Hopefully I can maintain momentum here on Shogan.tech and keep posting content related to IT, Automation, cloud, virtualisation and scripting though!

Congratulations to all the vExperts for 2014 (both new and returning) then – it is great to see such an enthusiastic community out there!

Upgrading to VMware Fusion 6.x from 5.x – Windows 8 UI font/size change strangeness

This is a very quick post today, but relates to an issue I had after upgrading my VMware Fusion install from 5.x to 6.0.2.

I am running a Windows 8 SP1 guest VM for development purposes on my mac, and right after upgrading and booting my Windows VM noticed this. The issue is that all the Windows UI elements – icons, text, etc look humongous on my 1920×1200 LCD monitor. The macbook’s LCD itself looked OK though. You can’t really see it that well in the screenshot below, but trust me, the section below with a few icons was about a quarter of my screen.

resolution-issue

I knew this was a new setting that had somehow been toggled in Fusion since the upgrade, so I had a quick look around and found it. To disable this feature, go to your Virtual Machine Settings -> Display, and untick “Automatically adjust user interface size in Windows”.

automatically-adjust-user-interface-size-windows

Fusion will prompt you to logout of your current user session in the Windows VM. After logging back in again, things should be back to normal.

Hope that saves someone 15 minutes of looking for the cause in the future!

Three PowerCLI scripts for information gathering – VMs, Hosts, etc

 

I was on a vSphere upgrade review engagement recently, and part of this involved checking hardware and existing vSphere VI was compatible with the targeted upgrade.

To help myself along, I created a few PowerCLI scripts to help with information gathering to CSV for the VI parts – such as Host Versions, build numbers, VMware tools and hardware versions, etc… These scripts were built to run once-off, simply either by copy/pasting them into your PowerCLI console, or by running them from the PowerCLI console directly.

They can easily be adapted to collect other information relating to VMs or hosts. To run, just launch PowerCLI, connect to the VC in question (using Connect-VIServer) and then copy/paste these into the console. The output will be saved to CSV in the directory you were in. Just make sure you unblock the zip file once downloaded if you execute them directly from PowerCLI, otherwise the copy/paste option mentioned above will work fine too.

There are three scripts bundled in the zip file:

  • Gather all hosts under the connected vCenter server and output Host name, Model and Bios version results to PowerCLI window and CSV
  • Gather all hosts under the connected vCenter server and output Host name, Version and Build version results to PowerCLI window and CSV
  • Gather all hosts under the specified DC and output VM name and hardware version results to PowerCLI window and CSV

Short and simple scripts, but hopefully they will come in handy to some. As mentioned above, these can easily be extended to fetch other information about items in your environment. Just take a look at the way existing info is fetched, and adapt from there. Also remember that using | gm (get-member) on objects in PowerShell is your friend – you can discover all the properties and methods on PowerShell objects by using this, and use those to enhance your reports/outputs in your scripts.

[wpdm_package id=’2025′]

 

Updated: Get VMware tools versions by ESXi host version – a PowerCLI function to map tools version codes to readable version numbers

Quite some time ago I created a PowerCLI function to help me determine VMware Tools versions of queried VMs using PowerCLI. The tools version is returned as a 4 digit number by the vSphere API, and subsequently, so does PowerCLI. This makes determining VMware Tools versions at a glance, a bit of a hassle.

The original function was able to output Tools versions up to ESXi 4.1 u1 or u2, and this week was the first time I had a good use case for this script. I needed more up to date mappings, so I have updated the function to work with VMware tools versions all the way up to ESXi 5.5 now.

Here is the latest script:

# Mapping file found at: http://packages.vmware.com/tools/versions

Function Get-VMToolsMapped() {

 Get-VMToolsMapped -VM MYVMNAME

.EXAMPLE
PS F:\> Get-VMToolsMapped MYVMNAME

.EXAMPLE
PS F:\> Get-VM | Get-VMToolsMapped

.EXAMPLE
PS F:\> Get-Cluster "CLUSTERNAME" | Get-VM | Get-VMToolsMapped

.LINK
http://www.shogan.co.uk

.NOTES
Created by: Sean Duffy
Date: 05/02/2014
#>

[CmdletBinding()]
param(
[Parameter(Position=0,Mandatory=$true,HelpMessage="Specify the VM name you would like to query VMware Tools info for.",
ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true)]
[String]
$VM
)

process {

$Report = @()
New-VIProperty -Name ToolsVersion -ObjectType VirtualMachine -ValueFromExtensionProperty 'config.tools.ToolsVersion' -Force

$VMInfo = Get-VM $VM | Select Name, ToolsVersion
Switch ($VMInfo.ToolsVersion) {
	9344 {$ESXMapping = "esx/5.5"}
	9226 {$ESXMapping = "esx/5.1u2"}
	9221 {$ESXMapping = "esx/5.1u1"}
	9217 {$ESXMapping = "esx/5.1"}
	9216 {$ESXMapping = "esx/5.1"}
	8396 {$ESXMapping = "esx/5.0u3"}
	8395 {$ESXMapping = "esx/5.0u3"}
	8394 {$ESXMapping = "esx/5.0u2"}
	8389 {$ESXMapping = "esx/5.0u1"}
	8384 {$ESXMapping = "esx/5.0"}
	8307 {$ESXMapping = "esx/4.1u3"} 
	8306 {$ESXMapping = "esx/4.1u3"} 
	8305 {$ESXMapping = "esx/4.1u3"} 
	8300 {$ESXMapping = "esx/4.1u2"}
	8295 {$ESXMapping = "esx/4.1u1"}
	8290 {$ESXMapping = "esx/4.1"}
	8289 {$ESXMapping = "esx/4.1"}
	8288 {$ESXMapping = "esx/4.1"}
	8196 {$ESXMapping = "esx/4.0u4 or esx/4.0u3"}
	8195 {$ESXMapping = "esx/4.0u2"}
	8194 {$ESXMapping = "esx/4.0u1"}
	8193 {$ESXMapping = "esx/4.0"}
	7304 {$ESXMapping = "esx/3.5u5"}
	7303 {$ESXMapping = "esx/3.5u4"}
	7302 {$ESXMapping = "esx/3.5u3"}
	default {$ESXMapping = "Unknown"}
	}

$row = New-Object -Type PSObject -Property @{
   		Name = $VMInfo.Name
		ToolsVersion = $VMInfo.ToolsVersion
		ESXMapping = $ESXMapping
	}
$Report += $row
return $Report

}
}

If you have any issues copying and pasting the script from this post, here is a direct download you can use too:

[download id=”28″]